Skip to content

Add the ctypes Python binding over the core C ABI - #1

Draft
suleman-uzair wants to merge 3 commits into
mainfrom
feat/python-ctypes-runtime
Draft

suleman-uzair wants to merge 3 commits into
mainfrom
feat/python-ctypes-runtime

Conversation

@suleman-uzair

@suleman-uzair suleman-uzair commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

This PR adds the ukiryu Python binding as pure ctypes over the core's C ABI (ukiryu_abi_version, ukiryu_json, ukiryu_free). Each operation is one JSON wire request; all behaviour stays in the Rust core.

Refs ukiryu/ukiryu#25 (part of ukiryu/ukiryu#29). Packaging, wheels and installed-wheel tests are a separate change.

Core pin

The ukiryu-rs submodule is pinned to e6c4100bc3011104099720b6d672e09000dbc975, the head of ukiryu/ukiryu-rs#82 (the lint and yaml wire operations and the R2 rule files, stacked on #66 wire ABI), not a released crate. It will be re-pinned to the merge commit once those merge.

Changes

  • _ffi.py: loads the library from UKIRYU_CDYLIB, then the packaged ukiryu/lib/, then the system loader. An explicit or present candidate that fails is an error, never a silent fallback; LibraryLoadError lists every candidate and the reason. Replies are copied and released with ukiryu_free exactly once; the ABI version must be 1.
  • api.py / models.py: Register, Tool (resolve, build, execute, exit_code_meaning), Shell, and the validate / schema / version functions, returning frozen dataclasses. Unknown or missing reply fields raise ProtocolError. execute requires env and timeout; failures raise UkiryuError with the source class, message and the run's result.
  • values.py: exact wire values: integers of any size, Floats (Ruby Float#to_s text), Symbol, Time (seconds, nanos, UTC offset), Regexp, ordered Map, and bytes.
  • tests/: value codec, loader order and ownership, typed API, real execute runs, and the conformance corpus through the public API (manifest digests checked, 14139 rows across 17 ops pinned; resolve.shell_detect and cli.run are declared with counts and reasons). lint_string, safe_load, load_model and model_to_yaml run the lint and yaml rows.
  • ci.yml: builds the pinned core on Ubuntu, macOS and Windows with Python 3.9 and 3.13, runs the tests, and uploads engine provenance (submodule commit, Cargo.lock and library digests, core version). No publish step.

Known failures

Three schema rows (profiles-ghostscript-10-0, profiles-inkscape-1-0, synthetic.invalid-yaml) differ in the YAML parser error message. The core's own corpus test in #66 fails on the same rows while it waits on an upstream patch release; they are not skipped here. Run 43896213256 shows these 3 rows as the only failures (13921 of 13924 rows match; every other test passes) before the lint and yaml rows were added.

The 27 lint and yaml rows that root ruling R2 covers are judged by the core's own rule files (migrated.json, projection.json, emitter.json in ukiryu-rs/ukiryu/tests/conformance, from ukiryu/ukiryu-rs#49) with the same rules as the core: traced migrated expectations with frozen error detail, the Lutaml declared-field projection, and pinned Yeptris bytes plus canonical equality. A separate test checks those rules are traced, pinned and cover exactly these 27 rows. UkiryuError gains detail for the structured facts the core attaches. The rule files' schema and shell detection migrations are not applied here, so the three schema rows above still compare with their frozen expectations.

The ukiryu package loads the ukiryu-ffi library with ctypes (UKIRYU_CDYLIB,
then the packaged library, then the system loader, with every rejected
candidate reported) and sends one JSON wire request per operation. Typed
dataclasses cover tool resolve, build and execute, type, definition and
profile validation, version extraction and ranges, exit-code meanings and
shell formatting. Symbols, exact times, regexps, ordered maps, Floats and
integers of any size cross without loss.

The core is pinned as the ukiryu-rs submodule at the wire ABI commit
4827c94. CI builds that library on Linux, macOS and Windows and runs the
tests, including the shared conformance corpus through the public API
with pinned per-operation row counts, and records engine provenance.
suleman-uzair added 2 commits November 16, 2026 20:59
Add lint_string, safe_load, load_model and model_to_yaml over the core's
new lint and yaml wire operations, dispatch the lint.string, yaml.load,
yaml.model_load and yaml.lutaml_roundtrip rows (215), and raise the
dispatched total to 14139.

The core submodule moves to f820559, the head of ukiryu/ukiryu-rs#82,
which adds those operations on top of #66.
The corpus test reads migrated.json, projection.json and emitter.json
from the core checkout and judges the 27 lint and yaml rows they list
by the same rules as the core: traced migrated expectations with
frozen error detail, the Lutaml declared-field projection, and pinned
Yeptris bytes plus canonical equality for the emitter rows. A new test
checks the rules are traced, pinned and cover exactly those rows.

UkiryuError gains detail, the structured facts the core attaches to
some failures (category and stage for YAML reader errors).

Pin ukiryu-rs to e6c4100 (#82), which adds the rule files and the
safe_load error detail.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant