deprecate get_refcnt (#3357) (#5797)

* deprecate get_refcnt (#3357)

* add private _get_refcnt

* add changelog entry

* remove allow(deprecated) tags

Author: luxedo

guide/src/class.md

@@ -969,8 +969,8 @@ fn increment_then_print_field(my_class: &Bound<'_, MyClass>) {
 // When the Python object smart pointer needs to be stored elsewhere prefer `Py<T>` over `Bound<'py, T>`
 // to avoid the lifetime restrictions.
 #[pyfunction]
-fn print_refcnt(my_class: Py<MyClass>, py: Python<'_>) {
-    println!("{}", my_class.get_refcnt(py));
+fn print_is_none(my_class: Py<MyClass>, py: Python<'_>) {
+    println!("{}", my_class.is_none(py));
 }
 ```
 

guide/src/migration.md

@@ -2525,7 +2525,7 @@ py.None().get_refcnt();
 
 After:
 
-```rust
+```rust,ignore
 # pyo3::Python::attach(|py| {
 py.None().get_refcnt(py);
 # })

newsfragments/5797.changed.md

@@ -0,0 +1,2 @@
+Deprecate `Py<T>::get_refcnt` and `PyAnyMethods::get_refcnt` in favor of `pyo3::ffi::Py_REFCNT(obj.as_ptr())`
+

src/ffi/tests.rs

@@ -1,7 +1,9 @@
 use crate::ffi::*;
-use crate::types::any::PyAnyMethods;
 use crate::Python;
 
+#[cfg(not(Py_LIMITED_API))]
+use crate::types::any::PyAnyMethods;
+
 #[cfg(all(not(Py_LIMITED_API), any(not(any(PyPy, GraalPy)), feature = "macros")))]
 use crate::types::PyString;
 
@@ -304,16 +306,16 @@ fn test_inc_dec_ref() {
     Python::attach(|py| {
         let obj = py.eval(c"object()", None, None).unwrap();
 
-        let ref_count = obj.get_refcnt();
+        let ref_count = obj._get_refcnt();
         let ptr = obj.as_ptr();
 
         unsafe { Py_INCREF(ptr) };
 
-        assert_eq!(obj.get_refcnt(), ref_count + 1);
+        assert_eq!(obj._get_refcnt(), ref_count + 1);
 
         unsafe { Py_DECREF(ptr) };
 
-        assert_eq!(obj.get_refcnt(), ref_count);
+        assert_eq!(obj._get_refcnt(), ref_count);
     })
 }
 
@@ -323,15 +325,15 @@ fn test_inc_dec_ref_immortal() {
     Python::attach(|py| {
         let obj = py.None();
 
-        let ref_count = obj.get_refcnt(py);
+        let ref_count = obj._get_refcnt(py);
         let ptr = obj.as_ptr();
 
         unsafe { Py_INCREF(ptr) };
 
-        assert_eq!(obj.get_refcnt(py), ref_count);
+        assert_eq!(obj._get_refcnt(py), ref_count);
 
         unsafe { Py_DECREF(ptr) };
 
-        assert_eq!(obj.get_refcnt(py), ref_count);
+        assert_eq!(obj._get_refcnt(py), ref_count);
     })
 }

src/instance.rs

@@ -1728,7 +1728,16 @@ impl<T> Py<T> {
 
     /// Gets the reference count of the `ffi::PyObject` pointer.
     #[inline]
-    pub fn get_refcnt(&self, _py: Python<'_>) -> isize {
+    #[deprecated(
+        since = "0.29.0",
+        note = "use `pyo3::ffi::Py_REFCNT(obj.as_ptr())` instead"
+    )]
+    pub fn get_refcnt(&self, py: Python<'_>) -> isize {
+        self._get_refcnt(py)
+    }
+
+    #[inline]
+    pub(crate) fn _get_refcnt(&self, _py: Python<'_>) -> isize {
         // SAFETY: Self is a valid pointer to a PyObject
         unsafe { ffi::Py_REFCNT(self.0.as_ptr()) }
     }
@@ -2542,17 +2551,17 @@ mod tests {
         });
 
         Python::attach(move |py| {
-            assert_eq!(dict.get_refcnt(py), 1);
+            assert_eq!(dict._get_refcnt(py), 1);
         });
     }
 
     #[test]
     fn pyobject_from_py() {
         Python::attach(|py| {
             let dict: Py<PyDict> = PyDict::new(py).unbind();
-            let cnt = dict.get_refcnt(py);
+            let cnt = dict._get_refcnt(py);
             let p: Py<PyAny> = dict.into();
-            assert_eq!(p.get_refcnt(py), cnt);
+            assert_eq!(p._get_refcnt(py), cnt);
         });
     }
 
@@ -2786,11 +2795,11 @@ a = A()
             let object2 = object.clone_ref(py);
 
             assert_eq!(object.as_ptr(), object2.as_ptr());
-            assert_eq!(object.get_refcnt(py), 2);
+            assert_eq!(object._get_refcnt(py), 2);
 
             object.drop_ref(py);
 
-            assert_eq!(object2.get_refcnt(py), 1);
+            assert_eq!(object2._get_refcnt(py), 1);
 
             object2.drop_ref(py);
         });

src/internal/state.rs

@@ -362,7 +362,7 @@ fn decrement_attach_count() {
 mod tests {
     use super::*;
 
-    use crate::{types::PyAnyMethods, Py, PyAny, Python};
+    use crate::{Py, PyAny, Python};
 
     fn get_object(py: Python<'_>) -> Py<PyAny> {
         py.eval(c"object()", None, None).unwrap().unbind()
@@ -396,14 +396,14 @@ mod tests {
             // Create a reference to drop while attached.
             let reference = obj.clone_ref(py);
 
-            assert_eq!(obj.get_refcnt(py), 2);
+            assert_eq!(obj._get_refcnt(py), 2);
             #[cfg(not(pyo3_disable_reference_pool))]
             assert!(pool_dec_refs_does_not_contain(&obj));
 
             // While attached, reference count will be decreased immediately.
             drop(reference);
 
-            assert_eq!(obj.get_refcnt(py), 1);
+            assert_eq!(obj._get_refcnt(py), 1);
             #[cfg(not(any(pyo3_disable_reference_pool)))]
             assert!(pool_dec_refs_does_not_contain(&obj));
         });
@@ -417,15 +417,15 @@ mod tests {
             // Create a reference to drop while detached.
             let reference = obj.clone_ref(py);
 
-            assert_eq!(obj.get_refcnt(py), 2);
+            assert_eq!(obj._get_refcnt(py), 2);
             assert!(pool_dec_refs_does_not_contain(&obj));
 
             // Drop reference in a separate (detached) thread.
             std::thread::spawn(move || drop(reference)).join().unwrap();
 
             // The reference count should not have changed, it is remembered
             // to release later.
-            assert_eq!(obj.get_refcnt(py), 2);
+            assert_eq!(obj._get_refcnt(py), 2);
             #[cfg(not(Py_GIL_DISABLED))]
             assert!(pool_dec_refs_contains(&obj));
             obj
@@ -438,7 +438,7 @@ mod tests {
             // DECREFs after releasing the lock on the POOL, so the
             // refcnt could still be 2 when this assert happens
             #[cfg(not(Py_GIL_DISABLED))]
-            assert_eq!(obj.get_refcnt(py), 1);
+            assert_eq!(obj._get_refcnt(py), 1);
             assert!(pool_dec_refs_does_not_contain(&obj));
         });
     }
@@ -501,7 +501,7 @@ mod tests {
         Python::attach(|py| {
             // Make a simple object with 1 reference
             let obj = get_object(py);
-            assert_eq!(obj.get_refcnt(py), 1);
+            assert_eq!(obj._get_refcnt(py), 1);
             // Cloning the object when detached should panic
             py.detach(|| obj.clone());
         });
@@ -511,7 +511,7 @@ mod tests {
     fn recursive_attach_ok() {
         Python::attach(|py| {
             let obj = Python::attach(|_| py.eval(c"object()", None, None).unwrap());
-            assert_eq!(obj.get_refcnt(), 1);
+            assert_eq!(obj._get_refcnt(), 1);
         })
     }
 
@@ -520,12 +520,12 @@ mod tests {
     fn test_clone_attached() {
         Python::attach(|py| {
             let obj = get_object(py);
-            let count = obj.get_refcnt(py);
+            let count = obj._get_refcnt(py);
 
             // Cloning when attached should increase reference count immediately
             #[expect(clippy::redundant_clone)]
             let c = obj.clone();
-            assert_eq!(count + 1, c.get_refcnt(py));
+            assert_eq!(count + 1, c._get_refcnt(py));
         })
     }
 

src/types/any.rs

@@ -881,6 +881,10 @@ pub trait PyAnyMethods<'py>: crate::sealed::Sealed {
         T: FromPyObject<'a, 'py>;
 
     /// Returns the reference count for the Python object.
+    #[deprecated(
+        since = "0.29.0",
+        note = "use `pyo3::ffi::Py_REFCNT(obj.as_ptr())` instead"
+    )]
     fn get_refcnt(&self) -> isize;
 
     /// Computes the "repr" representation of self.
@@ -1531,7 +1535,7 @@ impl<'py> PyAnyMethods<'py> for Bound<'py, PyAny> {
     }
 
     fn get_refcnt(&self) -> isize {
-        unsafe { ffi::Py_REFCNT(self.as_ptr()) }
+        self._get_refcnt()
     }
 
     fn repr(&self) -> PyResult<Bound<'py, PyString>> {
@@ -1652,6 +1656,11 @@ impl<'py> Bound<'py, PyAny> {
             Ok(Some(attr))
         }
     }
+
+    #[inline]
+    pub(crate) fn _get_refcnt(&self) -> isize {
+        unsafe { ffi::Py_REFCNT(self.as_ptr()) }
+    }
 }
 
 #[cfg(test)]

src/types/dict.rs

@@ -1022,11 +1022,11 @@ mod tests {
             let cnt;
             let obj = py.eval(c"object()", None, None).unwrap();
             {
-                cnt = obj.get_refcnt();
+                cnt = obj._get_refcnt();
                 let _dict = [(10, &obj)].into_py_dict(py);
             }
             {
-                assert_eq!(cnt, obj.get_refcnt());
+                assert_eq!(cnt, obj._get_refcnt());
             }
         });
     }

src/types/iterator.rs

@@ -191,7 +191,7 @@ mod tests {
     fn iter_refcnt() {
         let (obj, count) = Python::attach(|py| {
             let obj = vec![10, 20].into_pyobject(py).unwrap();
-            let count = obj.get_refcnt();
+            let count = obj._get_refcnt();
             (obj.unbind(), count)
         });
 
@@ -206,7 +206,7 @@ mod tests {
         });
 
         Python::attach(move |py| {
-            assert_eq!(count, obj.get_refcnt(py));
+            assert_eq!(count, obj._get_refcnt(py));
         });
     }
 
@@ -219,7 +219,7 @@ mod tests {
                 let list = PyList::empty(py);
                 list.append(10).unwrap();
                 list.append(&obj).unwrap();
-                count = obj.get_refcnt();
+                count = obj._get_refcnt();
                 list
             };
 
@@ -230,7 +230,7 @@ mod tests {
                 assert!(it.next().unwrap().is(&obj));
                 assert!(it.next().is_none());
             }
-            assert_eq!(count, obj.get_refcnt());
+            assert_eq!(count, obj._get_refcnt());
         });
     }
 

src/types/list.rs

@@ -1011,11 +1011,11 @@ mod tests {
                 let v = vec![2];
                 let ob = v.into_pyobject(py).unwrap();
                 let list = ob.cast::<PyList>().unwrap();
-                cnt = obj.get_refcnt();
+                cnt = obj._get_refcnt();
                 list.set_item(0, &obj).unwrap();
             }
 
-            assert_eq!(cnt, obj.get_refcnt());
+            assert_eq!(cnt, obj._get_refcnt());
         });
     }
 
@@ -1043,11 +1043,11 @@ mod tests {
             let obj = py.eval(c"object()", None, None).unwrap();
             {
                 let list = PyList::empty(py);
-                cnt = obj.get_refcnt();
+                cnt = obj._get_refcnt();
                 list.insert(0, &obj).unwrap();
             }
 
-            assert_eq!(cnt, obj.get_refcnt());
+            assert_eq!(cnt, obj._get_refcnt());
         });
     }
 
@@ -1068,10 +1068,10 @@ mod tests {
             let obj = py.eval(c"object()", None, None).unwrap();
             {
                 let list = PyList::empty(py);
-                cnt = obj.get_refcnt();
+                cnt = obj._get_refcnt();
                 list.append(&obj).unwrap();
             }
-            assert_eq!(cnt, obj.get_refcnt());
+            assert_eq!(cnt, obj._get_refcnt());
         });
     }