morphir-python 0.0.2__tar.gz → 0.1.0__tar.gz

{morphir_python-0.0.2 → morphir_python-0.1.0}/.gitignore

@@ -73,3 +73,9 @@ yarn-error.log*
 
 # behave writes the pretty formatter to this file when its output is piped
 pretty.output
+
+# Rust
+rust/target/
+
+# Extension bundles built by mise run extension:bundle
+.morphir/

{morphir_python-0.0.2 → morphir_python-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: morphir-python
-Version: 0.0.2
+Version: 0.1.0
 Summary: CLI tools and extensions for Morphir Python
 Project-URL: Homepage, https://github.com/finos/morphir-python
 Project-URL: Documentation, https://morphir.finos.org
@@ -20,7 +20,8 @@ Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.14
-Requires-Dist: morphir>=0.0.1
+Requires-Dist: morphir-python-native==0.1.1
+Requires-Dist: morphir>=0.1.0
 Requires-Dist: pygments>=2.20.0
 Requires-Dist: typer>=0.15
 Description-Content-Type: text/markdown
@@ -66,6 +67,7 @@ morphir-python ir inspect morphir-ir.json
 morphir-python ir convert morphir-ir.json --to v4 -o out.json --package-version 1.2.0
 morphir-python ir convert v4.json --to v3 -o out.json --drop-source-locations
 morphir-python ir convert old-format-1.json --to v3 -o out.json
+morphir-python ir convert morphir-ir.json --to v4 --v4-spelling expanded -o out.json
 ```
 
 `inspect` prints the normalized format version, the distribution kind
@@ -74,6 +76,9 @@ draft and formats 1 and 2 as legacy. `convert` handles `Library` and `Specs` in
 both directions. It writes a v3 `Library` as format `3` and a v3 `Specs` as
 `"3.1.0"`, the lowest version that holds each. A legacy format 1 or 2 file
 converts to a format 3.0.0 `Library` or draft v4; nothing writes format 1 or 2.
+Draft v4 is written in the compact canonical spelling, as other Morphir tools
+write it; `--v4-spelling expanded` writes every node in the expanded form
+instead. Both spellings read back to the same model.
 `convert` writes through a temporary file and renames it only on success, so a
 failed conversion leaves no output file.
 Diagnostics go to standard error as `code at location: message`.
@@ -86,7 +91,7 @@ format-version rules and the draft v4 status.
 ## Requirements
 
 - Python 3.14+
-- `morphir>=0.0.1` (installed as a dependency)
+- `morphir>=0.1.0` and `morphir-python-native==0.1.1` (installed as dependencies)
 
 ## License
 

{morphir_python-0.0.2 → morphir_python-0.1.0}/README.md

@@ -39,6 +39,7 @@ morphir-python ir inspect morphir-ir.json
 morphir-python ir convert morphir-ir.json --to v4 -o out.json --package-version 1.2.0
 morphir-python ir convert v4.json --to v3 -o out.json --drop-source-locations
 morphir-python ir convert old-format-1.json --to v3 -o out.json
+morphir-python ir convert morphir-ir.json --to v4 --v4-spelling expanded -o out.json
 ```
 
 `inspect` prints the normalized format version, the distribution kind
@@ -47,6 +48,9 @@ draft and formats 1 and 2 as legacy. `convert` handles `Library` and `Specs` in
 both directions. It writes a v3 `Library` as format `3` and a v3 `Specs` as
 `"3.1.0"`, the lowest version that holds each. A legacy format 1 or 2 file
 converts to a format 3.0.0 `Library` or draft v4; nothing writes format 1 or 2.
+Draft v4 is written in the compact canonical spelling, as other Morphir tools
+write it; `--v4-spelling expanded` writes every node in the expanded form
+instead. Both spellings read back to the same model.
 `convert` writes through a temporary file and renames it only on success, so a
 failed conversion leaves no output file.
 Diagnostics go to standard error as `code at location: message`.
@@ -59,7 +63,7 @@ format-version rules and the draft v4 status.
 ## Requirements
 
 - Python 3.14+
-- `morphir>=0.0.1` (installed as a dependency)
+- `morphir>=0.1.0` and `morphir-python-native==0.1.1` (installed as dependencies)
 
 ## License
 

{morphir_python-0.0.2 → morphir_python-0.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "morphir-python"
-version = "0.0.2"
+version = "0.1.0"
 description = "CLI tools and extensions for Morphir Python"
 readme = "README.md"
 license = "Apache-2.0"
@@ -22,7 +22,9 @@ authors = [
     { name = "FINOS", email = "morphir@finos.org" }
 ]
 dependencies = [
-    "morphir>=0.0.1",
+    "morphir>=0.1.0",
+    # Exact qualified native compiler; checked again when the compiler first loads.
+    "morphir-python-native==0.1.1",
     "typer>=0.15",
     # Rich uses Pygments; older versions are affected by CVE-2026-4539.
     "pygments>=2.20.0",

{morphir_python-0.0.2 → morphir_python-0.1.0}/src/morphir_tools/__init__.py

@@ -6,8 +6,8 @@ Morphir domain models, including code generation and development tools.
 Example:
     >>> import morphir_tools
     >>> morphir_tools.__version__
-    '0.0.2'
+    '0.1.0'
 """
 
-__version__ = "0.0.2"
+__version__ = "0.1.0"
 __all__ = ["__version__"]

morphir_python-0.1.0/src/morphir_tools/_output.py

@@ -0,0 +1,114 @@
+"""Safe publication of generated files.
+
+Generation writes a complete tree into a new sibling staging directory and only
+then moves it into place, so a failure never leaves partial output or touches
+existing user files.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+
+def umask() -> int:
+    """Return the process umask without changing it."""
+    mask = os.umask(0o022)
+    os.umask(mask)
+    return mask
+
+
+class OutputError(Exception):
+    """Output cannot be published safely; nothing was written."""
+
+
+def validate_artifact_paths(paths: Iterable[str]) -> None:
+    """Check that relative artifact paths stay inside one new directory tree.
+
+    Each path must be a normalized relative POSIX path. No two paths may name the
+    same file on a case-insensitive file system, and no path may be a parent
+    directory of another.
+
+    Raises:
+        OutputError: For the first invalid path or collision.
+    """
+    seen: dict[str, str] = {}
+    directories: dict[str, str] = {}
+    for path in paths:
+        pure = PurePosixPath(path)
+        if (
+            not path
+            or "\\" in path
+            or pure.is_absolute()
+            or ":" in pure.parts[0]
+            or any(part in {"", ".", ".."} for part in path.split("/"))
+        ):
+            raise OutputError(f"artifact path {path!r} is not a safe relative path")
+        key = path.casefold()
+        if key in seen:
+            raise OutputError(f"artifact paths {seen[key]!r} and {path!r} collide")
+        seen[key] = path
+        for parent in pure.parents:
+            if str(parent) != ".":
+                directories.setdefault(str(parent).casefold(), path)
+    for key, path in seen.items():
+        if key in directories:
+            raise OutputError(
+                f"artifact path {path!r} is also a directory of {directories[key]!r}"
+            )
+
+
+def check_destination(directory: Path) -> None:
+    """Require an absent directory, or an empty real directory.
+
+    Raises:
+        OutputError: When the destination is a symbolic link, a file or a
+            nonempty directory.
+    """
+    if directory.is_symlink():
+        raise OutputError(f"output directory {directory} is a symbolic link")
+    if directory.exists():
+        if not directory.is_dir():
+            raise OutputError(f"output path {directory} is not a directory")
+        if any(directory.iterdir()):
+            raise OutputError(f"output directory {directory} is not empty")
+
+
+def publish_tree(directory: Path, files: Sequence[tuple[str, str]]) -> None:
+    """Write ``files`` to a staging directory, then move it to ``directory``.
+
+    Args:
+        directory: The absent or empty destination.
+        files: Relative POSIX paths and their text, already validated.
+
+    Raises:
+        OutputError: When the destination is unsuitable.
+        OSError: When writing or moving fails; the staging tree is removed and
+            the destination is unchanged.
+    """
+    check_destination(directory)
+    parent = directory.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    # mkdtemp creates 0700; publish with the existing directory's mode, or the
+    # mode an ordinary mkdir would give under the user's umask.
+    mode = directory.stat().st_mode & 0o7777 if directory.exists() else 0o777 & ~umask()
+    staging = Path(tempfile.mkdtemp(prefix=f".{directory.name}.", dir=parent))
+    try:
+        staging.chmod(mode)
+        for relative, text in files:
+            target = staging.joinpath(*relative.split("/"))
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(text, encoding="utf-8")
+        check_destination(directory)
+        if directory.exists():
+            directory.rmdir()
+        os.replace(staging, directory)
+    except BaseException:
+        shutil.rmtree(staging, ignore_errors=True)
+        raise

{morphir_python-0.0.2 → morphir_python-0.1.0}/src/morphir_tools/cli.py

@@ -2,7 +2,9 @@
 
 Every IR operation goes through the `morphir` library: the shared format-version
 reader, the v3 (3.0.x and 3.1.x) and draft v4 codecs, and `morphir.ir.migrate`.
-The CLI adds file handling and reporting only.
+``compile`` and ``generate`` go through the public `morphir_tools.python` API,
+which loads the native compiler only when one of them runs. The CLI adds file
+handling and reporting only.
 
 Exit codes: 0 for success (including success with warnings), 1 when the library
 reports a diagnostic, 2 for a usage error.
@@ -14,7 +16,7 @@ import os
 import tempfile
 from enum import Enum
 from pathlib import Path
-from typing import Annotated
+from typing import TYPE_CHECKING, Annotated
 
 import typer
 
@@ -30,6 +32,13 @@ from morphir.ir.v4 import distribution as v4_dist
 from morphir.ir.v4.name import Name as Name4
 from morphir.ir.v4.path import Path as Path4
 
+from ._output import OutputError, publish_tree, umask, validate_artifact_paths
+
+if TYPE_CHECKING:
+    from .python import CompilerDiagnostic
+
+__all__ = ["OutputError", "app", "main", "validate_artifact_paths"]
+
 app = typer.Typer(
     name="morphir-python",
     help="Command-line tools for Morphir IR.",
@@ -44,6 +53,13 @@ ir_app = typer.Typer(
 app.add_typer(ir_app, name="ir")
 
 
+class V4Spelling(str, Enum):
+    """The draft v4 JSON spelling to write."""
+
+    COMPACT = "compact"
+    EXPANDED = "expanded"
+
+
 class Target(str, Enum):
     """The IR version to convert to."""
 
@@ -63,6 +79,9 @@ def _read(path: Path) -> str:
     except OSError as error:
         typer.echo(f"error: cannot read {path}: {error.strerror}", err=True)
         raise typer.Exit(1) from None
+    except UnicodeDecodeError:
+        typer.echo(f"error: cannot read {path}: the file is not UTF-8", err=True)
+        raise typer.Exit(1) from None
 
 
 def _write_atomically(target: Path, text: str) -> None:
@@ -71,6 +90,9 @@ def _write_atomically(target: Path, text: str) -> None:
         prefix=f".{target.name}.", suffix=".tmp", dir=directory
     )
     try:
+        # mkstemp creates 0600; keep an existing file's mode, or use the umask.
+        mode = target.stat().st_mode & 0o7777 if target.exists() else 0o666 & ~umask()
+        os.chmod(fd, mode)
         with os.fdopen(fd, "w", encoding="utf-8") as handle:
             handle.write(text)
         Path(temp_name).replace(target)
@@ -169,6 +191,14 @@ def convert(
             "writing v4, which spells an input as a bare type."
         ),
     ] = False,
+    v4_spelling: Annotated[
+        V4Spelling,
+        typer.Option(
+            "--v4-spelling",
+            help="The v4 JSON spelling to write: compact, the canonical form, or "
+            "expanded. Ignored when writing v3.",
+        ),
+    ] = V4Spelling.COMPACT,
 ) -> None:
     """Convert between format 3 (3.0.x and 3.1.x) and draft IR v4.
 
@@ -194,7 +224,9 @@ def convert(
                 upgraded = Ok(migrated.value, migrated.warnings)
             if drop_input_attributes:
                 upgraded = drop_inputs(upgraded.value)
-            document = v4_codec.encode_versioned_distribution(upgraded.value)
+            document = v4_codec.encode_versioned_distribution(
+                upgraded.value, spelling=v4_codec.Spelling(v4_spelling.value)
+            )
             warnings: tuple[Diagnostic, ...] = upgraded.warnings
         else:
             if not _is_v4(version):
@@ -218,6 +250,165 @@ def convert(
     typer.echo(f"wrote {output} (format {to.value})")
 
 
+def _report_compiler(diagnostics: tuple[CompilerDiagnostic, ...]) -> None:
+    for diagnostic in diagnostics:
+        typer.echo(f"{diagnostic.severity.value}: {diagnostic.render()}", err=True)
+
+
+def _fail(message: str) -> typer.Exit:
+    typer.echo(f"error: {message}", err=True)
+    return typer.Exit(1)
+
+
+def _discover(source: Path) -> tuple[Path, list[Path]]:
+    """Return the source root and its Python files, sorted, without following links."""
+    if source.is_dir() and not source.is_symlink():
+        files: list[Path] = []
+        for directory, names, filenames in os.walk(source, followlinks=False):
+            names[:] = sorted(
+                name
+                for name in names
+                if not name.startswith(".") and name != "__pycache__"
+            )
+            files.extend(
+                Path(directory) / name
+                for name in sorted(filenames)
+                if name.endswith(".py") and not (Path(directory) / name).is_symlink()
+            )
+        if not files:
+            raise _fail(f"no Python source files under {source}")
+        return source, files
+    return source.parent, [source]
+
+
+@app.command("compile")
+def compile_command(
+    source: Annotated[
+        Path, typer.Argument(help="A Python file, or a directory of Python files.")
+    ],
+    package: Annotated[
+        str, typer.Option(help="Morphir package name, such as acme/example.")
+    ],
+    output: Annotated[
+        Path, typer.Option("--output", "-o", help="Where to write the IR document.")
+    ],
+    ir_version: Annotated[
+        Target, typer.Option("--ir-version", help="The IR version to write.")
+    ] = Target.V3,
+    expose: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--expose",
+            help="Module to make public, such as acme/models. Repeat for more. "
+            "Without it every module is public.",
+        ),
+    ] = None,
+) -> None:
+    """Compile supported Python source to a versioned Morphir IR Library.
+
+    A directory is compiled as one package; a single file uses its parent
+    directory as the source root. Sources are parsed, never imported or run.
+    The output is written to a temporary file and renamed only on success, so a
+    failed compilation leaves an existing output file unchanged.
+    """
+    from .python import (  # Loads the compiler on demand.
+        CompiledV3,
+        CompileFailure,
+        IrVersion,
+        NativeCompilerError,
+        NativeCompilerUnavailable,
+        SourceDocument,
+        compile_sources,
+    )
+
+    root, files = _discover(source)
+    documents = [
+        SourceDocument(path.relative_to(root).as_posix(), _read(path)) for path in files
+    ]
+    version = IrVersion.V3 if ir_version is Target.V3 else IrVersion.V4
+    try:
+        result = compile_sources(
+            documents,
+            package=package,
+            exposed_modules=expose,
+            ir_version=version,
+        )
+    except (ValueError, NativeCompilerUnavailable) as error:
+        raise _fail(str(error)) from None
+    except NativeCompilerError as error:
+        raise _fail(f"internal compiler error: {error}") from None
+    if isinstance(result, CompileFailure):
+        _report_compiler(result.diagnostics)
+        raise typer.Exit(1)
+    if isinstance(result, CompiledV3):
+        document = v3_codec.encode_versioned_distribution(result.distribution)
+    else:
+        document = v4_codec.encode_versioned_distribution(result.distribution)
+    try:
+        _write_atomically(output, fv.dump_json(document))
+    except OSError as error:
+        raise _fail(f"cannot write {output}: {error.strerror}") from None
+    _report_compiler(result.warnings)
+    typer.echo(f"wrote {output} (format {ir_version.value})")
+    if ir_version is Target.V4:
+        typer.echo(f"note: {v4_codec.DRAFT_NOTICE}")
+
+
+@app.command("generate")
+def generate_command(
+    file: Annotated[Path, typer.Argument(help="A versioned morphir-ir.json file.")],
+    output_dir: Annotated[
+        Path,
+        typer.Option(
+            "--output-dir", help="A new or empty directory for the Python modules."
+        ),
+    ],
+) -> None:
+    """Generate Python modules from a format 3.0 or draft v4 Library.
+
+    Module paths are preserved under the output directory. All files are written
+    to a staging directory first and published together, so a failure leaves no
+    partial output. Legacy formats 1 and 2 must be upgraded with ir convert first.
+    """
+    from .python import (  # Loads the compiler on demand.
+        GenerationFailure,
+        NativeCompilerError,
+        NativeCompilerUnavailable,
+        generate_python,
+    )
+
+    text = _read(file)
+    try:
+        version, _ = fv.read_document(text)
+        model: object = (
+            v4_codec.decode_versioned_distribution(text)
+            if _is_v4(version)
+            else v3_codec.decode_versioned_distribution(text)
+        )
+    except DiagnosticError as error:
+        _report(error.diagnostics)
+        raise typer.Exit(1) from None
+    try:
+        result = generate_python(model)
+    except NativeCompilerUnavailable as error:
+        raise _fail(str(error)) from None
+    except NativeCompilerError as error:
+        raise _fail(f"internal compiler error: {error}") from None
+    if isinstance(result, GenerationFailure):
+        _report_compiler(result.diagnostics)
+        raise typer.Exit(1)
+    files = [(artifact.path, artifact.text) for artifact in result.artifacts]
+    try:
+        validate_artifact_paths(path for path, _ in files)
+        publish_tree(output_dir, files)
+    except OutputError as error:
+        raise _fail(str(error)) from None
+    except OSError as error:
+        raise _fail(f"cannot write {output_dir}: {error.strerror}") from None
+    _report_compiler(result.warnings)
+    typer.echo(f"wrote {len(files)} modules to {output_dir}")
+
+
 def main() -> None:
     """Run the ``morphir-python`` command line."""
     app()

morphir_python-0.1.0/src/morphir_tools/python/__init__.py

@@ -0,0 +1,71 @@
+r"""Compile Python to Morphir IR and generate Python from Morphir IR.
+
+This is the typed, in-process API behind ``morphir-python compile`` and
+``morphir-python generate``. A native compiler does the work; callers need
+neither Rust nor a separate Morphir executable, and the native compiler loads
+only when one of these functions is first called.
+
+Example:
+    >>> from morphir_tools.python import SourceDocument, compile_sources
+    >>> from morphir_tools.python import CompiledV3, generate_python
+    >>> source = SourceDocument(
+    ...     "rules.py",
+    ...     "def choose(flag: bool, a: int, b: int) -> int:\n"
+    ...     "    return a if flag else b\n",
+    ... )
+    >>> compiled = compile_sources([source], package="acme/example")
+    >>> isinstance(compiled, CompiledV3)
+    True
+    >>> generated = generate_python(compiled.distribution)
+    >>> [artifact.path for artifact in generated.artifacts]
+    ['rules.py']
+"""
+
+from ._api import compile_sources, generate_python, native_compiler
+from ._bridge import EXPECTED_BRIDGE_API, EXPECTED_NATIVE_VERSION
+from ._types import (
+    CompiledV3,
+    CompiledV4,
+    CompileFailure,
+    CompilerDiagnostic,
+    CompileResult,
+    Generated,
+    GeneratedArtifact,
+    GenerateResult,
+    GenerationFailure,
+    IrVersion,
+    LibraryModel,
+    NativeCompilerError,
+    NativeCompilerInfo,
+    NativeCompilerUnavailable,
+    Severity,
+    SourceDocument,
+    SourceLocation,
+    SourcePosition,
+)
+
+__all__ = [
+    "EXPECTED_BRIDGE_API",
+    "EXPECTED_NATIVE_VERSION",
+    "CompileFailure",
+    "CompileResult",
+    "CompiledV3",
+    "CompiledV4",
+    "CompilerDiagnostic",
+    "GenerateResult",
+    "Generated",
+    "GeneratedArtifact",
+    "GenerationFailure",
+    "IrVersion",
+    "LibraryModel",
+    "NativeCompilerError",
+    "NativeCompilerInfo",
+    "NativeCompilerUnavailable",
+    "Severity",
+    "SourceDocument",
+    "SourceLocation",
+    "SourcePosition",
+    "compile_sources",
+    "generate_python",
+    "native_compiler",
+]

morphir_python-0.1.0/src/morphir_tools/python/_api.py

@@ -0,0 +1,215 @@
+"""Compile Python sources to Morphir IR and generate Python from IR."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, cast
+
+from morphir.ir import format_version as fv
+from morphir.ir.diagnostics import DiagnosticError
+from morphir.ir.v3 import codec as v3_codec
+from morphir.ir.v3 import distribution as v3_dist
+from morphir.ir.v4 import codec as v4_codec
+from morphir.ir.v4 import distribution as v4_dist
+
+from . import _bridge
+from . import diagnostics as codes
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Mapping, Sequence
+
+from ._types import (
+    CompiledV3,
+    CompiledV4,
+    CompileFailure,
+    CompilerDiagnostic,
+    CompileResult,
+    Generated,
+    GeneratedArtifact,
+    GenerateResult,
+    GenerationFailure,
+    IrVersion,
+    LibraryModel,
+    NativeCompilerError,
+    NativeCompilerInfo,
+    Severity,
+    SourceDocument,
+    SourceLocation,
+    SourcePosition,
+)
+
+
+def native_compiler() -> NativeCompilerInfo:
+    """Load the native compiler and report its identity.
+
+    Raises:
+        NativeCompilerUnavailable: When it is missing or incompatible.
+    """
+    return _bridge.load()
+
+
+def compile_sources(
+    sources: Iterable[SourceDocument],
+    *,
+    package: str,
+    exposed_modules: Sequence[str] | None = None,
+    ir_version: IrVersion = IrVersion.V3,
+) -> CompileResult:
+    """Compile Python source documents to a Morphir IR Library.
+
+    The sources are parsed statically: nothing is imported or executed. The
+    order of ``sources`` does not affect the result.
+
+    Args:
+        sources: The documents of one package, with paths relative to its root.
+        package: The Morphir package name, such as ``"acme/example"``.
+        exposed_modules: Module paths to make public, such as
+            ``("acme/models",)``. ``None`` exposes every module; an empty
+            sequence exposes none.
+        ir_version: The IR version to write. Defaults to stable v3.
+
+    Returns:
+        A `CompiledV3` or `CompiledV4` holding the decoded Library, or a
+        `CompileFailure` with at least one diagnostic and no model.
+
+    Raises:
+        ValueError: When ``package`` is empty or two documents share a path.
+        NativeCompilerUnavailable: When the native compiler is missing or
+            incompatible.
+        NativeCompilerError: When the native compiler fails internally.
+    """
+    documents = sorted(sources, key=lambda document: document.path)
+    if not package:
+        raise ValueError("package must name a Morphir package")
+    paths = [document.path for document in documents]
+    if len(set(paths)) != len(paths):
+        raise ValueError("source documents contain a duplicate path")
+    request = {
+        "package": package,
+        "sources": [{"path": d.path, "text": d.text} for d in documents],
+        "exposedModules": None if exposed_modules is None else list(exposed_modules),
+        "irVersion": ir_version.value,
+    }
+    output = _call(_bridge.module().compile, json.dumps(request))
+    diagnostics = _diagnostics(output)
+    ir = output.get("ir")
+    if not output.get("success") or not isinstance(ir, str):
+        return CompileFailure(diagnostics or (_missing_diagnostic(),))
+    try:
+        if ir_version is IrVersion.V3:
+            classic = v3_codec.decode_versioned_distribution(ir)
+            if isinstance(classic, v3_dist.Library):
+                return CompiledV3(classic, diagnostics)
+        else:
+            draft = v4_codec.decode_versioned_distribution(ir)
+            if isinstance(draft, v4_dist.LibraryDistribution):
+                return CompiledV4(draft, diagnostics)
+    except DiagnosticError as error:
+        return CompileFailure(_ir_diagnostics(error))
+    raise NativeCompilerError("the native compiler returned a non-Library model")
+
+
+def generate_python(distribution: LibraryModel | object) -> GenerateResult:
+    """Generate Python modules from a v3 or draft v4 Library model.
+
+    Args:
+        distribution: A `morphir.ir.v3.distribution.Library` or
+            `morphir.ir.v4.distribution.LibraryDistribution`. Specs and
+            Application distributions are rejected with a diagnostic.
+
+    Returns:
+        `Generated` with one artifact per module, in path order, or a
+        `GenerationFailure` with at least one diagnostic and no artifacts.
+
+    Raises:
+        NativeCompilerUnavailable: When the native compiler is missing or
+            incompatible.
+        NativeCompilerError: When the native compiler fails internally.
+    """
+    try:
+        match distribution:
+            case v3_dist.Library():
+                document = v3_codec.encode_versioned_distribution(distribution)
+            case v4_dist.LibraryDistribution():
+                document = v4_codec.encode_versioned_distribution(distribution)
+            case _:
+                kind = type(distribution).__name__
+                return GenerationFailure(
+                    (
+                        CompilerDiagnostic(
+                            codes.UNSUPPORTED_DISTRIBUTION,
+                            Severity.ERROR,
+                            "Python generation needs a Library distribution, "
+                            f"not {kind}",
+                        ),
+                    )
+                )
+    except DiagnosticError as error:
+        return GenerationFailure(_ir_diagnostics(error))
+    output = _call(_bridge.module().generate, fv.dump_json(document))
+    diagnostics = _diagnostics(output)
+    raw = output.get("artifacts")
+    if not output.get("success") or not isinstance(raw, list):
+        return GenerationFailure(diagnostics or (_missing_diagnostic(),))
+    artifacts = tuple(
+        sorted(
+            (
+                GeneratedArtifact(str(item["path"]), str(item["content"]))
+                for item in cast("list[Mapping[str, object]]", raw)
+            ),
+            key=lambda artifact: artifact.path,
+        )
+    )
+    return Generated(artifacts, diagnostics)
+
+
+def _call(function: Callable[[str], str], argument: str) -> Mapping[str, object]:
+    output = cast("Mapping[str, object]", json.loads(function(argument)))
+    internal = output.get("internalError")
+    if internal is not None:
+        raise NativeCompilerError(str(internal))
+    return output
+
+
+def _missing_diagnostic() -> CompilerDiagnostic:
+    return CompilerDiagnostic(
+        codes.PY_SERIALIZATION,
+        Severity.ERROR,
+        "the native compiler failed without a diagnostic",
+    )
+
+
+def _diagnostics(output: Mapping[str, object]) -> tuple[CompilerDiagnostic, ...]:
+    items = cast("list[Mapping[str, object]]", output.get("diagnostics") or [])
+    return tuple(_diagnostic(item) for item in items)
+
+
+def _diagnostic(item: Mapping[str, object]) -> CompilerDiagnostic:
+    location = cast("Mapping[str, object] | None", item.get("location"))
+    source = None
+    if location is not None:
+        start = cast("Mapping[str, int]", location["start"])
+        end = cast("Mapping[str, int]", location["end"])
+        source = SourceLocation(
+            str(location["path"]),
+            SourcePosition(start["line"], start["character"]),
+            SourcePosition(end["line"], end["character"]),
+        )
+    return CompilerDiagnostic(
+        code=str(item.get("code") or codes.PY_SERIALIZATION),
+        severity=Severity(str(item["severity"])),
+        message=str(item["message"]),
+        source=source,
+    )
+
+
+def _ir_diagnostics(error: DiagnosticError) -> tuple[CompilerDiagnostic, ...]:
+    return tuple(
+        CompilerDiagnostic(
+            code=item.code,
+            severity=Severity.ERROR,
+            message=item.message,
+            ir_path=item.location,
+        )
+        for item in error.diagnostics
+    )

morphir_python-0.1.0/src/morphir_tools/python/_bridge.py

@@ -0,0 +1,84 @@
+"""Lazy loading and compatibility checks for the private native compiler."""
+
+from __future__ import annotations
+
+import functools
+from importlib import import_module, metadata
+from typing import Protocol, cast
+
+from ._types import NativeCompilerInfo, NativeCompilerUnavailable
+
+EXPECTED_NATIVE_VERSION = "0.1.1"
+"""The exact ``morphir-python-native`` version this release was qualified with.
+
+It must equal the pin in this distribution's ``pyproject.toml``.
+"""
+
+EXPECTED_BRIDGE_API = 1
+"""The bridge contract revision this release speaks."""
+
+_DISTRIBUTION = "morphir-python-native"
+
+
+class NativeModule(Protocol):
+    """The private ``morphir_python_native._native`` module."""
+
+    BRIDGE_API: int
+    COMPILER_VERSION: str
+    __version__: str
+
+    def compile(self, request: str) -> str:
+        """Compile a JSON request."""
+        ...
+
+    def generate(self, ir: str) -> str:
+        """Generate Python from IR JSON text."""
+        ...
+
+
+def _unavailable(detail: str) -> NativeCompilerUnavailable:
+    return NativeCompilerUnavailable(
+        f"the Morphir Python compiler is unavailable: {detail}. Reinstall "
+        f"morphir-python, which requires {_DISTRIBUTION}=={EXPECTED_NATIVE_VERSION}."
+    )
+
+
+@functools.cache
+def load() -> NativeCompilerInfo:
+    """Import the native module once and check that this release can use it.
+
+    Raises:
+        NativeCompilerUnavailable: When the module is missing, or its
+            distribution version, module version or bridge revision differ from
+            what this release expects.
+    """
+    try:
+        installed = metadata.version(_DISTRIBUTION)
+    except metadata.PackageNotFoundError:
+        raise _unavailable(f"{_DISTRIBUTION} is not installed") from None
+    try:
+        native = cast("NativeModule", import_module("morphir_python_native._native"))
+    except ImportError as error:
+        raise _unavailable(f"its native module cannot be imported ({error})") from None
+    if installed != EXPECTED_NATIVE_VERSION:
+        raise _unavailable(
+            f"{_DISTRIBUTION} {installed} is installed but this release needs "
+            f"{EXPECTED_NATIVE_VERSION}"
+        )
+    if native.__version__ != installed:
+        raise _unavailable(
+            f"the native module reports {native.__version__} but its distribution "
+            f"is {installed}"
+        )
+    if native.BRIDGE_API != EXPECTED_BRIDGE_API:
+        raise _unavailable(
+            f"bridge revision {native.BRIDGE_API} differs from the expected "
+            f"{EXPECTED_BRIDGE_API}"
+        )
+    return NativeCompilerInfo(installed, native.BRIDGE_API, native.COMPILER_VERSION)
+
+
+def module() -> NativeModule:
+    """Return the checked native module, loading it on first use."""
+    load()
+    return cast("NativeModule", import_module("morphir_python_native._native"))

morphir_python-0.1.0/src/morphir_tools/python/_types.py

@@ -0,0 +1,201 @@
+"""Immutable inputs and results of the Python compiler API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from morphir.ir.v3 import distribution as v3_dist
+from morphir.ir.v4 import distribution as v4_dist
+
+
+class IrVersion(Enum):
+    """The Morphir IR version a compilation writes."""
+
+    V3 = "3"
+    """Stable format 3.0.0."""
+    V4 = "4"
+    """Draft format 4.0.0."""
+
+
+class Severity(Enum):
+    """How serious a compiler diagnostic is."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+    HINT = "hint"
+
+
+@dataclass(frozen=True)
+class SourceDocument:
+    """One Python source file to compile.
+
+    Attributes:
+        path: Path relative to the source root, with ``/`` separators, such as
+            ``"acme/rules.py"``. It decides the Morphir module name.
+        text: The complete source text. It is parsed, never imported or run.
+    """
+
+    path: str
+    text: str
+
+
+@dataclass(frozen=True)
+class SourcePosition:
+    """A zero-based line and UTF-16 character offset in a source document."""
+
+    line: int
+    character: int
+
+
+@dataclass(frozen=True)
+class SourceLocation:
+    """A half-open range in one source document."""
+
+    path: str
+    start: SourcePosition
+    end: SourcePosition
+
+
+@dataclass(frozen=True)
+class CompilerDiagnostic:
+    """A problem reported by compilation or generation.
+
+    Attributes:
+        code: Stable code from `morphir_tools.python.diagnostics` or
+            `morphir.ir.diagnostics`.
+        severity: How serious the problem is.
+        message: Human-readable explanation. Callers must not parse it.
+        source: The source range, when the problem is in a source document.
+        ir_path: Path from the IR document root, when the problem is in IR.
+    """
+
+    code: str
+    severity: Severity
+    message: str
+    source: SourceLocation | None = None
+    ir_path: tuple[str | int, ...] = ()
+
+    def render(self) -> str:
+        """Render as ``code at location: message``, like IR diagnostics.
+
+        Source locations are written ``path:line:column`` with one-based line and
+        column numbers.
+        """
+        if self.source is not None:
+            start = self.source.start
+            where = f"{self.source.path}:{start.line + 1}:{start.character + 1}"
+        elif self.ir_path:
+            where = "/".join(str(part) for part in self.ir_path)
+        else:
+            where = "<request>"
+        return f"{self.code} at {where}: {self.message}"
+
+
+def _warnings_only(diagnostics: tuple[CompilerDiagnostic, ...]) -> None:
+    if any(item.severity is Severity.ERROR for item in diagnostics):
+        raise ValueError("a successful result cannot carry error diagnostics")
+
+
+def _not_empty(diagnostics: tuple[CompilerDiagnostic, ...]) -> None:
+    if not diagnostics:
+        raise ValueError("a failure needs at least one diagnostic")
+
+
+@dataclass(frozen=True)
+class CompiledV3:
+    """A successful compilation to a format 3.0.0 Library."""
+
+    distribution: v3_dist.Library
+    warnings: tuple[CompilerDiagnostic, ...] = ()
+
+    def __post_init__(self) -> None:
+        _warnings_only(self.warnings)
+
+
+@dataclass(frozen=True)
+class CompiledV4:
+    """A successful compilation to a draft format 4.0.0 Library."""
+
+    distribution: v4_dist.LibraryDistribution
+    warnings: tuple[CompilerDiagnostic, ...] = ()
+
+    def __post_init__(self) -> None:
+        _warnings_only(self.warnings)
+
+
+@dataclass(frozen=True)
+class CompileFailure:
+    """A compilation that produced no model."""
+
+    diagnostics: tuple[CompilerDiagnostic, ...]
+
+    def __post_init__(self) -> None:
+        _not_empty(self.diagnostics)
+
+
+type CompileResult = CompiledV3 | CompiledV4 | CompileFailure
+
+
+@dataclass(frozen=True)
+class GeneratedArtifact:
+    """One generated Python module.
+
+    Attributes:
+        path: Path relative to the output root, with ``/`` separators.
+        text: The module source.
+    """
+
+    path: str
+    text: str
+
+
+@dataclass(frozen=True)
+class Generated:
+    """Successful generation: every module of the input Library."""
+
+    artifacts: tuple[GeneratedArtifact, ...]
+    warnings: tuple[CompilerDiagnostic, ...] = ()
+
+    def __post_init__(self) -> None:
+        _warnings_only(self.warnings)
+
+
+@dataclass(frozen=True)
+class GenerationFailure:
+    """A generation that produced no artifacts."""
+
+    diagnostics: tuple[CompilerDiagnostic, ...]
+
+    def __post_init__(self) -> None:
+        _not_empty(self.diagnostics)
+
+
+type GenerateResult = Generated | GenerationFailure
+
+type LibraryModel = v3_dist.Library | v4_dist.LibraryDistribution
+"""A Library model that generation accepts."""
+
+
+@dataclass(frozen=True)
+class NativeCompilerInfo:
+    """Identity of the loaded native compiler.
+
+    Attributes:
+        version: Version of the ``morphir-python-native`` distribution and module.
+        bridge_api: Revision of the private bridge contract.
+        compiler_version: Version of the linked ``morphir-python-binding`` crate.
+    """
+
+    version: str
+    bridge_api: int
+    compiler_version: str
+
+
+class NativeCompilerUnavailable(ImportError):  # noqa: N818 - reads as a state
+    """The native compiler is missing or incompatible with this release."""
+
+
+class NativeCompilerError(RuntimeError):
+    """The native compiler failed internally; this is a bug, not a user error."""

morphir_python-0.1.0/src/morphir_tools/python/diagnostics.py

@@ -0,0 +1,33 @@
+"""Diagnostic codes reported by the Python compiler API.
+
+Every code the API can report lives in this module, as `morphir.ir.diagnostics`
+does for the IR readers and codecs.
+
+- ``PY001`` to ``PY006`` come from the native ``morphir-python-binding`` compiler.
+  They are the same codes its MEP extension reports, so Rust, WASM and Python
+  callers see one vocabulary.
+- ``unsupported_distribution`` is local to this API: generation accepts only a
+  Library distribution.
+- Decoding and encoding failures keep the `morphir.ir.diagnostics` code that the
+  codec reported, such as ``unknown_node`` or ``no_v4_spelling``.
+"""
+
+from __future__ import annotations
+
+# Native compiler (morphir-python-binding).
+PY_REQUEST = "PY001"
+"""Unsupported request or option."""
+PY_SYNTAX = "PY002"
+"""Python syntax error, with a source range."""
+PY_NAME = "PY003"
+"""Invalid name or naming collision."""
+PY_UNSUPPORTED = "PY004"
+"""Unsupported declaration, annotation or IR feature."""
+PY_SERIALIZATION = "PY005"
+"""IR decoding or serialization, or generated syntax failure."""
+PY_PARSE_STAGE = "PY006"
+"""Parse-stage output was requested but is unavailable."""
+
+# Python API (morphir-python).
+UNSUPPORTED_DISTRIBUTION = "unsupported_distribution"
+"""Generation received a Specs or Application distribution."""