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

morphir_python-0.0.3.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: morphir-python
+Version: 0.0.3
+Summary: CLI tools and extensions for Morphir Python
+Project-URL: Homepage, https://github.com/finos/morphir-python
+Project-URL: Documentation, https://morphir.finos.org
+Project-URL: Repository, https://github.com/finos/morphir-python
+Project-URL: Issues, https://github.com/finos/morphir-python/issues
+Author-email: FINOS <morphir@finos.org>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cli,code-generation,domain-modeling,morphir,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: morphir-python-native==0.1.0
+Requires-Dist: morphir>=0.0.2
+Requires-Dist: pygments>=2.20.0
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# Morphir Python
+
+CLI tools and extensions for [Morphir Python](https://github.com/finos/morphir-python).
+
+This package provides:
+
+- Command-line interface for Morphir operations
+- Code generation backends
+- File I/O utilities
+- Development tools
+
+## Installation
+
+```bash
+pip install morphir-python
+```
+
+Or with uv:
+
+```bash
+uv add morphir-python
+```
+
+The `morphir-python` distribution contains the CLI and depends on the separate
+`morphir` library/SDK distribution. Python imports remain `morphir` and
+`morphir_tools`. Version 0.0.1 was a bundle; for migration to CLI-only 0.0.2, see
+the [repository installation guide](../../README.md#migrating-from-the-bundled-001-release).
+
+## Usage
+
+The `morphir-python` command inspects and converts versioned `morphir-ir.json`
+files. It reads format 3.0.x (what morphir-elm writes), format 3.1.x (which adds
+the v3 `Specs` distribution) and draft IR 4.0.x, reads the legacy formats 1 and 2
+to upgrade them, and uses the `morphir` library for every read, write, and
+migration.
+
+```bash
+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
+```
+
+`inspect` prints the normalized format version, the distribution kind
+(`Library`, `Specs` or `Application`), and the package name, and labels v4 as
+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.
+`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`.
+
+Exit codes are 0 for success (also with warnings), 1 for a diagnostic, and 2 for
+a usage error. 3.x releases from 3.2.0 on are rejected; see the
+[morphir package README](../morphir/README.md#morphir-ir-versions) for the
+format-version rules and the draft v4 status.
+
+## Requirements
+
+- Python 3.14+
+- `morphir>=0.0.2` and `morphir-python-native==0.1.0` (installed as dependencies)
+
+## License
+
+Apache-2.0 - see the [LICENSE](../../LICENSE) file for details.
+
+## Related Packages
+
+- [morphir](https://pypi.org/project/morphir/) - Core library

morphir_python-0.0.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+morphir_tools/__init__.py,sha256=s0PyppW1YjLdjPHMZbu4KNEPRQYhAj7hHresVUTSyY0,348
+morphir_tools/_output.py,sha256=6mWIWg0vjM8pxcnRdegbGix_yqwClpR0gX2cqrdOcKo,4004
+morphir_tools/cli.py,sha256=DZiWPlJp8CNj4zLK7fGOrPy7LuuznRFo-BngrK85fjw,14356
+morphir_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+morphir_tools/python/__init__.py,sha256=5ufqFJLyatrEDxtS2zaL1j4yeKp_6IehQFIpL14wTFg,1995
+morphir_tools/python/_api.py,sha256=Wfm8MBGryA1QCB97FFPiQB3bYpkea9emRrZrngc4NBg,7716
+morphir_tools/python/_bridge.py,sha256=VN86T8tlgx7maoEwXKAkxR4nD7tbs-Fux_rUmYjQ4zo,2822
+morphir_tools/python/_types.py,sha256=9uQW1UeqRmp4tdJIdpDF6iLUDA2BRoV6y-5FtzjgIcs,5330
+morphir_tools/python/diagnostics.py,sha256=C3EOuOFwYL-K992L_kKuMlBwTwi7muP64mOCak8EG3c,1292
+morphir_python-0.0.3.dist-info/METADATA,sha256=d9jXyZt_jaLG95I5vGiB1gi6aP-SHJL6myEpBKFoTiw,3614
+morphir_python-0.0.3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+morphir_python-0.0.3.dist-info/entry_points.txt,sha256=ig7-ByPyqCN0S13AuOguSP9qT1npyySP6hVL32naLxA,58
+morphir_python-0.0.3.dist-info/licenses/LICENSE,sha256=tAkwu8-AdEyGxGoSvJ2gVmQdcicWw3j1ZZueVV74M-E,11357
+morphir_python-0.0.3.dist-info/RECORD,,

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.1'
+    '0.0.3'
 """
 
-__version__ = "0.0.1"
+__version__ = "0.0.3"
 __all__ = ["__version__"]

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_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.",
@@ -63,6 +72,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 +83,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)
@@ -218,6 +233,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_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",
+]