Rustpython Capi Expansion
Developmentrustpython-capi-expansionRustpython Capi Expansion is an Agent Skill for development published in the RustPython/RustPython repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Implement missing RustPython C-API functions in crates/capi using the pyo3-ffi header split mapping (`pyo3-ffi/src/*.rs`, mirroring CPython C API headers). Use this whenever the user asks to add or port C-API functions (for example from setobject.h, dictobject.h, unicodeobject.h) or add capi tests.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/RustPython/RustPython/blob/HEAD/.agents/skills/rustpython-capi-expansion/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rustpython-capi-expansion, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
RustPython C-API Expansion
Use this workflow for adding missing C-API functions to RustPython.
Source of truth for target files
- Use this mapping source:
pyo3-ffi/src/*.rs, which mirrors the CPython header split used by the C API. - Map requested header APIs to
crates/capi/src/<header_basename>.rsusing that split. Examples:setobject.h->crates/capi/src/setobject.rsdictobject.h->crates/capi/src/dictobject.rsunicodeobject.h->crates/capi/src/unicodeobject.rs
- Do not invent alternate target modules when the header split implies a direct target.
- If the target file is not present yet, create it and wire it in
crates/capi/src/lib.rs.
Implementation workflow
- Identify requested missing APIs from the user request and their originating C API header.
- Open nearby capi modules in
crates/capi/src/and follow existing style and patterns. - Implement only the requested functions in the mapped target file.
- Keep behavior aligned with CPython C-API contracts.
- Prefer using existing
rustpython-vmfunctionality as much as possible instead of re-implementing behavior in capi. - If a needed
rustpython-vmhelper exists but is private, make it public with a minimal, focused visibility change. - Prefer direct contract assumptions over defensive null checks unless required by the established local style.
- Add basic tests only; do not overfit with very specific edge-case clutter.
- In tests, use
pyo3only as a safe wrapper over the API. Avoid raw pointer-heavy direct FFI-style tests. - Run tests from
crates/capi.
Testing rules
- Run test commands with working directory set to
crates/capi. - Prefer targeted tests first (module/function filter), then broader capi tests if needed.
- Keep test names concise (no required
test_prefix).
Style rules
- Follow existing RustPython capi coding style in neighboring files.
- Reuse
rustpython-vmmethods and types first; avoid duplicating VM logic in capi wrappers. - When exposing previously private VM helpers, keep the API surface minimal and avoid unrelated refactors.
- Only expose and implement ABI-stable C-API surface needed for
abi3/abi3t. - Add comments only when they explain non-obvious behavior.
- Keep edits minimal and focused on requested API expansion.
Completion checklist
- All requested functions implemented in mapped target file.
- New module exported in
crates/capi/src/lib.rswhen applicable. - Basic safe-wrapper
pyo3tests added/updated. - Tests executed from
crates/capiand passing for changed area. - Final response includes changed file paths and test command summary.
Example prompts this skill should handle
- "Implement these missing functions from
dictobject.h." - "Add
setobject.hC-API functions in RustPython and include basic tests." - "Port the listed
unicodeobject.hAPIs in capi, follow existing style, and run tests fromcrates/capi."