Claude Cursor Skill

pyo3-bindings

PyO3 conventions for exposing a Rust core to Python: pyclass/pymethods, PyErr/PyResult error mapping, GIL release, properties, maturin builds, and pytest. Load when generating or reviewing PyO3 Python bindings for a Rust library.

LLM Mart · 0 points · 0 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download goldziher-ai-rulez-internal_builtins_bindings_pyo3_skills_pyo3-bindings-ca967ad.zip · 0 KB

goldziher/ai-rulez 162 16 forks MIT Updated 5h ago

Part of goldziher/ai-rulez — 151 skills

Install

skills CLI npx skills add https://github.com/Goldziher/ai-rulez/tree/main/internal/builtins/bindings/pyo3/skills/pyo3-bindings

Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install goldziher-ai-rulez@llmmart

Git git clone https://github.com/Goldziher/ai-rulez.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole goldziher/ai-rulez collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Use #[pyclass] and #[pymethods] for Python-visible types. Use #[new] for constructors.
Map Rust Result<T, E> to Python exceptions via PyErr. Use PyResult<T> as return type.
Use pyo3::types for conversions. Prefer &str over String in parameters, return String.
Prefer Bound<'py, T> over Py<T> for ergonomic, lifetime-checked references (PyO3 0.22+).
Release the GIL with py.allow_threads() for CPU-intensive Rust code. Never hold GIL during I/O.
Use #[getter] and #[setter] for properties. Implement __repr__ and __str__ for debugging.
Build with maturin develop for local testing, maturin build --release for distribution.
Test bindings from Python using pytest. Test both success and error paths.
Keep Python wrappers thin — business logic lives in Rust, Python provides ergonomic API.
Anti-patterns: .unwrap() in pyclass methods, blocking GIL for long operations, leaking Python objects.

Files (ai-rulez)

SKILL.md 1.2 KB

---
name: pyo3-bindings
description: "PyO3 conventions for exposing a Rust core to Python: pyclass/pymethods, PyErr/PyResult error mapping, GIL release, properties, maturin builds, and pytest. Load when generating or reviewing PyO3 Python bindings for a Rust library."
---

- Use `#[pyclass]` and `#[pymethods]` for Python-visible types. Use `#[new]` for constructors.
- Map Rust `Result<T, E>` to Python exceptions via `PyErr`. Use `PyResult<T>` as return type.
- Use `pyo3::types` for conversions. Prefer `&str` over `String` in parameters, return `String`.
- Prefer `Bound<'py, T>` over `Py<T>` for ergonomic, lifetime-checked references (PyO3 0.22+).
- Release the GIL with `py.allow_threads()` for CPU-intensive Rust code. Never hold GIL during I/O.
- Use `#[getter]` and `#[setter]` for properties. Implement `__repr__` and `__str__` for debugging.
- Build with `maturin develop` for local testing, `maturin build --release` for distribution.
- Test bindings from Python using `pytest`. Test both success and error paths.
- Keep Python wrappers thin — business logic lives in Rust, Python provides ergonomic API.
- Anti-patterns: `.unwrap()` in pyclass methods, blocking GIL for long operations, leaking Python objects.