Add initial draft of Rust API design document by emmatyping · Pull Request #45 · Rust-for-CPython/cpython

emmatyping · 2026-08-19T00:33:17Z

Okay, it took a while to play with these API design ideas and get them to a state where I was happy with them. I have a rough prototype similar to #41 that is based on this, but I figured it would make more sense to discuss the API design and make sure I haven't missed things or there isn't unsoundness in this design. It turns out it is just darn difficult to get thread-state passing right when you consider re-entrancy and multi-threading.

As mentioned in the document, my overall priorities in this design were:

be sound on GIL and free-threaded builds;
support every PEP 11 platform;
approach equivalent C performance where safety permits;
feel familiar to PyO3 and C API users; and
use modern APIs such as PyModExport.

I think 3 is probably the furthest from achievable with this current design, we query the TLS quite frequently with this design, but I believe a lot of those queries could be cleaned up. 4 is really a matter of taste, but I tried to be somewhat similar while also trying to have as small an API surface as possible.

Things left undone in this design that we will need to figure out:

Subinterpreter support (I expect this will best be discussed at the core sprints in October, but if anyone has thoughts, please chime in!)
Optimizing/handling Drop properly, including if one occurs while detached.
A buffer protocol wrapper (cc @ngoldbaum, I know you have Thoughts about this :) )
probably things I'm forgetting!

I also wasn't totally sure where to put this, perhaps it would go better in InternalDocs?

AI disclosure: I worked with GPT 5.6 Sol when iterating on this API and the content is a mix of writing me and the LLM. I've reviewed every word, but please let me know if there is anything unclear!

emmatyping · 2026-08-19T05:28:32Z

+
+- **Subinterpreters.** Future support requires an interpreter-identity model
+  for contexts, owning handles, module state, and process-global Rust values.
+- **Buffer protocol.** No safe `PyBuffer` API is included until the design


For a safe buffer protocol, I'm thinking for now we could ensure the buffer is uniquely held, and copy it if it isn't? There are usability and performance implications of that however.

emmatyping · 2026-08-19T05:32:46Z

+  Rust slices from racing with Python mutation or escaping across detach and
+  reentrant calls. Copying from an exact immutable bytes object is the safe
+  interim input path.
+- **Interpreter-aware locking.** The design must either provide a lock which


For this I am thinking it would make the most sense to either use PyMutex and wrap that, or write a lock which cooperates with the interpreter like the PyOnceLock in PyO3.

ngoldbaum

Did a read-through and had a few comments questions and suggestions

ngoldbaum · 2026-08-24T18:23:29Z

+pub type PyResult<T> = Result<T, PyErrRaised>;
+```
+
+`PyErrRaised` is `!Send` and `#[must_use]`. Built-in and custom exception types


Maybe worth an external link for must_use? I’d never seen it before this and had to look up the docs: https://doc.rust-lang.org/std/attribute.must_use.html

ngoldbaum · 2026-08-24T18:27:21Z

+
+Generic implementations compose. `Option<T>` maps `None`, borrowed handles can
+be promoted with an incref, and an existing `Bound<T>` can be returned without
+refcount traffic:


nit: churn instead of traffic?

ngoldbaum · 2026-08-24T18:30:10Z

+```
+
+Only generated `ModuleDef<S>` glue constructs `ModuleRef<S>` and proves the
+state type.


not quite sure what “proves the static type” means here

Probably a mis-edit on my part, I'll fix that!

ngoldbaum · 2026-08-24T18:33:19Z

+Generated modules declare `Py_mod_gil = Py_MOD_GIL_NOT_USED`, the internal
+exact-version ABI, the GIL/free-threaded build mode, and
+`Py_mod_multiple_interpreters = Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`.
+Stable-ABI and subinterpreter support are out of scope.


Is lack of subinterpreter support a problem for the PoC? Or would we degrade to a pure-python library instead of using a Rust accelerator under subinterpreters?

I expect it will be. There's been a lot of effort to have the stdlib support subinterpreters. I'm not sure if we would be able to degrade gracefully.

It would be useful to have some solution, but I'm okay punting until the core sprints.

ShaharNaveh · 2026-08-24T19:20:36Z

+pub struct ThreadContext<'py> {
+    ptr: NonNull<ffi::PyThreadState>,
+    detach: Option<DetachPermit<'py>>,
+    #[allow(clippy::type_complexity)]


It's better to use expect where possible and to provide a reason as well:

Suggested change

#[allow(clippy::type_complexity)]

#[expect(clippy::type_complexity, reason = "...")]

maybe it's a bit much for a documentation 🤷

ShaharNaveh · 2026-08-24T19:52:38Z

+```rust
+#[derive(PyClassGc)]
+struct Node {
+    parent: Option<Py<PyInstance<Node>>>,


Suggested change

parent: Option<Py<PyInstance<Node>>>,

parent: Option<Py<PyInstance<Self>>>,

Eclips4 · 2026-09-06T15:46:56Z

+`CallbackArgs` lends `'args`, while `with_current` supplies `'py`. Constructor
+tuple/dict parsing fills the same slots and shares conversion code.


Converting one argument can run Python code that removes another value from kwargs, if the parser only borrowed that value it could then access freed memory.

So, the constructor parser must take its own references to keyword values before converting any arguments, and keep them until the call and result conversion finish.

Filled a bug report for PyO3: PyO3/pyo3#6392
@davidhewitt FYI

Eclips4 · 2026-09-06T18:20:16Z

+
+This prevents safe code from combining an unrelated payload, module state, or
+definition. `#[derive(PyClassGc)]` uses the same sealed field rules as module
+state and disables GC slots when no field can own Python references. Manual


I suppose it could lead to memory leak.

Let's imagine next:

#[derive(PyClassGc)] struct Encoder { level: u32 } #[derive(ModuleStateGc)] struct ExampleState { encoder: Py<PyInstance<Encoder>> }

These objects form a cycle module -> state.encoder -> Python encoder instance -> Python encoder type -> module (again!).

Eclips4 · 2026-09-06T18:28:50Z

+`assume_set` is unsafe because a false marker would let a callback return an
+error sentinel without an exception; it therefore debug-checks the state. At
+the FFI boundary, `Err` requires a pending exception; otherwise the trampoline
+sets `SystemError`. `Ok` requires no pending exception; on mismatch the
+trampoline releases the result and returns its error sentinel. These checks
+also reject stale saved markers.


These checks confirm that an exception is pending, but cannot detect whether a later error replaced the original one. Returning an older PyErrRaised can therefore propagate a different exception.

Eclips4 · 2026-09-06T18:40:40Z

+| Module exec | Commit the appropriate failed state phase, set a fixed `SystemError`, and return `-1`. |
+| Module or instance clear | Finish the lifecycle transition, set `SystemError`, and return failure; CPython reports it as unraisable where required. |
+| Traverse | Never leave a Python exception pending. A panic is fatal because continuing with an incomplete reachability report can violate GC invariants. |
+| `tp_dealloc` and module free | Run mandatory non-panicking cleanup guards first, then report the panic as unraisable when an attached state is available. Abort if cleanup itself cannot be completed safely. |


Could we explicitly require preserving any pending Python exception during destruction? If Drop panics, reporting that panic as unraisable can overwrite and clear the error. We should save and clear the exception before cleanup, then restore it after cleanup and reporting, including when the original state was empty.

Eclips4 · 2026-09-06T18:49:48Z

+Rust structs in classes must be `Send + Sync + 'static`. Python methods receive only `&self`,
+never `&mut self`, because aliases can call the same object concurrently in a
+free-threaded interpreter. Mutable payload state therefore requires interior
+mutability. The rules for a blocking interpreter-aware lock remain an open
+decision listed in the appendix; an ordinary `Mutex` must not be presented as
+the general solution until those rules are settled.


It may be out of scope for now, but I think we need to define locking protocol for zlib. AFAIK streaming zlib holds its lock across detaching and reattaching, so another thread waiting on an ordinary Mutex while attached can deadlock with the GIL or free-threaded GC.

emmatyping requested review from Eclips4 and davidhewitt August 19, 2026 00:33

emmatyping commented Aug 19, 2026

View reviewed changes

emmatyping mentioned this pull request Aug 22, 2026

Initial sketch of a Rust API for CPython #41

Draft

Add initial draft of Rust API design document

4a6e800

emmatyping force-pushed the emmatyping/rust-api-design-doc branch from b334292 to 4a6e800 Compare August 24, 2026 18:37

ngoldbaum reviewed Aug 24, 2026

View reviewed changes

ShaharNaveh reviewed Aug 24, 2026

View reviewed changes

emmatyping mentioned this pull request Aug 30, 2026

RC PoC #2

Closed

Eclips4 reviewed Sep 6, 2026

View reviewed changes

	#[allow(clippy::type_complexity)]
	#[expect(clippy::type_complexity, reason = "...")]

	parent: Option<Py<PyInstance<Node>>>,
	parent: Option<Py<PyInstance<Self>>>,

		`CallbackArgs` lends `'args`, while `with_current` supplies `'py`. Constructor
		tuple/dict parsing fills the same slots and shares conversion code.

Uh oh!

Conversation

emmatyping commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ngoldbaum left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

emmatyping commented Aug 19, 2026 •

edited

Loading