refactor(python): simplify loader-unification code

Pythonic-style polish on the new MetaDataSource + MetaDataLoader
surface; behavior unchanged, 442 tests still pass.

- meta_data_loader: replace `if/elif` format dispatch with `match`;
  narrow the YAML parse `except Exception` to `ParseError` (drops
  the defensive `getattr(exc, "code", ...)` — ParseError always
  carries a code).
- meta_data_loader: inline the one-line `_empty_root()` helper.
- directory_source: collapse `if/else` candidates assignment + post-
  hoc list sort + explicit yield loop into a single `sorted(...)` +
  `yield from` (generator expression input, no temp list mutation).
- metaobjects/__init__: replace the three `load_*` wrapper functions
  with direct classmethod aliases (`load_directory = MetaDataLoader
  .from_directory`). Signatures + docstrings come straight from the
  classmethods — no wrapping layer to drift.

Considered + rejected: deduping `_infer_format` between FileSource
and UriSource (different input types — `Path` vs `str` — and four
lines each; a shared helper would add an abstraction the spec
forbids for marginal benefit).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dmealing

server/python/src/metaobjects/__init__.py

@@ -3,12 +3,10 @@
 Top-level exports cover the cross-language loader API (MetaDataLoader +
 LoadResult, the four MetaDataSource impls, and Pythonic module-level
 shortcuts ``load_directory`` / ``load_uris`` / ``load_string`` that
-delegate to the class factories).
+alias the class factories ala ``requests.get`` over ``Session().get``).
 """
 from __future__ import annotations
 
-from pathlib import Path
-
 from .errors import ErrorCode, MetaError
 from .loader.meta_data_loader import LoadResult, MetaDataLoader
 from .loader.sources import (
@@ -19,35 +17,13 @@
     MetaDataSource,
     UriSource,
 )
-from .provider import Provider
-
-
-def load_directory(
-    directory: Path | str,
-    providers: list[Provider] | None = None,
-    exclude: list[str] | None = None,
-    recurse: bool = True,
-) -> LoadResult:
-    """Module-level shortcut for ``MetaDataLoader.from_directory``."""
-    return MetaDataLoader.from_directory(
-        directory, providers=providers, exclude=exclude, recurse=recurse,
-    )
-
-
-def load_uris(
-    uris: list[str], providers: list[Provider] | None = None
-) -> LoadResult:
-    """Module-level shortcut for ``MetaDataLoader.from_uris``."""
-    return MetaDataLoader.from_uris(uris, providers=providers)
-
 
-def load_string(
-    content: str,
-    format: MetaDataFormat = MetaDataFormat.JSON,
-    providers: list[Provider] | None = None,
-) -> LoadResult:
-    """Module-level shortcut for ``MetaDataLoader.from_string``."""
-    return MetaDataLoader.from_string(content, format=format, providers=providers)
+# Module-level shortcuts: the 99% case for callers who don't need a
+# long-lived loader. Signatures + docstrings come straight from the
+# classmethods — no wrapping layer to drift.
+load_directory = MetaDataLoader.from_directory
+load_uris = MetaDataLoader.from_uris
+load_string = MetaDataLoader.from_string
 
 
 __all__ = [

server/python/src/metaobjects/loader/meta_data_loader.py

@@ -19,7 +19,7 @@
 from pathlib import Path
 
 from ..core_types import core_provider
-from ..errors import ErrorCode, MetaError
+from ..errors import ErrorCode, MetaError, ParseError
 from ..meta.meta_data import MetaData
 from ..meta.meta_root import MetaRoot
 from ..parser import ParseResult, parse_document
@@ -48,11 +48,6 @@ class LoadResult:
     warnings: list[str] = field(default_factory=list)
 
 
-def _empty_root() -> MetaRoot:
-    """Construct the canonical empty root (matches parse_document's seed)."""
-    return MetaRoot(TYPE_METADATA, SUBTYPE_ROOT, "")
-
-
 class MetaDataLoader:
     """Source-polymorphic metadata loader.
 
@@ -74,7 +69,8 @@ def registry(self) -> TypeRegistry:
 
     def load(self, sources: list[MetaDataSource]) -> LoadResult:
         """Parse -> merge -> super-resolve -> validate -> freeze."""
-        result = LoadResult(root=_empty_root())
+        # Canonical empty root (matches parse_document's seed).
+        result = LoadResult(root=MetaRoot(TYPE_METADATA, SUBTYPE_ROOT, ""))
         roots: list[MetaData] = []
 
         for src in sources:
@@ -149,18 +145,17 @@ def _parse_source(
             errors.append(MetaError(str(exc), ErrorCode.ERR_UNKNOWN, src.id))
             return None
 
-        if src.format is MetaDataFormat.YAML:
-            try:
-                return parse_yaml(text, self._registry, source=src.id)
-            except Exception as exc:  # ParseError carries a code
-                code = getattr(exc, "code", ErrorCode.ERR_MALFORMED_YAML)
-                errors.append(MetaError(str(exc), code, src.id))
-                return None
-
-        # Default: JSON.
-        try:
-            doc = json.loads(text)
-        except json.JSONDecodeError as exc:
-            errors.append(MetaError(str(exc), ErrorCode.ERR_MALFORMED_JSON, src.id))
-            return None
-        return parse_document(doc, self._registry, source=src.id)
+        match src.format:
+            case MetaDataFormat.YAML:
+                try:
+                    return parse_yaml(text, self._registry, source=src.id)
+                except ParseError as exc:
+                    errors.append(MetaError(str(exc), exc.code, src.id))
+                    return None
+            case MetaDataFormat.JSON:
+                try:
+                    doc = json.loads(text)
+                except json.JSONDecodeError as exc:
+                    errors.append(MetaError(str(exc), ErrorCode.ERR_MALFORMED_JSON, src.id))
+                    return None
+                return parse_document(doc, self._registry, source=src.id)

server/python/src/metaobjects/loader/sources/directory_source.py

@@ -34,18 +34,17 @@ def directory(self) -> Path:
         return self._directory
 
     def expand(self) -> Iterator[FileSource]:
-        if self._recurse:
-            candidates: Iterable[Path] = self._directory.rglob("*")
-        else:
-            candidates = self._directory.iterdir()
-
-        files = [
-            p
-            for p in candidates
-            if p.is_file()
-            and p.suffix.lower() in _SUPPORTED_SUFFIXES
-            and p.name not in self._exclude
-        ]
-        files.sort(key=lambda p: p.name)
-        for p in files:
-            yield FileSource(p)
+        candidates = (
+            self._directory.rglob("*") if self._recurse else self._directory.iterdir()
+        )
+        files = sorted(
+            (
+                p
+                for p in candidates
+                if p.is_file()
+                and p.suffix.lower() in _SUPPORTED_SUFFIXES
+                and p.name not in self._exclude
+            ),
+            key=lambda p: p.name,
+        )
+        yield from (FileSource(p) for p in files)