Setu#

For AI sessions (and other readers in a hurry)#

llms.txt is the index to read first; doc/setu-guide.md is the guide to writing an extension: the rules, every parameter type, every class hook signature, every compile error Setu raises. A project using Setu keeps a copy of the guide at doc/setu-guide.md (zig build setu-guide-sync / setu-guide-check, see addSetuGuideSteps), so a session working on its bindings finds it inside the project. tool/check_guide.py keeps the guide in step with the source. A project's own docs site gets llms.txt and llms-full.txt for its Python API from tool/setu_doc.py.

An extension: one module declaration#

The extension's root file lists its Zig files once. Setu finds their lowercase pub fns (functions), setu.Classes, setu.Exceptions, UPPER_CASE constants and enums, creates them in its Py_mod_exec (classes bases first), adds __version__, runs init, and writes the .pyi from the same declaration:

const setu = @import("setu");

pub const module: setu.Module = .{
    .name = "point",
    .version = "1.0",
    .from = &.{
        .{ .ns = @import("point.zig"), .source = @embedFile("point.zig") },
        .{ .ns = @import("kernel.zig"), .prefixes = &.{"O_"} }, // constants only: no `source`
        .{ .ns = @import("enum.zig"), .enums = .int_enum }, // `enum.IntEnum` classes
    },
    .init = init, // after Setu's part
};

fn init(_: *setu.c.Object) setu.py.Error!void {}

comptime {
    setu.py.exportModule(module);
}

// build.zig: the .pyi, written by Setu's stub generator (built for the host, no libpython)
const pyi = @import("setu").addStubs(b, setu_dep, .{ .root_source_file = b.path("src/root.zig") });

_-named declarations, camelCase pub fns, plain structs and lowercase values are skipped; a name found twice is a compile error. src/scan.zig (top) has the rules, test/setu_class.zig an example of each filter (.only, .exclude, .prefixes, .functions = false).

Naming#

Setu's own code follows Zig style. In a file that Module.from, py.exportFns or setu.Class exports, a lowercase pub fn, snake_case included (prep_recv, get_label), is a Python function, method or property under that name; camelCase pub fns are Zig-only helpers. So snake_case function names there are on purpose, not a slip from Zig's camelCase rule: they are the Python names. Hooks keep their Python names too (__init__, __repr__).

Wheels: tool/setu_build.py#

A PEP 517 build backend (no setuptools) that builds a Zig + Setu extension's wheels with zig build. A backend must sit in the project's own tree, so each project keeps a byte-identical copy in its tool/, never edited there: what differs per project goes in [tool.setu_build] in its pyproject.toml (the keys are listed in the script's docstring). Setu tests the script itself: tool/check.py builds the glibc and musl wheels of test/wheel/ and pip-installs them on every interpreter (tool/check_wheel.py).

A project keeps its copy in step with the Setu it pins with two zig build steps, from its build.zig (setu must be in its build.zig.zon):

const setu_dep = b.dependency("setu", .{});
@import("setu").addSetuBuildSteps(b, setu_dep);

zig build setu-build-sync copies the pinned Setu's tool/setu_build.py into tool/ (run it after bumping Setu); zig build setu-build-check fails if the copy differs (run it in the project's checks).

Docs site: tool/setu_doc.py#

A static HTML site built by Setu's own builder, Python's standard library only: the API pages from the imported module's docstrings (the /// docs; typed signatures from the .pyi), grouped by a [tool.setu_doc] table in the project's pyproject.toml (the keys are in the script's docstring), the project's Markdown pages, the constants, its example scripts, llms.txt / llms-full.txt, and a runner for the >>> examples (setu_doc.py check; project fixtures in a hooks file). Everything the pages do (search, Run, the theme menu, Copy, the source views) is Zig compiled to WebAssembly (tool/setu_doc_web.zig); setu_doc.py serve serves the site on 127.0.0.1 with Run buttons that run an example and show its session (only on examples that can run: none that read a name nothing defines; the published site has no Run buttons). A Markdown table after a <!-- chart --> line becomes a colored bar chart (GitHub shows the table). The project keeps a byte-identical copy of setu_doc.py in tool/, like setu_build.py, in step with addSetuDocSteps (zig build setu-doc-sync / setu-doc-check), which also adds zig build doc-web (the Wasm module, from the pinned Setu; setu_doc.py runs it). A Zig project with no Python module gets the same site from its Markdown pages (no module, a name; a static folder such as Zig's autodoc output copied in). test/doc/ is a working model, test/doc_md/ a module-less one (tool/check_doc.py). The workflow runs zig build develop (the extension and its stub), then python tool/setu_doc.py (writes site/), and uploads site/ to GitHub Pages.

Releases#

Versions are <year>.<month>.<day>[-<n>], no zero padding: 2026.10.20 for a day's first release, then 2026.10.20-2, 2026.10.20-3, ... Tags are v<version> (the build.zig.zon version). Each tag's notes say whether tool/setu_build.py changed since the previous tag: if it did, projects run zig build setu-build-sync after bumping to it. git diff --quiet <previous tag> <tag> -- tool/setu_build.py tells (exit 1: changed).