Issue #112: A binding is a generated file over the C library (nikaia bind python / js)

Open and answer this issue on GitHub.

targets, blocked · opened 2026-09-30 · updated 2026-10-08 · 1 comment

Record: ADR-131, all of it. nikaia bind python writes a ctypes binding from the ledger (exceptions per variant, str and bytes for buffers, classes with close() for handles, IntEnum, None, generators for streams, an awaitable for _async); nikaia bind js is the WebAssembly build’s .js. No second artifact, no native Node add-on: a Nikaia library does not ship twice.

Order (§5): the Python generator over the example library; the streamed and async forms; the js name; a test that imports the binding.

Comments

keywan-ghadami, 2026-10-08

nikaia bind python is built (0.0.684, 2a22b7c), against ADR-284 D26, D27 and D29.

nikaia bind python builds the library and writes target/nikaia/c-library/<package>/__init__.py, a ctypes module over lib<package>.so beside it. It is generated from the same reading of the package as the header, and carries the same ledger hash.

• Statuses become exceptions: Error with a subclass per thrown variant, and BoundaryError subclasses for the seven negative codes (ReentrantError, PanickedError, …). Each carries code and what last_error said.
• Text and bytes go in as str and bytes. Results come back with the size query done by the binding.
• A handle is a class: the extern constructor is __init__, plus its methods, a property per pub field, close(), a with block and __del__. A closed handle raises ArgumentError.
• An extern struct is a ctypes.Structure (nested ones in order), an enum an IntEnum, and null is None.
• A callback is any callable, kept alive for the call. What it raises is raised by the call once the call has returned, since ctypes cannot carry an exception through C.
• init() and shutdown().
• Only the entry points (D29).

Test: tests/c_library.rs: python_calls_the_library_through_its_binding runs a Python script over every kind of entry point in the test library. That includes a callback calling back into a held handle, which raises ReentrantError.

Still open:

• The _async form as an awaitable under a running loop, with cancel() as the ticket. Today a pausing function is called in its blocking form.
• A stream as a generator.
• nikaia bind js, which is the WebAssembly build’s .js (D22, D26) and waits on #111. That is why this issue stays blocked.
• nikaia bind node (D28).

---

Generated by Claude Code

Back to Open Issues