deprecate the use of PyCell in favor of Bound and Py

guide/src/class.md

@@ -1230,6 +1230,7 @@ struct MyClass {
 
 impl pyo3::types::DerefToPyAny for MyClass {}
 
+# #[allow(deprecated)]
 unsafe impl pyo3::type_object::HasPyGilRef for MyClass {
     type AsRefTarget = pyo3::PyCell<Self>;
 }

guide/src/types.md

@@ -96,6 +96,7 @@ For a `&PyAny` object reference `any` where the underlying object is a `#[pyclas
 let obj: &PyAny = Py::new(py, MyClass {})?.into_ref(py);
 
 // To &PyCell<MyClass> with PyAny::downcast
+# #[allow(deprecated)]
 let _: &PyCell<MyClass> = obj.downcast()?;
 
 // To Py<PyAny> (aka PyObject) with .into()

pyo3-macros-backend/src/pyclass.rs

@@ -1281,6 +1281,7 @@ fn impl_pytypeinfo(
     };
 
     quote! {
+        #[allow(deprecated)]
         unsafe impl _pyo3::type_object::HasPyGilRef for #cls {
             type AsRefTarget = _pyo3::PyCell<Self>;
         }

src/conversion.rs

@@ -6,9 +6,9 @@ use crate::pyclass::boolean_struct::False;
 use crate::type_object::PyTypeInfo;
 use crate::types::any::PyAnyMethods;
 use crate::types::PyTuple;
-use crate::{
-    ffi, gil, Bound, Py, PyAny, PyCell, PyClass, PyNativeType, PyObject, PyRef, PyRefMut, Python,
-};
+#[allow(deprecated)]
+use crate::PyCell;
+use crate::{ffi, gil, Bound, Py, PyAny, PyClass, PyNativeType, PyObject, PyRef, PyRefMut, Python};
 use std::ptr::NonNull;
 
 /// Returns a borrowed pointer to a Python object.
@@ -265,6 +265,7 @@ where
     }
 }
 
+#[allow(deprecated)]
 impl<'py, T> FromPyObject<'py> for &'py PyCell<T>
 where
     T: PyClass,
@@ -279,6 +280,7 @@ where
     T: PyClass + Clone,
 {
     fn extract(obj: &PyAny) -> PyResult<Self> {
+        #[allow(deprecated)]
         let cell: &PyCell<Self> = obj.downcast()?;
         Ok(unsafe { cell.try_borrow_unguarded()?.clone() })
     }

src/conversions/std/array.rs

@@ -240,7 +240,7 @@ mod tests {
             let array: [Foo; 8] = [Foo, Foo, Foo, Foo, Foo, Foo, Foo, Foo];
             let pyobject = array.into_py(py);
             let list = pyobject.downcast_bound::<PyList>(py).unwrap();
-            let _cell: &crate::PyCell<Foo> = list.get_item(4).unwrap().extract().unwrap();
+            let _bound = list.get_item(4).unwrap().downcast::<Foo>().unwrap();
         });
     }
 

src/impl_/coroutine.rs

@@ -4,12 +4,14 @@ use std::{
     ops::{Deref, DerefMut},
 };
 
+#[allow(deprecated)]
+use crate::PyCell;
 use crate::{
     coroutine::{cancel::ThrowCallback, Coroutine},
     instance::Bound,
     pyclass::boolean_struct::False,
     types::PyString,
-    IntoPy, Py, PyAny, PyCell, PyClass, PyErr, PyObject, PyResult, Python,
+    IntoPy, Py, PyAny, PyClass, PyErr, PyObject, PyResult, Python,
 };
 
 pub fn new_coroutine<F, T, E>(
@@ -33,6 +35,7 @@ where
 
 fn get_ptr<T: PyClass>(obj: &Py<T>) -> *mut T {
     // SAFETY: Py<T> can be casted as *const PyCell<T>
+    #[allow(deprecated)]
     unsafe { &*(obj.as_ptr() as *const PyCell<T>) }.get_ptr()
 }
 

src/impl_/pyclass.rs

@@ -1,3 +1,5 @@
+#[allow(deprecated)]
+use crate::PyCell;
 use crate::{
     exceptions::{PyAttributeError, PyNotImplementedError, PyRuntimeError, PyValueError},
     ffi,
@@ -8,8 +10,8 @@ use crate::{
     pyclass_init::PyObjectInit,
     types::any::PyAnyMethods,
     types::PyBool,
-    Borrowed, Py, PyAny, PyCell, PyClass, PyErr, PyMethodDefType, PyNativeType, PyResult,
-    PyTypeInfo, Python,
+    Borrowed, Py, PyAny, PyClass, PyErr, PyMethodDefType, PyNativeType, PyResult, PyTypeInfo,
+    Python,
 };
 use std::{
     borrow::Cow,
@@ -26,12 +28,14 @@ pub use lazy_type_object::LazyTypeObject;
 /// Gets the offset of the dictionary from the start of the object in bytes.
 #[inline]
 pub fn dict_offset<T: PyClass>() -> ffi::Py_ssize_t {
+    #[allow(deprecated)]
     PyCell::<T>::dict_offset()
 }
 
 /// Gets the offset of the weakref list from the start of the object in bytes.
 #[inline]
 pub fn weaklist_offset<T: PyClass>() -> ffi::Py_ssize_t {
+    #[allow(deprecated)]
     PyCell::<T>::weaklist_offset()
 }
 
@@ -1105,6 +1109,7 @@ pub trait PyClassBaseType: Sized {
 ///
 /// In the future this will be extended to immutable PyClasses too.
 impl<T: PyClass> PyClassBaseType for T {
+    #[allow(deprecated)]
     type LayoutAsBase = crate::pycell::PyCell<T>;
     type BaseNativeType = T::BaseNativeType;
     type Initializer = crate::pyclass_init::PyClassInitializer<Self>;
@@ -1113,6 +1118,7 @@ impl<T: PyClass> PyClassBaseType for T {
 
 /// Implementation of tp_dealloc for pyclasses without gc
 pub(crate) unsafe extern "C" fn tp_dealloc<T: PyClass>(obj: *mut ffi::PyObject) {
+    #[allow(deprecated)]
     crate::impl_::trampoline::dealloc(obj, PyCell::<T>::tp_dealloc)
 }
 
@@ -1122,6 +1128,7 @@ pub(crate) unsafe extern "C" fn tp_dealloc_with_gc<T: PyClass>(obj: *mut ffi::Py
     {
         ffi::PyObject_GC_UnTrack(obj.cast());
     }
+    #[allow(deprecated)]
     crate::impl_::trampoline::dealloc(obj, PyCell::<T>::tp_dealloc)
 }
 

src/impl_/pymethods.rs

@@ -6,9 +6,11 @@ use crate::internal_tricks::extract_c_string;
 use crate::pycell::{PyBorrowError, PyBorrowMutError};
 use crate::pyclass::boolean_struct::False;
 use crate::types::{any::PyAnyMethods, PyModule, PyType};
+#[allow(deprecated)]
+use crate::PyCell;
 use crate::{
-    ffi, Borrowed, Bound, DowncastError, Py, PyAny, PyCell, PyClass, PyErr, PyObject, PyRef,
-    PyRefMut, PyResult, PyTraverseError, PyTypeCheck, PyVisit, Python,
+    ffi, Borrowed, Bound, DowncastError, Py, PyAny, PyClass, PyErr, PyObject, PyRef, PyRefMut,
+    PyResult, PyTraverseError, PyTypeCheck, PyVisit, Python,
 };
 use std::borrow::Cow;
 use std::ffi::CStr;
@@ -518,6 +520,7 @@ impl<'a> From<BoundRef<'a, 'a, PyModule>> for &'a PyModule {
     }
 }
 
+#[allow(deprecated)]
 impl<'a, 'py, T: PyClass> From<BoundRef<'a, 'py, T>> for &'a PyCell<T> {
     #[inline]
     fn from(bound: BoundRef<'a, 'py, T>) -> Self {

src/instance.rs

@@ -1,6 +1,8 @@
 use crate::err::{self, PyDowncastError, PyErr, PyResult};
 use crate::ffi_ptr_ext::FfiPtrExt;
-use crate::pycell::{PyBorrowError, PyBorrowMutError, PyCell};
+#[allow(deprecated)]
+use crate::pycell::PyCell;
+use crate::pycell::{PyBorrowError, PyBorrowMutError};
 use crate::pyclass::boolean_struct::{False, True};
 use crate::type_object::HasPyGilRef;
 use crate::types::{any::PyAnyMethods, string::PyStringMethods, typeobject::PyTypeMethods};
@@ -337,6 +339,7 @@ where
         unsafe { &*cell.get_ptr() }
     }
 
+    #[allow(deprecated)]
     pub(crate) fn get_cell(&'py self) -> &'py PyCell<T> {
         let cell = self.as_ptr().cast::<PyCell<T>>();
         // SAFETY: Bound<T> is known to contain an object which is laid out in memory as a
@@ -1190,6 +1193,7 @@ where
     {
         let any = self.as_ptr() as *const PyAny;
         // SAFETY: The class itself is frozen and `Sync` and we do not access anything but `cell.contents.value`.
+        #[allow(deprecated)]
         unsafe {
             let cell: &PyCell<T> = PyNativeType::unchecked_downcast(&*any);
             &*cell.get_ptr()
@@ -1706,6 +1710,7 @@ impl<T> std::convert::From<Bound<'_, T>> for Py<T> {
 }
 
 // `&PyCell<T>` can be converted to `Py<T>`
+#[allow(deprecated)]
 impl<T> std::convert::From<&PyCell<T>> for Py<T>
 where
     T: PyClass,
@@ -2222,8 +2227,6 @@ a = A()
 
     #[cfg(feature = "macros")]
     mod using_macros {
-        use crate::PyCell;
-
         use super::*;
 
         #[crate::pyclass(crate = "crate")]
@@ -2285,6 +2288,7 @@ a = A()
         #[test]
         #[allow(deprecated)]
         fn cell_tryfrom() {
+            use crate::PyCell;
             use crate::PyTryInto;
             // More detailed tests of the underlying semantics in pycell.rs
             Python::with_gil(|py| {

src/lib.rs

@@ -315,7 +315,9 @@ pub use crate::gil::GILPool;
 pub use crate::gil::{prepare_freethreaded_python, with_embedded_python_interpreter};
 pub use crate::instance::{Borrowed, Bound, Py, PyNativeType, PyObject};
 pub use crate::marker::Python;
-pub use crate::pycell::{PyCell, PyRef, PyRefMut};
+#[allow(deprecated)]
+pub use crate::pycell::PyCell;
+pub use crate::pycell::{PyRef, PyRefMut};
 pub use crate::pyclass::PyClass;
 pub use crate::pyclass_init::PyClassInitializer;
 pub use crate::type_object::{PyTypeCheck, PyTypeInfo};

src/prelude.rs

@@ -14,7 +14,9 @@ pub use crate::conversion::{PyTryFrom, PyTryInto};
 pub use crate::err::{PyErr, PyResult};
 pub use crate::instance::{Borrowed, Bound, Py, PyObject};
 pub use crate::marker::Python;
-pub use crate::pycell::{PyCell, PyRef, PyRefMut};
+#[allow(deprecated)]
+pub use crate::pycell::PyCell;
+pub use crate::pycell::{PyRef, PyRefMut};
 pub use crate::pyclass_init::PyClassInitializer;
 pub use crate::types::{PyAny, PyModule};
 pub use crate::PyNativeType;

src/pycell.rs

@@ -62,6 +62,7 @@
 //! ) -> *mut pyo3::ffi::PyObject {
 //!     use :: pyo3 as _pyo3;
 //!     _pyo3::impl_::trampoline::noargs(_slf, _args, |py, _slf| {
+//! #       #[allow(deprecated)]
 //!         let _cell = py
 //!             .from_borrowed_ptr::<_pyo3::PyAny>(_slf)
 //!             .downcast::<_pyo3::PyCell<Number>>()?;
@@ -153,6 +154,7 @@
 //! # pub struct Number {
 //! #     inner: u32,
 //! # }
+//! # #[allow(deprecated)]
 //! #[pyfunction]
 //! fn swap_numbers(a: &PyCell<Number>, b: &PyCell<Number>) {
 //!     // Check that the pointers are unequal
@@ -263,6 +265,7 @@ unsafe impl<T, U> PyLayout<T> for PyCellBase<U> where U: PySizedLayout<T> {}
 /// ```
 /// For more information on how, when and why (not) to use `PyCell` please see the
 /// [module-level documentation](self).
+#[deprecated(since = "0.21.0")]
 #[repr(C)]
 pub struct PyCell<T: PyClassImpl> {
     ob_base: <T::BaseType as PyClassBaseType>::LayoutAsBase,
@@ -278,10 +281,12 @@ pub(crate) struct PyCellContents<T: PyClassImpl> {
     pub(crate) weakref: T::WeakRef,
 }
 
+#[allow(deprecated)]
 unsafe impl<T: PyClass> PyNativeType for PyCell<T> {
     type AsRefSource = T;
 }
 
+#[allow(deprecated)]
 impl<T: PyClass> PyCell<T> {
     /// Makes a new `PyCell` on the Python heap and return the reference to it.
     ///
@@ -539,15 +544,19 @@ impl<T: PyClass> PyCell<T> {
     }
 }
 
+#[allow(deprecated)]
 impl<T: PyClassImpl> PyCell<T> {
     fn borrow_checker(&self) -> &<T::PyClassMutability as PyClassMutability>::Checker {
         T::PyClassMutability::borrow_checker(self)
     }
 }
 
+#[allow(deprecated)]
 unsafe impl<T: PyClassImpl> PyLayout<T> for PyCell<T> {}
+#[allow(deprecated)]
 impl<T: PyClass> PySizedLayout<T> for PyCell<T> {}
 
+#[allow(deprecated)]
 impl<T> PyTypeCheck for PyCell<T>
 where
     T: PyClass,
@@ -559,24 +568,28 @@ where
     }
 }
 
+#[allow(deprecated)]
 unsafe impl<T: PyClass> AsPyPointer for PyCell<T> {
     fn as_ptr(&self) -> *mut ffi::PyObject {
         (self as *const _) as *mut _
     }
 }
 
+#[allow(deprecated)]
 impl<T: PyClass> ToPyObject for &PyCell<T> {
     fn to_object(&self, py: Python<'_>) -> PyObject {
         unsafe { PyObject::from_borrowed_ptr(py, self.as_ptr()) }
     }
 }
 
+#[allow(deprecated)]
 impl<T: PyClass> AsRef<PyAny> for PyCell<T> {
     fn as_ref(&self) -> &PyAny {
         unsafe { self.py().from_borrowed_ptr(self.as_ptr()) }
     }
 }
 
+#[allow(deprecated)]
 impl<T: PyClass> Deref for PyCell<T> {
     type Target = PyAny;
 
@@ -585,6 +598,7 @@ impl<T: PyClass> Deref for PyCell<T> {
     }
 }
 
+#[allow(deprecated)]
 impl<T: PyClass + fmt::Debug> fmt::Debug for PyCell<T> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self.try_borrow() {
@@ -666,7 +680,10 @@ where
     U: PyClass,
 {
     fn as_ref(&self) -> &T::BaseType {
-        unsafe { &*self.inner.get_cell().ob_base.get_ptr() }
+        #[allow(deprecated)]
+        unsafe {
+            &*self.inner.get_cell().ob_base.get_ptr()
+        }
     }
 }
 
@@ -806,6 +823,7 @@ impl<T: PyClass> IntoPy<PyObject> for &'_ PyRef<'_, T> {
     }
 }
 
+#[allow(deprecated)]
 impl<'a, T: PyClass> std::convert::TryFrom<&'a PyCell<T>> for crate::PyRef<'a, T> {
     type Error = PyBorrowError;
     fn try_from(cell: &'a crate::PyCell<T>) -> Result<Self, Self::Error> {
@@ -847,7 +865,10 @@ where
     U: PyClass<Frozen = False>,
 {
     fn as_ref(&self) -> &T::BaseType {
-        unsafe { &*self.inner.get_cell().ob_base.get_ptr() }
+        #[allow(deprecated)]
+        unsafe {
+            &*self.inner.get_cell().ob_base.get_ptr()
+        }
     }
 }
 
@@ -857,7 +878,10 @@ where
     U: PyClass<Frozen = False>,
 {
     fn as_mut(&mut self) -> &mut T::BaseType {
-        unsafe { &mut *self.inner.get_cell().ob_base.get_ptr() }
+        #[allow(deprecated)]
+        unsafe {
+            &mut *self.inner.get_cell().ob_base.get_ptr()
+        }
     }
 }
 
@@ -960,6 +984,7 @@ unsafe impl<'a, T: PyClass<Frozen = False>> AsPyPointer for PyRefMut<'a, T> {
     }
 }
 
+#[allow(deprecated)]
 impl<'a, T: PyClass<Frozen = False>> std::convert::TryFrom<&'a PyCell<T>>
     for crate::PyRefMut<'a, T>
 {
@@ -1074,6 +1099,7 @@ where
     }
 }
 
+#[allow(deprecated)]
 impl<T: PyClassImpl> PyCellLayout<T> for PyCell<T>
 where
     <T::BaseType as PyClassBaseType>::LayoutAsBase: PyCellLayout<T::BaseType>,