pylearnspec 0.4.0__py3-none-any.whl

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/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/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/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/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/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/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/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,
+    )

pylearnspec/certmd/validator.py

@@ -0,0 +1,72 @@
+"""CertMD validator."""
+
+from __future__ import annotations
+
+import re
+
+from pylearnspec.certmd.parser import parse_cert
+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)?)?$")
+
+
+def validate_cert(content: str, *, strict: bool = False) -> list[Diagnostic]:
+    diags: list[Diagnostic] = []
+    try:
+        c = parse_cert(content)
+    except Exception as e:
+        diags.append(Diagnostic(level="error", message=f"Parse error: {e}"))
+        return diags
+
+    sev = severity_for(strict)
+    fm = c.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'"))
+
+    # grade_levels sanity
+    grades = fm.get("grade_levels") or {}
+    if isinstance(grades, dict):
+        previous = -1.0
+        for key in ("pass", "merit", "distinction"):
+            if key in grades:
+                try:
+                    v = float(grades[key])
+                except (TypeError, ValueError):
+                    diags.append(Diagnostic(level="error", message=f"grade_levels.{key} must be numeric"))
+                    continue
+                if v < 0 or v > 1:
+                    diags.append(Diagnostic(
+                        level="error",
+                        message=f"grade_levels.{key} must be between 0.0 and 1.0",
+                    ))
+                if v < previous:
+                    diags.append(Diagnostic(
+                        level=sev,
+                        message=f"grade_levels.{key} ({v}) is below the previous threshold ({previous})",
+                    ))
+                previous = v
+
+    if not c.image_path:
+        diags.append(Diagnostic(level=sev, message="No Markdown image line found in the body"))
+    if not c.has_requirements_block:
+        diags.append(Diagnostic(level=sev, message="No 'requirements' block — award conditions are narrative only"))
+
+    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/common/directives.py

@@ -0,0 +1,130 @@
+"""Cross-format directive and reference extraction.
+
+These directives are part of the LearnSpec Architecture Charter and shared
+across all content formats:
+
+- ``!import <path>``       — composition (inline another file)
+- ``!ref <path>``          — context (declare a dependency without inline render)
+- ``!checkpoint id:...``   — named progress marker
+- ``media:slug``           — symbolic media reference resolved via MediaMD
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+_IMPORT_RE = re.compile(r"^!import[ \t]+(\S+)(?:[ \t]+([^\n]*))?$", re.MULTILINE)
+_REF_RE = re.compile(r"^!ref[ \t]+(\S+)[ \t]*$", re.MULTILINE)
+_CHECKPOINT_RE = re.compile(r"^!checkpoint[ \t]+([^\n]+)$", re.MULTILINE)
+_MEDIA_SLUG_RE = re.compile(
+    r'!\[[^\]]*\]\(media:([a-z0-9][a-z0-9-]*)(?:\s+"([^"]*)")?\)'
+)
+
+# Attributes inside a directive line: key:value, key:"quoted value", key:true
+_ATTR_RE = re.compile(r'(\w+):(?:"([^"]*)"|(\S+))')
+
+
+def _parse_attrs(text: str) -> dict[str, Any]:
+    """Parse `key:value` and `key:"quoted value"` attribute pairs from a string."""
+    out: dict[str, Any] = {}
+    for m in _ATTR_RE.finditer(text):
+        key = m.group(1)
+        value = m.group(2) if m.group(2) is not None else m.group(3)
+        if value in ("true", "false"):
+            out[key] = value == "true"
+        else:
+            out[key] = value
+    return out
+
+
+@dataclass
+class ImportDirective:
+    path: str
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def kind(self) -> str:
+        """Return the imported file kind: learn, quiz, flash, diagram, or unknown."""
+        for ext in ("learn", "quiz", "flash", "diagram", "track"):
+            if self.path.endswith(f".{ext}.md"):
+                return ext
+        return "unknown"
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"path": self.path, "kind": self.kind}
+        if self.attrs:
+            d["attrs"] = self.attrs
+        return d
+
+
+@dataclass
+class RefDirective:
+    path: str
+
+    @property
+    def kind(self) -> str:
+        for ext in ("media", "glossary"):
+            if self.path.endswith(f".{ext}.md"):
+                return ext
+        return "unknown"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"path": self.path, "kind": self.kind}
+
+
+@dataclass
+class Checkpoint:
+    id: str
+    label: str = ""
+    type: str = "milestone"
+    badge: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"id": self.id, "label": self.label, "type": self.type, "badge": self.badge}
+
+
+@dataclass
+class MediaRef:
+    """Inline ``media:slug`` image reference."""
+    slug: str
+    fallback_url: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"slug": self.slug, "fallback_url": self.fallback_url}
+
+
+def extract_imports(text: str) -> list[ImportDirective]:
+    out: list[ImportDirective] = []
+    for m in _IMPORT_RE.finditer(text):
+        path = m.group(1).strip()
+        attrs_text = (m.group(2) or "").strip()
+        out.append(ImportDirective(path=path, attrs=_parse_attrs(attrs_text)))
+    return out
+
+
+def extract_refs(text: str) -> list[RefDirective]:
+    return [RefDirective(path=m.group(1).strip()) for m in _REF_RE.finditer(text)]
+
+
+def extract_checkpoints(text: str) -> list[Checkpoint]:
+    out: list[Checkpoint] = []
+    for m in _CHECKPOINT_RE.finditer(text):
+        attrs = _parse_attrs(m.group(1))
+        if "id" not in attrs:
+            continue
+        out.append(Checkpoint(
+            id=str(attrs["id"]),
+            label=str(attrs.get("label", "")),
+            type=str(attrs.get("type", "milestone")),
+            badge=str(attrs.get("badge", "")),
+        ))
+    return out
+
+
+def extract_media_refs(text: str) -> list[MediaRef]:
+    return [
+        MediaRef(slug=m.group(1), fallback_url=m.group(2) or "")
+        for m in _MEDIA_SLUG_RE.finditer(text)
+    ]

pylearnspec/common/frontmatter.py

@@ -0,0 +1,32 @@
+"""YAML frontmatter extraction shared by QuizMD and LearnMD parsers."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import yaml
+
+_FRONTMATTER_RE = re.compile(
+    r"\A\s*---[ \t]*\n(.*?\n)---[ \t]*\n",
+    re.DOTALL,
+)
+
+
+def extract_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    """Return (frontmatter_dict, remaining_text).
+
+    If no frontmatter is found, returns ({}, text).
+    """
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return {}, text
+    raw = m.group(1)
+    try:
+        data = yaml.safe_load(raw)
+    except yaml.YAMLError:
+        return {}, text
+    if not isinstance(data, dict):
+        return {}, text
+    rest = text[m.end() :]
+    return data, rest

pylearnspec/common/validation.py

@@ -0,0 +1,22 @@
+"""Shared validation primitives used across all LearnSpec formats."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Severity = Literal["error", "warning"]
+
+
+@dataclass
+class Diagnostic:
+    level: Severity
+    message: str
+
+    def to_dict(self) -> dict:
+        return {"level": self.level, "message": self.message}
+
+
+def severity_for(strict: bool) -> Severity:
+    """Return the severity used for fields demoted to warning in lenient mode."""
+    return "error" if strict else "warning"

pylearnspec/diagrammd/__init__.py

@@ -0,0 +1,6 @@
+"""DiagramMD — canonical diagram syntax for the LearnSpec suite."""
+
+from pylearnspec.diagrammd.parser import parse_diagram
+from pylearnspec.diagrammd.validator import validate_diagram
+
+__all__ = ["parse_diagram", "validate_diagram"]

pylearnspec/diagrammd/models.py

@@ -0,0 +1,43 @@
+"""Data models for DiagramMD parsed output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Diagram:
+    type: str           # mermaid, tikz, graphviz, plantuml, blockdiag, seqdiag, chess, abc, smiles, vega-lite, …
+    source: str = ""
+    id: str = ""
+    caption: str = ""
+    alt: str = ""
+    width: str = ""
+    extra: dict[str, Any] = field(default_factory=dict)  # e.g. play, cursor, colors for abc
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"type": self.type, "source": self.source}
+        for k in ("id", "caption", "alt", "width"):
+            v = getattr(self, k)
+            if v:
+                d[k] = v
+        if self.extra:
+            d["extra"] = self.extra
+        return d
+
+
+@dataclass
+class DiagramFile:
+    title: str = ""
+    level: str = "0"
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+    diagrams: list[Diagram] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "level": self.level,
+            "frontmatter": self.frontmatter,
+            "diagrams": [d.to_dict() for d in self.diagrams],
+        }