Python Backend

Choose the Python path when the destination environment already provides Python 3.11 or newer and a readable generated product is useful. Python remains a build target. Python constructs never become Topaz syntax.

Prerequisites

• Complete the study-plan package from First Application.
• Keep its topaz.toml, topaz.lock, src/plan.tpz, src/main.tpz, and selected test together.
• Install Python 3.11 or newer on the destination machine.
• Run the following commands from the study-plan directory.

The product requires neither the Topaz compiler nor .tpz files at runtime. It includes generated Python source code and its support module, so it is not a native binary.

Shared checked package

The same two Topaz modules are used on the Rust page. First, src/plan.tpz:

export record StudyTask {
    title: string,
    minutes: int,
    done: bool = false,
}

function parseMinutes(text: string) -> Result<int, string> {
    match toInt(text) {
        case Some(value) if value > 0 => Ok(value)
        case _ => Err("minutes must be a positive integer")
    }
}

export function makeTask(
    title: string,
    minuteText: string,
    done: bool = false,
) -> Result<StudyTask, string> {
    let minutes = parseMinutes(minuteText)?
    Ok(StudyTask { title: title, minutes: minutes, done: done })
}

export function summarize(tasks: Array<StudyTask>) -> string {
    let mut remaining = 0
    for task in tasks {
        if !task.done {
            remaining = remaining + task.minutes
        }
    }
    "tasks={tasks.length}, remaining={remaining} minutes"
}

The package entry src/main.tpz:

import src.plan { StudyTask, makeTask, summarize }

export function main(args: Array<string>, stdin: string) -> Result<int, string> {
    let tasks: Array<StudyTask> = [
        makeTask("Run first program", "10", true)?,
        makeTask("Build application", "25", false)?,
    ]
    print(summarize(tasks))
    Ok(0)
}

Verify the Topaz source

Check the package, run the selected test, and establish the reference output:

topaz check --root . --locked
topaz test tests/plan.tpz --root . --locked
topaz run --root . --locked

The test reports tests/plan.tpz: test-ok. The run prints:

tasks=2, remaining=25 minutes

Emit for inspection, build for delivery

Use emit only when you need to inspect or integrate the generated Python source:

topaz emit --target python --root . --locked --out-dir ../dist/python-source

Use build for the complete managed Python product:

topaz build --target python --root . --locked --out-dir ../dist/python

Run program.py explicitly after building it. Python builds reject --run and --release. Neither is a Python-product switch. Rust's --backend option is not valid for a Python build either.

Inspect the managed product

The product contains:

dist/python/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── program.py
├── topaz-artifact.json
└── topaz_py_rt.py

topaz-artifact.json records target python, the Python 3.11-or-newer runtime requirement, invocation details, and the size and SHA-256 hash of every managed file. Topaz writes the manifest last and rejects a modified managed file, an unsafe collision, or a different target in the same output directory. Ship the complete tree. program.py and topaz_py_rt.py belong together, and the notices, license, and manifest remain part of the managed product.

Run after the Topaz source is unavailable

Because dist is located outside the package, move the source package aside and run only the product:

cd ..
mv study-plan source-unavailable
python3 dist/python/program.py

On Windows, use Rename-Item study-plan source-unavailable, then run python dist\python\program.py. The product exits with code 0 and prints the output shown above.

Target-specific recovery

The Python backend reports unsupported standard-library operations before writing an artifact and points to the corresponding source location. In particular, Codec.deflateFixedCompress, Codec.zlibFixedCompress, and Codec.reedSolomon255223Protect are unavailable on this target. Keep those operations on a supported target or select another implementation before rebuilding.

If program.py cannot import topaz_py_rt.py, restore the complete managed tree instead of copying a single generated file by itself. If Python is too old, install Python 3.11 or newer on the destination.

Exact boundary

Generated Python is a replaceable deployment artifact, not a stable handwritten extension API or native binary. A successful run establishes this program's output and exit code in the selected Python environment. It does not expose arbitrary Python libraries, exceptions, decorators, or package APIs to .tpz source code.

The Lispex application profile is not a generated Python capability. Packages that reach it are refused before Python artifact output. Use Run Lispex Rules to choose the interpreter or an admitted native target.

Continue with Interop Boundaries, Rust Backend, Interpreter & Backends, or Artifacts & Deployment.