feat(python): module-level load_directory/load_uris/load_string shortcuts

Adds top-level package exports mirroring the cross-port API: the
Tier-1 surface (MetaDataLoader, LoadResult, MetaDataSource, the four
source impls, MetaDataFormat) plus Pythonic module-level shortcuts
that delegate one-to-one to the class factories. Tests cover the
three shortcuts and assert the public-export surface is intact.

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

Author: dmealing

server/python/src/metaobjects/__init__.py

@@ -1 +1,67 @@
-"""metaobjects — Python implementation of the MetaObjects standard."""
+"""metaobjects — Python implementation of the MetaObjects standard.
+
+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).
+"""
+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 (
+    DirectorySource,
+    FileSource,
+    InMemoryStringSource,
+    MetaDataFormat,
+    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)
+
+
+__all__ = [
+    "MetaDataLoader",
+    "LoadResult",
+    "MetaDataSource",
+    "MetaDataFormat",
+    "FileSource",
+    "DirectorySource",
+    "UriSource",
+    "InMemoryStringSource",
+    "ErrorCode",
+    "MetaError",
+    "load_directory",
+    "load_uris",
+    "load_string",
+]

server/python/tests/unit/test_module_shortcuts.py

@@ -0,0 +1,51 @@
+"""Module-level shortcut tests.
+
+Mirrors the Pythonic ``requests.get(url)`` pattern: a single import gives
+you the 99% case (load_directory / load_uris / load_string) without
+having to construct a MetaDataLoader.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import metaobjects
+
+
+_TINY = '{"metadata.root":{"package":"x","children":[]}}'
+
+
+def test_module_level_load_string() -> None:
+    result = metaobjects.load_string(_TINY)
+    assert result.errors == []
+
+
+def test_module_level_load_string_yaml() -> None:
+    result = metaobjects.load_string(
+        "metadata.root:\n  package: x\n  children: []\n",
+        format=metaobjects.MetaDataFormat.YAML,
+    )
+    assert result.errors == []
+
+
+def test_module_level_load_directory(tmp_path: Path) -> None:
+    (tmp_path / "meta.tiny.json").write_text(_TINY, encoding="utf-8")
+    result = metaobjects.load_directory(tmp_path)
+    assert result.errors == []
+
+
+def test_public_exports_are_present() -> None:
+    # Spot-check the Tier-1 surface.
+    for sym in (
+        "MetaDataLoader",
+        "LoadResult",
+        "MetaDataSource",
+        "MetaDataFormat",
+        "FileSource",
+        "DirectorySource",
+        "UriSource",
+        "InMemoryStringSource",
+        "load_directory",
+        "load_uris",
+        "load_string",
+    ):
+        assert hasattr(metaobjects, sym), f"metaobjects.{sym} missing"