Python

A Python module is imported like a header: a .py file, or a package’s directory (one with an __init__.py). Nothing in the Python is written for Volt, and the Volt code has no interpreter handles or object juggling: bolt asks Python what the module exports, typed by its annotations, and writes Volt that calls it through Python’s C API. Python starts the first time it’s called.

use std::io;
use { "geom.py" } as geom;

fn main() -> void {
    var p = geom::Point::new(3.0, 4.0);          // a class (a dataclass here): Point(3.0, 4.0)
    p.scale(2.0);                                 // a method
    p.set_y(1.5);                                 // an attribute: y() and set_y(v)
    std::println("{} {}", p.x(), geom::upper("quiet"));             // 6 QUIET
    std::println("{} {}", geom::add(40), geom::greet("volt", true)); // defaults, keyword-only arguments
    val xs: i64[3] = { 5, 7, 9 };
    std::println("{}", geom::find(xs[..], 9) ?? -1);                 // int | None is i64?: 2
}

An exception stops the program with its type and message, as a Volt panic does (Python declares none to make an error of). What the table doesn’t cover — a dict of lists, a tuple of classes, a callable taking a class — is left out, listed in a comment of the generated declarations (VOLT_SHOW_IMPORT=1 voltc check main.volt prints them). Calls hold the GIL, so any thread can make them. bolt runs python3 (or $PYTHON) to read the module and python3-config (or $PYTHON_CONFIG) for Python.h and the library; it needs Python 3.12 or later.

The interop/python package (in the repository) embeds the Python interpreter for calls made by hand. Depend on it and call Python with Volt values; its build file asks python3-config (or $PYTHON_CONFIG) for the headers and the library, and bolt passes them to your program.

[dependencies]
python = { path = "../volt/interop/python" }

use std::io;

fn run() -> python::python_error!void {
    val math = try python::import("math");
    val root = try (try math.call_method("sqrt", 2.0)).to_f64();
    std::println("{:.4}", root);                                   // 1.4142

    try python::exec("def greet(who):\n    return 'hi ' + who\n");
    val greet = try python::eval("greet");
    std::println("{}", try (try greet.call("volt")).to_string());  // hi volt

    val bad = python::eval("1 / 0");
    if (bad.err) {
        std::println("{}", bad.err);   // EXCEPTION(ZeroDivisionError: division by zero)
    }
}

fn main() -> !void {
    var py = python::start();          // Python stops when py is deleted
    try run();
}

A python::object holds one reference: copying it adds one and deleting it drops it. Every call that can fail returns python_error!T, and a Python exception becomes python_error::EXCEPTION("Type: message").

The thread that called start() holds Python’s lock (the GIL). Another thread takes it with python::gil(), which holds it until it’s deleted, while the first lets go of it inside py.without_gil(f):

var total: std::thread::atomic_i64 = {};
py.without_gil(|total&| () {
    var t = std::thread::spawn(|total&| () {
        val g = python::gil();
        val r = python::eval("sum(range(101))") catch return;
        total.store(r.to_i64() catch 0);
    }) catch return;
    t.join();
});

A Volt library that lists python among its bindings gets a Python module from bolt build (target/debug/bindings/NAME.py): one file over ctypes, with no C to compile. pyi adds its type stubs.

The examples here use greet, the library every client in examples/interop/calls-volt calls: export fn add(a: i64, b: i64) -> i64, export fn hello(name: str) -> std::string, and an export struct tally with tally_new, tally_add and tally_name. What export means, and what crosses as what, is in They call Volt.

# bolt.toml of the Volt library
[lib]
kind = ["shared"]
bindings = ["python", "pyi"]

import greet                        # bindings/greet.py

print("add", greet.add(2, 3))       # add 5
print(greet.hello("volt"))          # hello, volt: owned text comes back as a str
with greet.tally("clicks") as c:    # an export struct is a class; with (or close()) frees it
    c.add(1)
    print(c.name(), c.add(2))       # clicks 3

bolt build writes the library to target/debug/libgreet.so (libgreet.dylib on macOS, greet.dll on Windows) and the module to target/debug/bindings/greet.py, which finds the library one directory up, so point Python at the module:

bolt build
PYTHONPATH=target/debug/bindings python3 main.py

The module loads the library from $VOLT_NAME_LIB (the package’s name in capitals), else libNAME.so (libNAME.dylib, NAME.dll) from next to itself or the directory above. An error set becomes an exception class deriving from the module’s Error, raised with the error’s name (its code and name say which, and the class has the codes: for error math_error { NEGATIVE }, greet.math_error.NEGATIVE). Structs are ctypes structures made from their fields (greet.vec2(1, 2)), and what Volt changes in one it takes by reference comes back; an enum is a class of its values; slices are lists, optionals are the value or None, and a callback is any callable. A number by reference (n: i32*, x: f64&) takes a ctypes number, ctypes.c_int32(7), whose value gets what Volt writes (None is a null i32*). The module takes every shape: owned text and objects go in (an object given to Volt is Python’s no longer; a closed or lent one is refused with ValueError before anything is given, and so is closing or giving away one that a call that hasn’t returned holds, as its callback might), a Volt trait is a class to subclass (any object with its fns passes), a callback can take and give text and objects and raise an error set’s class for E!T (any other exception comes out of the call once Volt returns), a closure Volt gives back is a callable (close() or a with block frees it, else the garbage collector), and a std::vec comes back as a list.

A Python project can install a Volt library with pip install, which runs bolt: see pip install and npm install.