|
| 1 | +--- |
| 2 | +name: rustpython-capi-expansion |
| 3 | +description: 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. |
| 4 | +--- |
| 5 | + |
| 6 | +# RustPython C-API Expansion |
| 7 | + |
| 8 | +Use this workflow for adding missing C-API functions to RustPython. |
| 9 | + |
| 10 | +## Source of truth for target files |
| 11 | + |
| 12 | +- Use this mapping source: `pyo3-ffi/src/*.rs`, which mirrors the CPython header split used by the C API. |
| 13 | +- Map requested header APIs to `crates/capi/src/<header_basename>.rs` using that split. Examples: |
| 14 | + - `setobject.h` -> `crates/capi/src/setobject.rs` |
| 15 | + - `dictobject.h` -> `crates/capi/src/dictobject.rs` |
| 16 | + - `unicodeobject.h` -> `crates/capi/src/unicodeobject.rs` |
| 17 | +- Do not invent alternate target modules when the header split implies a direct target. |
| 18 | +- If the target file is not present yet, create it and wire it in `crates/capi/src/lib.rs`. |
| 19 | + |
| 20 | +## Implementation workflow |
| 21 | + |
| 22 | +1. Identify requested missing APIs from the user request and their originating C API header. |
| 23 | +2. Open nearby capi modules in `crates/capi/src/` and follow existing style and patterns. |
| 24 | +3. Implement only the requested functions in the mapped target file. |
| 25 | +4. Keep behavior aligned with CPython C-API contracts. |
| 26 | +5. Prefer using existing `rustpython-vm` functionality as much as possible instead of re-implementing behavior in capi. |
| 27 | +6. If a needed `rustpython-vm` helper exists but is private, make it public with a minimal, focused visibility change. |
| 28 | +7. Prefer direct contract assumptions over defensive null checks unless required by the established local style. |
| 29 | +8. Add basic tests only; do not overfit with very specific edge-case clutter. |
| 30 | +9. In tests, use `pyo3` only as a safe wrapper over the API. Avoid raw pointer-heavy direct FFI-style tests. |
| 31 | +10. Run tests from `crates/capi`. |
| 32 | + |
| 33 | +## Testing rules |
| 34 | + |
| 35 | +- Run test commands with working directory set to `crates/capi`. |
| 36 | +- Prefer targeted tests first (module/function filter), then broader capi tests if needed. |
| 37 | +- Keep test names concise (no required `test_` prefix). |
| 38 | + |
| 39 | +## Style rules |
| 40 | + |
| 41 | +- Follow existing RustPython capi coding style in neighboring files. |
| 42 | +- Reuse `rustpython-vm` methods and types first; avoid duplicating VM logic in capi wrappers. |
| 43 | +- When exposing previously private VM helpers, keep the API surface minimal and avoid unrelated refactors. |
| 44 | +- Only expose and implement ABI-stable C-API surface needed for `abi3` / `abi3t`. |
| 45 | +- Add comments only when they explain non-obvious behavior. |
| 46 | +- Keep edits minimal and focused on requested API expansion. |
| 47 | + |
| 48 | +## Completion checklist |
| 49 | + |
| 50 | +- [ ] All requested functions implemented in mapped target file. |
| 51 | +- [ ] New module exported in `crates/capi/src/lib.rs` when applicable. |
| 52 | +- [ ] Basic safe-wrapper `pyo3` tests added/updated. |
| 53 | +- [ ] Tests executed from `crates/capi` and passing for changed area. |
| 54 | +- [ ] Final response includes changed file paths and test command summary. |
| 55 | + |
| 56 | +## Example prompts this skill should handle |
| 57 | + |
| 58 | +- "Implement these missing functions from `dictobject.h`." |
| 59 | +- "Add `setobject.h` C-API functions in RustPython and include basic tests." |
| 60 | +- "Port the listed `unicodeobject.h` APIs in capi, follow existing style, and run tests from `crates/capi`." |
0 commit comments