Morphir Python

Read the documentation site for installation, API examples and CLI workflows.

CLI tools and extensions for Morphir Python.

This package provides:

• Command-line interface for Morphir operations
• Code generation backends
• File I/O utilities
• Development tools

Installation

For an isolated CLI installation managed by mise, use one of the verified mise/uv or mise/pipx configurations. mise manages Python 3.14 and installs the compiled native dependency from a wheel. No Rust toolchain is required on supported platforms.

To install the CLI and compiler API into an existing Python environment:

python -m pip install --only-binary=:all: morphir-python==0.1.2

Or with uv:

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.

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.

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 (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. 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.

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 for the format-version rules and the draft v4 status.

Requirements

• Python 3.14+
• morphir>=0.1.0 and morphir-python-native==0.1.2 (installed as dependencies)

License

Apache-2.0 - see the LICENSE file for details.

Related Packages

• morphir - Core library