add gil-refs feature to allow backwards-compatible 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:

src/types/tuple.rs

@@ -60,9 +60,12 @@ pyobject_native_type_core!(PyTuple, pyobject_native_static_type_object!(ffi::PyT
 impl PyTuple {
     /// Deprecated form of `PyTuple::new_bound`.
     #[track_caller]
-    #[deprecated(
-        since = "0.21.0",
-        note = "`PyTuple::new` will be replaced by `PyTuple::new_bound` in a future PyO3 version"
+    #[cfg_attr(
+        not(feature = "gil-refs"),
+        deprecated(
+            since = "0.21.0",
+            note = "`PyTuple::new` will be replaced by `PyTuple::new_bound` in a future PyO3 version"
+        )
     )]
     pub fn new<T, U>(
         py: Python<'_>,
@@ -115,9 +118,12 @@ impl PyTuple {
     }
 
     /// Deprecated form of `PyTuple::empty_bound`.
-    #[deprecated(
-        since = "0.21.0",
-        note = "`PyTuple::empty` will be replaced by `PyTuple::empty_bound` in a future PyO3 version"
+    #[cfg_attr(
+        not(feature = "gil-refs"),
+        deprecated(
+            since = "0.21.0",
+            note = "`PyTuple::empty` will be replaced by `PyTuple::empty_bound` in a future PyO3 version"
+        )
     )]
     pub fn empty(py: Python<'_>) -> &PyTuple {
         Self::empty_bound(py).into_gil_ref()
@@ -803,7 +809,7 @@ tuple_conversion!(
 );
 
 #[cfg(test)]
-#[allow(deprecated)] // TODO: remove allow when GIL Pool is removed
+#[cfg_attr(not(feature = "gil-refs"), allow(deprecated))]
 mod tests {
     use crate::types::{any::PyAnyMethods, tuple::PyTupleMethods, PyAny, PyList, PyTuple};
     use crate::{Python, ToPyObject};