pylearnspec

Python parser and validator for the LearnSpec suite of open standards:

Install

pip install pylearnspec

Quick start

Parse a QuizMD file

from pylearnspec import parse_quiz

with open("my-quiz.quiz.md") as f:
    quiz = parse_quiz(f.read())

print(quiz.title)
print(f"{len(quiz.questions)} questions")

for q in quiz.questions:
    print(f"  Q{q.number} ({q.q_type}): {q.title}")

Parse a LearnMD file

from pylearnspec import parse_learn

with open("my-lesson.learn.md") as f:
    lesson = parse_learn(f.read())

print(lesson.title)
for section in lesson.sections:
    print(f"  {'#' * section.depth} {section.title}")

Validate

from pylearnspec import validate_quiz, validate_learn

# Lenient mode (default)
diagnostics = validate_quiz(content)

# Strict mode (for CI)
diagnostics = validate_quiz(content, strict=True)

for d in diagnostics:
    print(f"[{d.level}] {d.message}")

JSON output

Both Quiz and Lesson objects have a .to_dict() method for JSON serialization:

import json
from pylearnspec import parse_quiz

quiz = parse_quiz(content)
print(json.dumps(quiz.to_dict(), indent=2))

Supported features

QuizMD

• Frontmatter (Level 1) and per-question quiz blocks (Level 2)
• Question types: MCQ, multi-select, true/false, open answer, match, order
• Per-choice and global feedback ([!correct], [!incorrect])
• !import directives
• Validation (lenient and strict modes)

LearnMD

• Frontmatter metadata (lang, estimated_time, tags)
• Section hierarchy (## modules, ### lessons)
• Special fenced blocks: summary, example, note, tip, warning, quiz, etc.
• GFM callout detection (> [!tip], > [!warning], etc.)
• !import directives (.learn.md and .quiz.md)
• Validation (lenient and strict modes)

AnimMD

• Frontmatter (pace, captions, badges) and the bind intent layer ({node: A}, {edge: [A, B]}, {label: "text"})
• One ## heading per step; the five verbs show, hide, draw, focus, pulse
• Companion blocks in DiagramMD catalogues (```anim for:slug), preserved through parse_diagram/serialize_diagram round-trips (orphans included)
• Validation (lenient and strict modes) and deterministic serialization

LearnSpec suite (v0.2)

Every format follows the same shape:

• YAML frontmatter with the universal fields (lang required, license, spec_version, created, updated)
• Cross-format directives !import, !ref, !checkpoint (when applicable) — see pylearnspec.common.directives
• parse_<format>(content) returns a typed dataclass with a .to_dict() method
• validate_<format>(content, strict=False) returns a list of Diagnostic(level, message)

Development

pip install -e ".[dev]"
pytest

License

MIT