morphir-python 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

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_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.0"
+"""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_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_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."""

morphir/__init__.py

@@ -1,14 +0,0 @@
-"""Morphir - Functional domain modeling for Python.
-
-Morphir enables you to write business logic once and use it across multiple
-platforms, languages, and runtimes. It provides a strongly-typed intermediate
-representation (IR) that captures the semantics of your domain model.
-
-Example:
-    >>> import morphir
-    >>> morphir.__version__
-    '0.0.1'
-"""
-
-__version__ = "0.0.1"
-__all__ = ["__version__"]

morphir/ir/__init__.py

@@ -1,110 +0,0 @@
-"""Morphir IR.
-
-The default model is IR v4 (`morphir.ir.v4`); every name here is the same object
-as its `morphir.ir.v4` counterpart. Format 3.0.0 lives in `morphir.ir.v3`.
-"""
-
-from . import module, package
-from .v4.access_controlled import AccessControlled
-from .v4.decorations import (
-    DecorationFormat,
-    DecorationValuesFile,
-    LayerManifest,
-    SchemaRef,
-)
-from .v4.distribution import (
-    ApplicationDistribution,
-    Distribution,
-    EntryPoint,
-    EntryPointKind,
-    LibraryDistribution,
-    PackageInfo,
-    SpecsDistribution,
-)
-from .v4.document import (
-    DocArray,
-    DocBool,
-    DocFloat,
-    DocInt,
-    DocNull,
-    DocObject,
-    DocString,
-    Document,
-)
-from .v4.documented import Documented
-from .v4.fqname import FQName
-from .v4.literal import (
-    BoolLiteral,
-    CharLiteral,
-    DecimalLiteral,
-    FloatLiteral,
-    IntegerLiteral,
-    Literal,
-    StringLiteral,
-)
-from .v4.meta import FileMeta, SourceRange
-from .v4.name import Name
-from .v4.path import Path
-from .v4.qname import QName
-from .v4.ref import DefRef, FileWithDefs, PointerRef, Ref
-from .v4.type import Field, Type, TypeAttributes
-from .v4.type_constraints import TypeConstraints
-from .v4.type_def import Definition as TypeDefinition
-from .v4.type_spec import Specification as TypeSpecification
-from .v4.value import Definition as ValueDefinition
-from .v4.value import Pattern, Value, ValueAttributes
-from .v4.value import Specification as ValueSpecification
-
-__all__ = [
-    "AccessControlled",
-    "ApplicationDistribution",
-    "BoolLiteral",
-    "CharLiteral",
-    "DecimalLiteral",
-    "DecorationFormat",
-    "DecorationValuesFile",
-    "DefRef",
-    "Distribution",
-    "DocArray",
-    "DocBool",
-    "DocFloat",
-    "DocInt",
-    "DocNull",
-    "DocObject",
-    "DocString",
-    "Document",
-    "Documented",
-    "EntryPoint",
-    "EntryPointKind",
-    "FQName",
-    "Field",
-    "FileMeta",
-    "FileWithDefs",
-    "FloatLiteral",
-    "IntegerLiteral",
-    "LayerManifest",
-    "LibraryDistribution",
-    "Literal",
-    "Name",
-    "PackageInfo",
-    "Path",
-    "Pattern",
-    "PointerRef",
-    "QName",
-    "Ref",
-    "SchemaRef",
-    "SourceRange",
-    "SpecsDistribution",
-    "StringLiteral",
-    "Type",
-    "TypeAttributes",
-    "TypeConstraints",
-    "TypeDefinition",
-    "TypeSpecification",
-    "Value",
-    "ValueAttributes",
-    "ValueDefinition",
-    "ValueSpecification",
-    "module",
-    "package",
-]

morphir/ir/access_controlled.py

@@ -1,15 +0,0 @@
-"""Compatibility shim: re-exports `morphir.ir.v4.access_controlled`."""
-
-from morphir.ir.v4.access_controlled import (
-    AccessControlled,
-    Private,
-    Public,
-    T,
-)
-
-__all__ = [
-    "AccessControlled",
-    "Private",
-    "Public",
-    "T",
-]

morphir/ir/decorations.py

@@ -1,19 +0,0 @@
-"""Compatibility shim: re-exports `morphir.ir.v4.decorations`."""
-
-from morphir.ir.v4.decorations import (
-    DecorationFormat,
-    DecorationValuesFile,
-    LayerManifest,
-    SchemaRef,
-    deep_merge,
-    merge_decoration_values,
-)
-
-__all__ = [
-    "DecorationFormat",
-    "DecorationValuesFile",
-    "LayerManifest",
-    "SchemaRef",
-    "deep_merge",
-    "merge_decoration_values",
-]