add `gil-refs` feature to aid migration

Cargo.toml

@@ -96,6 +96,9 @@ generate-import-lib = ["pyo3-ffi/generate-import-lib"]
 # Changes `Python::with_gil` to automatically initialize the Python interpreter if needed.
 auto-initialize = []
 
+# Allows use of the deprecated "GIL Refs" APIs.
+gil-refs = []
+
 # Optimizes PyObject to Vec conversion and so on.
 nightly = []
 

guide/src/features.md

@@ -57,6 +57,12 @@ This feature adds the `pyo3::inspect` module, as well as `IntoPy::type_output` a
 
 This is a first step towards adding first-class support for generating type annotations automatically in PyO3, however work is needed to finish this off. All feedback and offers of help welcome on [issue #2454](https://github.com/PyO3/pyo3/issues/2454).
 
+### `gil-refs`
+
+This feature is a backwards-compatibility feature to allow continued use of the "GIL Refs" APIs deprecated in PyO3 0.21. These APIs have performance drawbacks and soundness edge cases which the newer `Bound<T>` smart pointer and accompanying APIs resolve.
+
+This feature and the APIs it enables is expected to be removed in a future PyO3 version.
+
 ### `macros`
 
 This feature enables a dependency on the `pyo3-macros` crate, which provides the procedural macros portion of PyO3's API:

newsfragments/3707.added.md

@@ -0,0 +1 @@
+Add `gil-refs` feature to allow continued use of the deprecated GIL Refs APIs.

src/err/mod.rs

@@ -536,9 +536,12 @@ impl PyErr {
     }
 
     /// Deprecated form of `PyErr::write_unraisable_bound`.
-    #[deprecated(
-        since = "0.21.0",
-        note = "`PyErr::write_unraisable` will be replaced by `PyErr::write_unraisable_bound` in a future PyO3 version"
+    #[cfg_attr(
+        not(feature = "gil-refs"),
+        deprecated(
+            since = "0.21.0",
+            note = "`PyErr::write_unraisable` will be replaced by `PyErr::write_unraisable_bound` in a future PyO3 version"
+        )
     )]
     #[inline]
     pub fn write_unraisable(self, py: Python<'_>, obj: Option<&PyAny>) {

src/types/datetime.rs

@@ -164,9 +164,12 @@ pub trait PyTimeAccess {
 /// Trait for accessing the components of a struct containing a tzinfo.
 pub trait PyTzInfoAccess<'py> {
     /// Deprecated form of `get_tzinfo_bound`.
-    #[deprecated(
-        since = "0.21.0",
-        note = "`get_tzinfo` will be replaced by `get_tzinfo_bound` in a future PyO3 version"
+    #[cfg_attr(
+        not(feature = "gil-refs"),
+        deprecated(
+            since = "0.21.0",
+            note = "`get_tzinfo` will be replaced by `get_tzinfo_bound` in a future PyO3 version"
+        )
     )]
     fn get_tzinfo(&self) -> Option<&'py PyTzInfo> {
         self.get_tzinfo_bound().map(Bound::into_gil_ref)
@@ -734,7 +737,7 @@ mod tests {
 
     #[test]
     #[cfg_attr(target_arch = "wasm32", ignore)] // DateTime import fails on wasm for mysterious reasons
-    #[allow(deprecated)]
+    #[cfg_attr(not(feature = "gil-refs"), allow(deprecated))]
     fn test_get_tzinfo() {
         crate::Python::with_gil(|py| {
             let utc = timezone_utc(py);

src/types/pysuper.rs

@@ -17,9 +17,12 @@ pyobject_native_type_core!(
 
 impl PySuper {
     /// Deprecated form of `PySuper::new_bound`.
-    #[deprecated(
-        since = "0.21.0",
-        note = "`PySuper::new` will be replaced by `PySuper::new_bound` in a future PyO3 version"
+    #[cfg_attr(
+        not(feature = "gil-refs"),
+        deprecated(
+            since = "0.21.0",
+            note = "`PySuper::new` will be replaced by `PySuper::new_bound` in a future PyO3 version"
+        )
     )]
     pub fn new<'py>(ty: &'py PyType, obj: &'py PyAny) -> PyResult<&'py PySuper> {
         Self::new_bound(&ty.as_borrowed(), &obj.as_borrowed()).map(Bound::into_gil_ref)

tests/test_exceptions.rs

@@ -100,7 +100,7 @@ fn test_exception_nosegfault() {
 
 #[test]
 #[cfg(Py_3_8)]
-#[allow(deprecated)]
+#[cfg_attr(not(feature = "gil-refs"), allow(deprecated))]
 fn test_write_unraisable() {
     use common::UnraisableCapture;
     use pyo3::{exceptions::PyRuntimeError, ffi};

tests/test_super.rs

@@ -35,7 +35,7 @@ impl SubClass {
     }
 
     fn method_super_new(self_: &PyCell<Self>) -> PyResult<&PyAny> {
-        #[allow(deprecated)]
+        #[cfg_attr(not(feature = "gil-refs"), allow(deprecated))]
         let super_ = PySuper::new(self_.get_type(), self_)?;
         super_.call_method("method", (), None)
     }