Skip to content

docs: update safety docs for PyCapsule::import #6064

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Person-93 wants to merge 2 commits into
base: main
Choose a base branch
from
+3 −1
Open

docs: update safety docs for PyCapsule::import #6064

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6456928
update safety docs for `PyCapsule::import`
Person-93 May 22, 2026
564beb8
empty commit to trigger ci
Person-93 May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/types/capsule.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -385,7 +385,9 @@ impl PyCapsule {
///
/// # Safety
///
/// It must be known that the capsule imported by `name` contains an item of type `T`.
/// - It must be known that the capsule imported by `name` contains an item of type `T`.
/// - The contents of the capsule must not be mutated by any third-party code while the reference is alive.
/// The python interpreter does _NOT_ provide any synchronization guarantees for capsules.
pub unsafe fn import<'py, T>(py: Python<'py>, name: &CStr) -> PyResult<&'py T> {
Comment on lines +389 to 391
Copy link
Copy Markdown
Member

@davidhewitt davidhewitt May 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder, is it potentially worse than this? I imagine that if arbitrary Python code runs while the reference is alive, it can presumably free the capsule and leave the reference dangling.

There are presumably also alignment concerns, which the user cannot know.

Maybe there's enough spice here that it would be worth deprecating this and encouraging users to move over to #6066?

Copy link
Copy Markdown
Member

@davidhewitt davidhewitt May 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similarly we made the decision to remove .reference() in #5229 (comment)

Copy link
Copy Markdown
Contributor Author

@Person-93 Person-93 May 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe there's enough spice here that it would be worth deprecating this and encouraging users to move over to #6066?

I think that's a good idea. In the meantime, maybe we can check if the pointer is aligned and either panic or return an error if it isn't.

// SAFETY: `name` is a valid C string, thread is attached to the Python interpreter
let ptr = unsafe { ffi::PyCapsule_Import(name.as_ptr(), false as c_int) };
Expand Down
Loading