deprecate PyObject type alias (#5325)

* deprecate `PyObject` type alias

* fix typo

Co-authored-by: Lily Acorn <code@lilyf.org>

---------

Co-authored-by: Lily Acorn <code@lilyf.org>

Author: Icxolu

guide/src/async-await.md

@@ -13,7 +13,7 @@ use pyo3::prelude::*;
 
 #[pyfunction]
 #[pyo3(signature=(seconds, result=None))]
-async fn sleep(seconds: f64, result: Option<PyObject>) -> Option<PyObject> {
+async fn sleep(seconds: f64, result: Option<Py<PyAny>>) -> Option<Py<PyAny>> {
     let (tx, rx) = oneshot::channel();
     thread::spawn(move || {
         thread::sleep(Duration::from_secs_f64(seconds));

guide/src/class.md

@@ -413,7 +413,7 @@ impl SubSubClass {
     }
 
     #[staticmethod]
-    fn factory_method(py: Python<'_>, val: usize) -> PyResult<PyObject> {
+    fn factory_method(py: Python<'_>, val: usize) -> PyResult<Py<PyAny>> {
         let base = PyClassInitializer::from(BaseClass::new());
         let sub = base.add_subclass(SubClass { val2: val });
         if val % 2 == 0 {
@@ -748,7 +748,7 @@ To create a constructor which takes a positional class argument, you can combine
 # use pyo3::prelude::*;
 # use pyo3::types::PyType;
 # #[pyclass]
-# struct BaseClass(PyObject);
+# struct BaseClass(Py<PyAny>);
 #
 #[pymethods]
 impl BaseClass {

guide/src/class/protocols.md

@@ -59,7 +59,7 @@ given signatures should be interpreted as follows:
     #[pymethods]
     impl NotHashable {
         #[classattr]
-        const __hash__: Option<PyObject> = None;
+        const __hash__: Option<Py<PyAny>> = None;
     }
     ```
     </details>
@@ -162,15 +162,15 @@ use std::sync::Mutex;
 
 #[pyclass]
 struct MyIterator {
-    iter: Mutex<Box<dyn Iterator<Item = PyObject> + Send>>,
+    iter: Mutex<Box<dyn Iterator<Item = Py<PyAny>> + Send>>,
 }
 
 #[pymethods]
 impl MyIterator {
     fn __iter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> {
         slf
     }
-    fn __next__(slf: PyRefMut<'_, Self>) -> Option<PyObject> {
+    fn __next__(slf: PyRefMut<'_, Self>) -> Option<Py<PyAny>> {
         slf.iter.lock().unwrap().next()
     }
 }
@@ -283,7 +283,7 @@ Use the `#[pyclass(sequence)]` annotation to instruct PyO3 to fill the `sq_lengt
     #[pymethods]
     impl NoContains {
         #[classattr]
-        const __contains__: Option<PyObject> = None;
+        const __contains__: Option<Py<PyAny>> = None;
     }
     ```
     </details>
@@ -439,7 +439,7 @@ use pyo3::gc::PyVisit;
 
 #[pyclass]
 struct ClassWithGCSupport {
-    obj: Option<PyObject>,
+    obj: Option<Py<PyAny>>,
 }
 
 #[pymethods]

guide/src/conversions/tables.md

@@ -1,6 +1,6 @@
 ## Mapping of Rust types to Python types
 
-When writing functions callable from Python (such as a `#[pyfunction]` or in a `#[pymethods]` block), the trait `FromPyObject` is required for function arguments, and `IntoPy<PyObject>` is required for function return values.
+When writing functions callable from Python (such as a `#[pyfunction]` or in a `#[pymethods]` block), the trait `FromPyObject` is required for function arguments, and `IntoPyObject` is required for function return values.
 
 Consult the tables in the following section to find the Rust types provided by PyO3 which implement these traits.
 
@@ -54,7 +54,6 @@ It is also worth remembering the following special types:
 | `Python<'py>`    | A GIL token, used to pass to PyO3 constructors to prove ownership of the GIL. |
 | `Bound<'py, T>`  | A Python object connected to the GIL lifetime. This provides access to most of PyO3's APIs. |
 | `Py<T>`          | A Python object isolated from the GIL lifetime. This can be sent to other threads. |
-| `PyObject`       | An alias for `Py<PyAny>`              |
 | `PyRef<T>`       | A `#[pyclass]` borrowed immutably.    |
 | `PyRefMut<T>`    | A `#[pyclass]` borrowed mutably.      |
 

guide/src/conversions/traits.md

@@ -580,7 +580,7 @@ forward the implementation to the inner type.
 
 // newtype tuple structs are implicitly `transparent`
 #[derive(IntoPyObject)]
-struct TransparentTuple(PyObject);
+struct TransparentTuple(Py<PyAny>);
 
 #[derive(IntoPyObject)]
 #[pyo3(transparent)]
@@ -599,7 +599,7 @@ For `enum`s each variant is converted according to the rules for `struct`s above
 
 #[derive(IntoPyObject)]
 enum Enum<'a, 'py, K: Hash + Eq, V> { // enums are supported and convert using the same
-    TransparentTuple(PyObject),       // rules on the variants as the structs above
+    TransparentTuple(Py<PyAny>),       // rules on the variants as the structs above
     #[pyo3(transparent)]
     TransparentStruct { inner: Bound<'py, PyAny> },
     Tuple(&'a str, HashMap<K, V>),
@@ -645,7 +645,7 @@ demonstrated below.
 ```rust,no_run
 # use pyo3::prelude::*;
 # #[allow(dead_code)]
-struct MyPyObjectWrapper(PyObject);
+struct MyPyObjectWrapper(Py<PyAny>);
 
 impl<'py> IntoPyObject<'py> for MyPyObjectWrapper {
     type Target = PyAny; // the Python type
@@ -741,7 +741,6 @@ In the example above we used `BoundObject::into_any` and `BoundObject::unbind` t
 [`FromPyObject`]: {{#PYO3_DOCS_URL}}/pyo3/conversion/trait.FromPyObject.html
 [`IntoPyObject`]: {{#PYO3_DOCS_URL}}/pyo3/conversion/trait.IntoPyObject.html
 [`IntoPyObjectExt`]: {{#PYO3_DOCS_URL}}/pyo3/conversion/trait.IntoPyObjectExt.html
-[`PyObject`]: {{#PYO3_DOCS_URL}}/pyo3/type.PyObject.html
 
 [`PyRef`]: {{#PYO3_DOCS_URL}}/pyo3/pycell/struct.PyRef.html
 [`PyRefMut`]: {{#PYO3_DOCS_URL}}/pyo3/pycell/struct.PyRefMut.html

guide/src/function/signature.md

@@ -82,7 +82,7 @@ Arguments of type `Python` must not be part of the signature:
 # use pyo3::prelude::*;
 #[pyfunction]
 #[pyo3(signature = (lambda))]
-pub fn simple_python_bound_function(py: Python<'_>, lambda: PyObject) -> PyResult<()> {
+pub fn simple_python_bound_function(py: Python<'_>, lambda: Py<PyAny>) -> PyResult<()> {
     Ok(())
 }
 ```

guide/src/migration.md

@@ -16,6 +16,14 @@ For this reason we chose to rename these to more modern terminology introduced i
 - `pyo3::prepare_freethreaded_python` is now called `Python::initialize`.
 </details>
 
+### Deprecation of `PyObject` type alias
+<details open>
+<summary><small>Click to expand</small></summary>
+
+The type alias `PyObject` (aka `Py<PyAny>`) is often confused with the identically named FFI definition `pyo3::ffi::PyObject`. For this reason we are deprecating its usage. To migrate simply replace its usage by the target type `Py<PyAny>`.
+
+</details>
+
 ### Deprecation of `GILProtected`
 <details open>
 <summary><small>Click to expand</small></summary>
@@ -186,6 +194,7 @@ impl ToPyObject for MyPyObjectWrapper {
 
 After:
 ```rust,no_run
+# #![allow(deprecated)]
 # use pyo3::prelude::*;
 # #[allow(dead_code)]
 # struct MyPyObjectWrapper(PyObject);

guide/src/python-from-rust/function-calls.md

@@ -12,9 +12,9 @@ Both of these APIs take `args` and `kwargs` arguments (for positional and keywor
 * [`call1`]({{#PYO3_DOCS_URL}}/pyo3/types/trait.PyAnyMethods.html#tymethod.call1) and [`call_method1`]({{#PYO3_DOCS_URL}}/pyo3/types/trait.PyAnyMethods.html#tymethod.call_method1) to call only with positional `args`.
 * [`call0`]({{#PYO3_DOCS_URL}}/pyo3/types/trait.PyAnyMethods.html#tymethod.call0) and [`call_method0`]({{#PYO3_DOCS_URL}}/pyo3/types/trait.PyAnyMethods.html#tymethod.call_method0) to call with no arguments.
 
-For convenience the [`Py<T>`](../types.md#pyt-and-pyobject) smart pointer also exposes these same six API methods, but needs a `Python` token as an additional first argument to prove the GIL is held.
+For convenience the [`Py<T>`](../types.md#pyt) smart pointer also exposes these same six API methods, but needs a `Python` token as an additional first argument to prove the GIL is held.
 
-The example below calls a Python function behind a `PyObject` (aka `Py<PyAny>`) reference:
+The example below calls a Python function behind a `Py<PyAny>` reference:
 
 ```rust
 use pyo3::prelude::*;

guide/src/python-typing-hints.md

@@ -230,7 +230,7 @@ impl MyClass {
     pub fn __class_getitem__(
         cls: &Bound<'_, PyType>,
         key: &Bound<'_, PyAny>,
-    ) -> PyResult<PyObject> {
+    ) -> PyResult<Py<PyAny>> {
         /* implementation details */
     }
 }

guide/src/trait-bounds.md

@@ -44,7 +44,7 @@ How could we expose this solver to Python thanks to PyO3 ?
 ## Implementation of the trait bounds for the Python class
 
 If a Python class implements the same three methods as the `Model` trait, it seems logical it could be adapted to use the solver.
-However, it is not possible to pass a `PyObject` to it as it does not implement the Rust trait (even if the Python model has the required methods).
+However, it is not possible to pass a `Py<PyAny>` to it as it does not implement the Rust trait (even if the Python model has the required methods).
 
 In order to implement the trait, we must write a wrapper around the calls in Rust to the Python model.
 The method signatures must be the same as the trait, keeping in mind that the Rust trait cannot be changed for the purpose of making the code available in Python.