pylearnspec 0.4.0__tar.gz

pylearnspec-0.4.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.venv/
+venv/
+uv.lock
+.env
+*.so
+.coverage
+htmlcov/

pylearnspec-0.4.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.2
+Name: pylearnspec
+Version: 0.4.0
+Summary: Python parser and validator for the LearnSpec suite (LearnMD, QuizMD, FlashMD, TrackMD, DiagramMD, MediaMD, GlossaryMD, BadgeMD, CertMD, NuggetMD)
+Author-email: learnspec <hello@learnspec.org>
+License: MIT
+Project-URL: Homepage, https://github.com/learnspec/pylearnspec
+Project-URL: Repository, https://github.com/learnspec/pylearnspec
+Keywords: learnspec,quizmd,learnmd,flashmd,trackmd,diagrammd,mediamd,glossarymd,badgemd,certmd,nuggetmd,parser,education,assessment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+
+# pylearnspec
+
+Python parser and validator for the [LearnSpec](https://learnspec.org) suite of open standards:
+
+| Format | API |
+|---|---|
+| **LearnMD** — instructional content | `parse_learn`, `validate_learn` |
+| **QuizMD** — assessments | `parse_quiz`, `validate_quiz` |
+| **FlashMD** — flashcards | `parse_flash`, `validate_flash` |
+| **NuggetMD** — micro-learning nuggets | `parse_nugget`, `validate_nugget` |
+| **TrackMD** — learning paths | `parse_track`, `validate_track` |
+| **DiagramMD** — diagrams | `parse_diagram`, `validate_diagram` |
+| **MediaMD** — media catalogues | `parse_media`, `validate_media` |
+| **GlossaryMD** — glossaries | `parse_glossary`, `validate_glossary` |
+| **BadgeMD** — micro-credentials | `parse_badge`, `validate_badge` |
+| **CertMD** — macro-credentials | `parse_cert`, `validate_cert` |
+
+## Install
+
+```bash
+pip install pylearnspec
+```
+
+## Quick start
+
+### Parse a QuizMD file
+
+```python
+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
+
+```python
+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
+
+```python
+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:
+
+```python
+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)
+
+### 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
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

pylearnspec-0.4.0/README.md

@@ -0,0 +1,118 @@
+# pylearnspec
+
+Python parser and validator for the [LearnSpec](https://learnspec.org) suite of open standards:
+
+| Format | API |
+|---|---|
+| **LearnMD** — instructional content | `parse_learn`, `validate_learn` |
+| **QuizMD** — assessments | `parse_quiz`, `validate_quiz` |
+| **FlashMD** — flashcards | `parse_flash`, `validate_flash` |
+| **NuggetMD** — micro-learning nuggets | `parse_nugget`, `validate_nugget` |
+| **TrackMD** — learning paths | `parse_track`, `validate_track` |
+| **DiagramMD** — diagrams | `parse_diagram`, `validate_diagram` |
+| **MediaMD** — media catalogues | `parse_media`, `validate_media` |
+| **GlossaryMD** — glossaries | `parse_glossary`, `validate_glossary` |
+| **BadgeMD** — micro-credentials | `parse_badge`, `validate_badge` |
+| **CertMD** — macro-credentials | `parse_cert`, `validate_cert` |
+
+## Install
+
+```bash
+pip install pylearnspec
+```
+
+## Quick start
+
+### Parse a QuizMD file
+
+```python
+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
+
+```python
+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
+
+```python
+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:
+
+```python
+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)
+
+### 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
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

pylearnspec-0.4.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=64,<77", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pylearnspec"
+version = "0.4.0"
+description = "Python parser and validator for the LearnSpec suite (LearnMD, QuizMD, FlashMD, TrackMD, DiagramMD, MediaMD, GlossaryMD, BadgeMD, CertMD, NuggetMD)"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{ name = "learnspec", email = "hello@learnspec.org" }]
+keywords = ["learnspec", "quizmd", "learnmd", "flashmd", "trackmd", "diagrammd", "mediamd", "glossarymd", "badgemd", "certmd", "nuggetmd", "parser", "education", "assessment"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/learnspec/pylearnspec"
+Repository = "https://github.com/learnspec/pylearnspec"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pylearnspec-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pylearnspec-0.4.0/src/pylearnspec/__init__.py

@@ -0,0 +1,50 @@
+"""pylearnspec — Python parser and validator for the LearnSpec suite.
+
+Supported formats:
+- LearnMD    (parse_learn, validate_learn)
+- QuizMD     (parse_quiz, validate_quiz)
+- FlashMD    (parse_flash, validate_flash)
+- TrackMD    (parse_track, validate_track)
+- DiagramMD  (parse_diagram, validate_diagram)
+- MediaMD    (parse_media, validate_media)
+- GlossaryMD (parse_glossary, validate_glossary)
+- BadgeMD    (parse_badge, validate_badge)
+- CertMD     (parse_cert, validate_cert)
+- NuggetMD   (parse_nugget, validate_nugget)
+"""
+
+__version__ = "0.4.0"
+
+from pylearnspec.badgemd.parser import parse_badge
+from pylearnspec.badgemd.validator import validate_badge
+from pylearnspec.certmd.parser import parse_cert
+from pylearnspec.certmd.validator import validate_cert
+from pylearnspec.diagrammd.parser import parse_diagram
+from pylearnspec.diagrammd.validator import validate_diagram
+from pylearnspec.flashmd.parser import parse_flash
+from pylearnspec.flashmd.validator import validate_flash
+from pylearnspec.glossarymd.parser import parse_glossary
+from pylearnspec.glossarymd.validator import validate_glossary
+from pylearnspec.learnmd.parser import parse_learn
+from pylearnspec.learnmd.validator import validate_learn
+from pylearnspec.mediamd.parser import parse_media
+from pylearnspec.mediamd.validator import validate_media
+from pylearnspec.nuggetmd.parser import parse_nugget
+from pylearnspec.nuggetmd.validator import validate_nugget
+from pylearnspec.quizmd.parser import parse_quiz
+from pylearnspec.quizmd.validator import validate_quiz
+from pylearnspec.trackmd.parser import parse_track
+from pylearnspec.trackmd.validator import validate_track
+
+__all__ = [
+    "parse_quiz", "validate_quiz",
+    "parse_learn", "validate_learn",
+    "parse_flash", "validate_flash",
+    "parse_track", "validate_track",
+    "parse_diagram", "validate_diagram",
+    "parse_media", "validate_media",
+    "parse_glossary", "validate_glossary",
+    "parse_badge", "validate_badge",
+    "parse_cert", "validate_cert",
+    "parse_nugget", "validate_nugget",
+]

pylearnspec-0.4.0/src/pylearnspec/badgemd/__init__.py

@@ -0,0 +1,6 @@
+"""BadgeMD — micro-credentials format for the LearnSpec suite."""
+
+from pylearnspec.badgemd.parser import parse_badge
+from pylearnspec.badgemd.validator import validate_badge
+
+__all__ = ["parse_badge", "validate_badge"]

pylearnspec-0.4.0/src/pylearnspec/badgemd/models.py

@@ -0,0 +1,28 @@
+"""Data models for BadgeMD parsed output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Badge:
+    title: str = ""
+    level: str = "0"
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+    image_path: str = ""              # from the ![](...) line in the body
+    body_text: str = ""               # narrative criteria
+    criteria: list[dict[str, Any]] = field(default_factory=list)
+    has_criteria_block: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "level": self.level,
+            "frontmatter": self.frontmatter,
+            "image_path": self.image_path,
+            "body_text": self.body_text,
+            "criteria": self.criteria,
+            "has_criteria_block": self.has_criteria_block,
+        }

pylearnspec-0.4.0/src/pylearnspec/badgemd/parser.py

@@ -0,0 +1,67 @@
+"""BadgeMD parser."""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+
+from pylearnspec.badgemd.models import Badge
+from pylearnspec.common.frontmatter import extract_frontmatter
+
+_H1_RE = re.compile(r"^#\s+(.+)$", re.MULTILINE)
+_IMAGE_LINE_RE = re.compile(r"^!\[[^\]]*\]\(([^)]+)\)", re.MULTILINE)
+_CRITERIA_BLOCK_RE = re.compile(
+    r"^```criteria\s*\n(.*?)^```\s*$",
+    re.MULTILINE | re.DOTALL,
+)
+
+
+def parse_badge(content: str) -> Badge:
+    frontmatter, body = extract_frontmatter(content)
+
+    title = frontmatter.get("name", "") or frontmatter.get("title", "")
+    if not title:
+        m = _H1_RE.search(body)
+        if m:
+            title = m.group(1).strip()
+
+    image_path = ""
+    if (m := _IMAGE_LINE_RE.search(body)):
+        image_path = m.group(1).strip()
+
+    criteria: list[dict] = []
+    has_criteria_block = False
+    if (m := _CRITERIA_BLOCK_RE.search(body)):
+        has_criteria_block = True
+        try:
+            loaded = yaml.safe_load(m.group(1))
+            if isinstance(loaded, dict):
+                criteria = [loaded]
+            elif isinstance(loaded, list):
+                criteria = [c for c in loaded if isinstance(c, dict)]
+        except yaml.YAMLError:
+            pass
+
+    # Strip image and criteria block from body to get narrative text
+    body_text = _CRITERIA_BLOCK_RE.sub("", body)
+    body_text = _IMAGE_LINE_RE.sub("", body_text, count=1)
+    body_text = body_text.strip()
+
+    has_fm = bool(frontmatter)
+    if has_criteria_block:
+        level = "2"
+    elif has_fm:
+        level = "1"
+    else:
+        level = "0"
+
+    return Badge(
+        title=title,
+        level=level,
+        frontmatter=frontmatter,
+        image_path=image_path,
+        body_text=body_text,
+        criteria=criteria,
+        has_criteria_block=has_criteria_block,
+    )

pylearnspec-0.4.0/src/pylearnspec/badgemd/validator.py

@@ -0,0 +1,59 @@
+"""BadgeMD validator."""
+
+from __future__ import annotations
+
+import re
+
+from pylearnspec.badgemd.parser import parse_badge
+from pylearnspec.common.validation import Diagnostic, severity_for
+
+_DURATION_RE = re.compile(r"^P(?:\d+Y)?(?:\d+M)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+S)?)?$")
+
+KNOWN_CRITERIA_TYPES = {"track_complete", "quiz_pass", "checkpoint_reached", "manual"}
+
+
+def validate_badge(content: str, *, strict: bool = False) -> list[Diagnostic]:
+    diags: list[Diagnostic] = []
+    try:
+        b = parse_badge(content)
+    except Exception as e:
+        diags.append(Diagnostic(level="error", message=f"Parse error: {e}"))
+        return diags
+
+    sev = severity_for(strict)
+    fm = b.frontmatter
+
+    if not fm.get("lang"):
+        diags.append(Diagnostic(level=sev, message="Missing 'lang' in frontmatter"))
+    if not fm.get("name"):
+        diags.append(Diagnostic(level="error", message="Missing required 'name'"))
+    if not fm.get("image"):
+        diags.append(Diagnostic(level="error", message="Missing required 'image'"))
+    elif not str(fm["image"]).lower().endswith(".svg"):
+        diags.append(Diagnostic(level=sev, message="'image' should point to an SVG file"))
+
+    issuer = fm.get("issuer") or {}
+    if not isinstance(issuer, dict) or not issuer.get("name"):
+        diags.append(Diagnostic(level="error", message="Missing required 'issuer.name'"))
+    if isinstance(issuer, dict) and not issuer.get("url"):
+        diags.append(Diagnostic(level=sev, message="Missing 'issuer.url'"))
+
+    if not b.image_path:
+        diags.append(Diagnostic(level=sev, message="No Markdown image line found in the body"))
+
+    if not b.has_criteria_block:
+        diags.append(Diagnostic(level=sev, message="No 'criteria' fenced block — award conditions are narrative only"))
+    else:
+        for i, c in enumerate(b.criteria, start=1):
+            t = c.get("type")
+            if t and t not in KNOWN_CRITERIA_TYPES:
+                diags.append(Diagnostic(level=sev, message=f"Criterion #{i}: unrecognised type '{t}'"))
+
+    expires = fm.get("expires")
+    if expires is not None and not _DURATION_RE.match(str(expires)):
+        diags.append(Diagnostic(
+            level="error",
+            message=f"'expires' must be an ISO 8601 duration (got {expires!r})",
+        ))
+
+    return diags

pylearnspec-0.4.0/src/pylearnspec/certmd/__init__.py

@@ -0,0 +1,6 @@
+"""CertMD — macro-credentials format for the LearnSpec suite."""
+
+from pylearnspec.certmd.parser import parse_cert
+from pylearnspec.certmd.validator import validate_cert
+
+__all__ = ["parse_cert", "validate_cert"]

pylearnspec-0.4.0/src/pylearnspec/certmd/models.py

@@ -0,0 +1,28 @@
+"""Data models for CertMD parsed output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Cert:
+    title: str = ""
+    level: str = "0"
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+    image_path: str = ""
+    body_text: str = ""
+    requirements: list[dict[str, Any]] = field(default_factory=list)
+    has_requirements_block: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "level": self.level,
+            "frontmatter": self.frontmatter,
+            "image_path": self.image_path,
+            "body_text": self.body_text,
+            "requirements": self.requirements,
+            "has_requirements_block": self.has_requirements_block,
+        }

pylearnspec-0.4.0/src/pylearnspec/certmd/parser.py

@@ -0,0 +1,65 @@
+"""CertMD parser."""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+
+from pylearnspec.certmd.models import Cert
+from pylearnspec.common.frontmatter import extract_frontmatter
+
+_H1_RE = re.compile(r"^#\s+(.+)$", re.MULTILINE)
+_IMAGE_LINE_RE = re.compile(r"^!\[[^\]]*\]\(([^)]+)\)", re.MULTILINE)
+_REQUIREMENTS_BLOCK_RE = re.compile(
+    r"^```requirements\s*\n(.*?)^```\s*$",
+    re.MULTILINE | re.DOTALL,
+)
+
+
+def parse_cert(content: str) -> Cert:
+    frontmatter, body = extract_frontmatter(content)
+
+    title = frontmatter.get("name", "") or frontmatter.get("title", "")
+    if not title:
+        m = _H1_RE.search(body)
+        if m:
+            title = m.group(1).strip()
+
+    image_path = ""
+    if (m := _IMAGE_LINE_RE.search(body)):
+        image_path = m.group(1).strip()
+
+    requirements: list[dict] = []
+    has_block = False
+    if (m := _REQUIREMENTS_BLOCK_RE.search(body)):
+        has_block = True
+        try:
+            loaded = yaml.safe_load(m.group(1))
+            if isinstance(loaded, dict):
+                requirements = [loaded]
+            elif isinstance(loaded, list):
+                requirements = [r for r in loaded if isinstance(r, dict)]
+        except yaml.YAMLError:
+            pass
+
+    body_text = _REQUIREMENTS_BLOCK_RE.sub("", body)
+    body_text = _IMAGE_LINE_RE.sub("", body_text, count=1).strip()
+
+    has_fm = bool(frontmatter)
+    if has_block:
+        level = "2"
+    elif has_fm:
+        level = "1"
+    else:
+        level = "0"
+
+    return Cert(
+        title=title,
+        level=level,
+        frontmatter=frontmatter,
+        image_path=image_path,
+        body_text=body_text,
+        requirements=requirements,
+        has_requirements_block=has_block,
+    )