libdeno Python API

This is a private alpha Python binding for the Rust libdeno runtime. The Python distribution and core Rust crate are both versioned at 0.3.4. The contract is deliberately small, synchronous, and fail-closed:

import libdeno

exit_code = libdeno.run(
    "entry.js",
    permissions=("--allow-read=.",),
    args=("app-arg",),
)

runtime = libdeno.Runtime(cwd=None)
exit_code = runtime.run("entry.js", allow_all_permissions=True)

run() and Runtime.run() block until the script and its event loop finish and return an integer exit code. The native call releases the Python GIL while the Rust runtime executes. Runtime reuses its resolver stack while permissions, module graphs, and isolates remain per run.

entry and cwd accept str, bytes, and os.PathLike values, including non-ASCII paths. cwd=None (or an omitted cwd) means the process current directory. For Runtime, that directory is fixed when the object is created; the process cwd is never changed. Options after entry are keyword-only.

The Python binding does not expose output capture, async APIs, subprocess helpers, or permission hooks. Script-level Deno APIs still follow the Rust runtime's permission model.

Options and limits

• permissions contains CLI-style --allow-* capability strings. An empty sequence is rejected with ConfigurationError unless allow_all_permissions=True is explicit. -A/--allow-all is equivalent.
• args are exposed through process.argv; features optionally selects valid Deno unstable feature names. None keeps the runtime defaults.
• execution_deadline is a finite, non-negative number of seconds. A busy JavaScript run normally raises DenoTimeoutError when the deadline fires, but this is best effort: blocking system calls, native code, and blocked permission paths can make a run exceed it.
• max_heap_bytes is an optional V8 old-generation constraint. Values below 8 MiB are rejected with ConfigurationError; the value does not cap native allocations, external memory, host memory, RSS, CPU, or child processes. It is not an OS/process isolation boundary.
• HTTP body limits apply to reqwest-returned, transport-decoded response-body bytes, not wire bytes; upstream decoding may allocate before the limit is checked. The explicit npm .tgz path has the same 1 GiB response-body cap. For a gzip response, the final four body bytes are checked as an ISIZE hint (the final member's size modulo 2^32); this threshold is not a decompressed- output budget and does not identify the first consumed member or total extraction. Fallback extraction has no hard output budget, so this is not a decompression or RSS cap.

Exceptions

The facade exports LibdenoError and these subclasses:

• EntryError — entry resolution failed.
• DenoPermissionError — invalid permission flags or denials carrying typed Rust permission provenance. JavaScript exception names/classes/causes are not trusted as denial evidence; a JS failure, including a denial whose typed provenance was lost, is reported as DenoRuntimeError.
• ConfigurationError — options cannot form a valid run, including empty permissions without an explicit opt-in, invalid deadlines, or an undersized heap value.
• DenoRuntimeError — runtime startup or JavaScript failure.
• DenoIOError — host filesystem/I/O failure.
• DenoTimeoutError — the runtime reported an execution deadline timeout.

Build and install a wheel

Use a virtual environment rather than installing build tools globally:

cd python
python -m venv .venv
. .venv/bin/activate
python -m pip install "maturin>=1.11,<2"
./build-wheel.sh
python -m pip install target/wheels/*.whl
cd ..
python -m unittest discover -s python/tests -p 'test_*.py'

The wheel uses the Python 3.9 stable ABI and targets Python 3.9+. The build script clears RUSTC_WRAPPER, resolves the active compiler dynamically, and uses Cargo's locked dependency resolution. The activation command above uses POSIX shell syntax; this build script requires Bash.

Run the stdlib test suite after installing the wheel from the repository root, so the source package does not shadow the installed package. Keep the same virtual environment activated so python refers to its interpreter.

Not supported yet

• Prompting and permission hooks.
• Output capture, async APIs, and subprocess execution.
• Python-facing permission/options objects beyond the keyword arguments above.
• Native addons.
• Source distributions (sdist); this prototype only defines a wheel build path.
• A stable public contract; this is a private alpha API and may change without notice.