Add versioned glossary YAML import and export

2026-09-12 11:23:18 +02:00
parent 9840953687
commit e2a0434941
7 changed files with 396 additions and 0 deletions
@@ -0,0 +1,122 @@
+"""Versioned UTF-8 YAML import and export for the terminology glossary."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import yaml
+
+from mka.application.glossary import (
+    GLOSSARY_CATEGORIES,
+    GlossaryEntry,
+    GlossaryReplacementEntry,
+)
+
+GLOSSARY_YAML_VERSION = 1
+
+
+class GlossaryYamlError(ValueError):
+    """Raised when a glossary YAML document is malformed or invalid."""
+
+
+def export_glossary_yaml(entries: Sequence[GlossaryEntry]) -> str:
+    """Serialize all glossary state in a deterministic, versioned document."""
+    document = {
+        "version": GLOSSARY_YAML_VERSION,
+        "glossary": [
+            {
+                "id": entry.id,
+                "canonical_term": entry.canonical_term,
+                "aliases": list(entry.aliases),
+                "category": entry.category,
+                "description": entry.description,
+                "active": entry.is_active,
+            }
+            for entry in entries
+        ],
+    }
+    return yaml.safe_dump(document, allow_unicode=True, sort_keys=False, default_flow_style=False)
+
+
+def import_glossary_yaml(content: str | bytes) -> list[GlossaryReplacementEntry]:
+    """Parse and completely validate a glossary replacement document."""
+    try:
+        if isinstance(content, bytes):
+            content = content.decode("utf-8")
+        document = yaml.safe_load(content)
+    except (yaml.YAMLError, UnicodeDecodeError) as exc:
+        raise GlossaryYamlError(f"Malformed glossary YAML: {exc}") from exc
+
+    if not isinstance(document, dict):
+        raise GlossaryYamlError("Glossary YAML must contain a top-level mapping.")
+    version = document.get("version")
+    if type(version) is not int or version != GLOSSARY_YAML_VERSION:
+        raise GlossaryYamlError(
+            f"Unsupported glossary YAML version {version!r}; expected {GLOSSARY_YAML_VERSION}."
+        )
+    raw_entries = document.get("glossary")
+    if not isinstance(raw_entries, list):
+        raise GlossaryYamlError("Glossary YAML must contain a top-level 'glossary' list.")
+
+    result: list[GlossaryReplacementEntry] = []
+    seen_ids: set[int] = set()
+    seen_terms: set[str] = set()
+    for index, raw in enumerate(raw_entries, start=1):
+        if not isinstance(raw, dict):
+            raise GlossaryYamlError(f"Glossary entry {index} must be a mapping.")
+        entry_id = raw.get("id")
+        if type(entry_id) is not int or entry_id <= 0:
+            raise GlossaryYamlError(f"Glossary entry {index} requires a positive integer id.")
+        if entry_id in seen_ids:
+            raise GlossaryYamlError(f"Duplicate glossary entry id: {entry_id}.")
+        seen_ids.add(entry_id)
+
+        canonical = _required_text(raw, "canonical_term", index).strip()
+        category = raw.get("category")
+        if category not in GLOSSARY_CATEGORIES:
+            allowed = ", ".join(GLOSSARY_CATEGORIES)
+            raise GlossaryYamlError(
+                f"Glossary entry {index} has invalid category; expected one of: {allowed}."
+            )
+        aliases_value = raw.get("aliases")
+        if not isinstance(aliases_value, list) or any(
+            not isinstance(alias, str) or not alias.strip() for alias in aliases_value
+        ):
+            raise GlossaryYamlError(f"Glossary entry {index} aliases must be a list of text.")
+        aliases = tuple(alias.strip() for alias in aliases_value)
+        folded = [canonical.casefold(), *(alias.casefold() for alias in aliases)]
+        if len(folded) != len(set(folded)):
+            raise GlossaryYamlError(
+                f"Glossary entry {index} aliases must be unique and differ from its canonical term."
+            )
+        duplicate = next((term for term in folded if term in seen_terms), None)
+        if duplicate is not None:
+            raise GlossaryYamlError(
+                f"Glossary entry {index} contains a duplicate canonical term or alias."
+            )
+        seen_terms.update(folded)
+
+        description = raw.get("description")
+        if description is not None and not isinstance(description, str):
+            raise GlossaryYamlError(f"Glossary entry {index} description must be text or null.")
+        active = raw.get("active")
+        if type(active) is not bool:
+            raise GlossaryYamlError(f"Glossary entry {index} active must be true or false.")
+        result.append(
+            GlossaryReplacementEntry(
+                id=entry_id,
+                canonical_term=canonical,
+                aliases=aliases,
+                category=category,
+                description=description,
+                is_active=active,
+            )
+        )
+    return result
+
+
+def _required_text(entry: dict[object, object], field: str, index: int) -> str:
+    value = entry.get(field)
+    if not isinstance(value, str) or not value.strip():
+        raise GlossaryYamlError(f"Glossary entry {index} requires a non-empty {field}.")
+    return value