python

Functions¶

Import this provider export for Python extern bindings:

use plugin python::{python}

extern python fn add(a: int, b: int) -> int {
    return a + b
}

extern python fn root(value: float) -> float {
    import math
    return math.sqrt(value)
}

print(add(20, 22))
print(root(81.0))

The function signature uses Zolo types and its body uses Python. Calls behave like ordinary Zolo functions. Import the provider explicitly; an alias keeps the same behavior. Python indentation, comments, strings and local imports are preserved. Group several functions with extern python { ... } or capture Zolo values in an expression block with an annotated result type.

int preserves signed 64-bit values exactly. Bytes remain binary, arrays retain nil slots and empty shape, and typed structs become copied records. Returned callables use normal call syntax. Live Python objects retain state and identity.

Async and imports¶

extern python async fn later(value: int) -> int {
    import asyncio
    await asyncio.sleep(0.001)
    return value + 1
}

extern python from "./tools.py" use {twice, Counter}

print(await later(41))
print(twice(21))

Async bindings return normal Futures; callbacks may also return Futures. Exceptions use try/catch. Cancellation requests cancellation of the Python task and does not forcibly interrupt native blocking operations.

Source imports expose annotated functions and classes. Relative paths follow the Zolo source file. extern python mod declares a native module inline. Imports inside function bodies preserve their normal invocation timing.

Package dependencies¶

use plugin python::{python}

extern python deps {
    numpy = "2.3.3"
    httpx = { version = "0.28.1", extras = ["http2"] }
}

Declare packages once at file scope, or use [foreign.python.dependencies] in zolo.toml with [packages] schema = 2. Standalone scripts prepare packages on the first run; projects default to explicit zolo install. Exact pins and native requirement ranges resolve into the shared Zolo lock. --offline --frozen consumes verified locked packages without changing the graph. Libraries are isolated from system site-packages and included in prepared runtime artifacts.

This adapter installs binary wheels only. The package interpreter must match the selected CPython shared library; incompatible native environments fail before authored imports run. One executing CPython process admits one dependency environment, while editor analysis can inspect separate document environments. See foreign dependencies.

Runtime and editor¶

The plugin embeds CPython in the process. Select a complete conventional CPython 3.9–3.14 installation with the GIL using ZOLO_PYTHON_HOME and optionally ZOLO_PYTHON_LIBRARY before first use. Declare packages with extern python deps or the project manifest; the package environment is separate from that interpreter installation. Without dependency declarations, ZOLO_PYTHON_PATH adds legacy module search directories and third-party libraries need their own installation. Inherited PYTHONHOME and PYTHONPATH do not select the provider environment.

Windows startup isolates Python's streams from host input reads. Its version-checked bootstrap uses provisional CPython APIs, so unknown versions and free-threaded builds are rejected. The host's standard handles remain unchanged.

Diagnostics, completion, hover, signature help and Python semantic tokens analyze current source without executing authored code. Python's dynamic behavior limits what can be inferred statically. VM, native and LLVM share the provider contract; wasm without a CPython host rejects the binding.

Executable packaging retains source artifacts and declared package closures. CPython remains an external runtime dependency; undeclared packages found through legacy paths need their own deployment. This experimental provider is verified on Windows with CPython 3.12 and NumPy across VM/native/LLVM, including execution after source files are removed. Linux/macOS and other interpreter versions have not yet been verified at runtime.