add Python::try_attach

newsfragments/5342.added.md

@@ -0,0 +1 @@
+Add `Python::try_attach`.

pytests/src/misc.rs

@@ -24,7 +24,7 @@ fn hammer_gil_in_thread() -> LockHolder {
         // now the interpreter has shut down, so hammer the GIL. In buggy
         // versions of PyO3 this will cause a crash.
         loop {
-            Python::attach(|_py| ());
+            Python::try_attach(|_py| ());
         }
     });
     LockHolder { sender }

src/internal/state.rs

@@ -62,7 +62,6 @@ impl AttachGuard {
     }
 
     /// Variant of the above which will will return `None` if the interpreter cannot be attached to.
-    #[cfg(any(not(Py_LIMITED_API), Py_3_11, test))] // see Python::try_attach
     pub(crate) fn try_acquire() -> Option<Self> {
         match ATTACH_COUNT.try_with(|c| c.get()) {
             Ok(i) if i > 0 => {

src/marker.rs

@@ -393,6 +393,9 @@ impl Python<'_> {
     /// - If the [`auto-initialize`] feature is not enabled and the Python interpreter is not
     ///   initialized.
     ///
+    /// To avoid possible initialization or panics if calling in a context where the Python
+    /// interpreter might be unavailable, consider using [`Python::try_attach`].
+    ///
     /// # Examples
     ///
     /// ```
@@ -419,15 +422,20 @@ impl Python<'_> {
         f(guard.python())
     }
 
-    /// Variant of [`Python::attach`] which will do no work if the interpreter is in a
-    /// state where it cannot be attached to:
+    /// Variant of [`Python::attach`] which will return without attaching to the Python
+    /// interpreter if the interpreter is in a state where it cannot be attached to:
     /// - in the middle of GC traversal
     /// - not initialized
+    ///
+    /// Note that due to the nature of the underlying Python APIs used to implement this,
+    /// the behavior is currently provided on a best-effort basis; it is expected that a
+    /// future CPython version will introduce APIs which guarantee this behaviour. This
+    /// function is still recommended for use in the meanwhile as it provides the best
+    /// possible behaviour and should transparently change to an optimal implementation
+    /// once such APIs are available.
     #[inline]
     #[track_caller]
-    #[cfg(any(not(Py_LIMITED_API), Py_3_11, test))] // only used in buffer.rs for now, allow in test cfg for simplicity
-                                                    // TODO: make this API public?
-    pub(crate) fn try_attach<F, R>(f: F) -> Option<R>
+    pub fn try_attach<F, R>(f: F) -> Option<R>
     where
         F: for<'py> FnOnce(Python<'py>) -> R,
     {