Introspection: properly set OUTPUT_TYPE on IntoPyObject implementations for Bound and Borrow and add a PyTypeCheck to them

We need the PyTypeCheck bound to get the type hint for the underlying type

Author: Tpt

guide/src/type-stub.md

@@ -79,7 +79,5 @@ This is useful when PyO3 is not able to derive proper type annotations by itself
 - Introspection only works with Python modules declared with an inline Rust module.
   Modules declared using a function are not supported.
 - `FromPyObject::INPUT_TYPE` and `IntoPyObject::OUTPUT_TYPE` must be implemented for PyO3 to get the proper input/output type annotations to use.
-- Because `FromPyObject::INPUT_TYPE` and `IntoPyObject::OUTPUT_TYPE` are `const` it is not possible to build yet smart generic annotations for containers like `concat!("list[", T::OUTPUT_TYPE, "]")`.
-  See [this tracking issue](https://github.com/rust-lang/rust/issues/76560).
 - PyO3 is not able to introspect the content of `#[pymodule]` and `#[pymodule_init]` functions.
   If they are present, the module is tagged as incomplete using a fake `def __getattr__(name: str) -> Incomplete: ...` function [following best practices](https://typing.python.org/en/latest/guides/writing_stubs.html#incomplete-stubs).

newsfragments/5640.changed.md

@@ -0,0 +1 @@
+IntoPyObject implementation on Bound, Borrowed and Py: add a PyTypeCheck bound to emit typing information

pytests/stubs/pyfunctions.pyi

@@ -1,6 +1,4 @@
-from typing import Any
-
-def args_kwargs(*args, **kwargs) -> tuple[Any, Any | None]: ...
+def args_kwargs(*args, **kwargs) -> tuple[tuple, dict | None]: ...
 def many_keyword_arguments(
     *,
     ant: object | None = None,
@@ -21,19 +19,19 @@ def many_keyword_arguments(
     penguin: object | None = None,
 ) -> None: ...
 def none() -> None: ...
-def positional_only(a: object, /, b: object) -> tuple[Any, Any]: ...
+def positional_only(a: object, /, b: object) -> tuple[object, object]: ...
 def simple(
     a: object, b: object | None = None, *, c: object | None = None
-) -> tuple[Any, Any | None, Any | None]: ...
+) -> tuple[object, object | None, object | None]: ...
 def simple_args(
     a: object, b: object | None = None, *args, c: object | None = None
-) -> tuple[Any, Any | None, Any, Any | None]: ...
+) -> tuple[object, object | None, tuple, object | None]: ...
 def simple_args_kwargs(
     a: object, b: object | None = None, *args, c: object | None = None, **kwargs
-) -> tuple[Any, Any | None, Any, Any | None, Any | None]: ...
+) -> tuple[object, object | None, tuple, object | None, dict | None]: ...
 def simple_kwargs(
     a: object, b: object | None = None, c: object | None = None, **kwargs
-) -> tuple[Any, Any | None, Any | None, Any | None]: ...
+) -> tuple[object, object | None, object | None, dict | None]: ...
 def with_custom_type_annotations(
     a: int, *_args: str, _b: int | None = None, **_kwargs: bool
 ) -> int: ...

src/conversion.rs

@@ -9,7 +9,8 @@ use crate::pyclass::boolean_struct::False;
 use crate::pyclass::{PyClassGuardError, PyClassGuardMutError};
 use crate::types::PyTuple;
 use crate::{
-    Borrowed, Bound, BoundObject, Py, PyAny, PyClass, PyClassGuard, PyErr, PyRef, PyRefMut, Python,
+    Borrowed, Bound, BoundObject, Py, PyAny, PyClass, PyClassGuard, PyErr, PyRef, PyRefMut,
+    PyTypeCheck, Python,
 };
 use std::convert::Infallible;
 use std::marker::PhantomData;
@@ -123,61 +124,79 @@ pub(crate) mod private {
     }
 }
 
-impl<'py, T> IntoPyObject<'py> for Bound<'py, T> {
+impl<'py, T: PyTypeCheck> IntoPyObject<'py> for Bound<'py, T> {
     type Target = T;
     type Output = Bound<'py, Self::Target>;
     type Error = Infallible;
 
+    #[cfg(feature = "experimental-inspect")]
+    const OUTPUT_TYPE: TypeHint = T::TYPE_HINT;
+
     fn into_pyobject(self, _py: Python<'py>) -> Result<Self::Output, Self::Error> {
         Ok(self)
     }
 }
 
-impl<'a, 'py, T> IntoPyObject<'py> for &'a Bound<'py, T> {
+impl<'a, 'py, T: PyTypeCheck> IntoPyObject<'py> for &'a Bound<'py, T> {
     type Target = T;
     type Output = Borrowed<'a, 'py, Self::Target>;
     type Error = Infallible;
 
+    #[cfg(feature = "experimental-inspect")]
+    const OUTPUT_TYPE: TypeHint = T::TYPE_HINT;
+
     fn into_pyobject(self, _py: Python<'py>) -> Result<Self::Output, Self::Error> {
         Ok(self.as_borrowed())
     }
 }
 
-impl<'a, 'py, T> IntoPyObject<'py> for Borrowed<'a, 'py, T> {
+impl<'a, 'py, T: PyTypeCheck> IntoPyObject<'py> for Borrowed<'a, 'py, T> {
     type Target = T;
     type Output = Borrowed<'a, 'py, Self::Target>;
     type Error = Infallible;
 
+    #[cfg(feature = "experimental-inspect")]
+    const OUTPUT_TYPE: TypeHint = T::TYPE_HINT;
+
     fn into_pyobject(self, _py: Python<'py>) -> Result<Self::Output, Self::Error> {
         Ok(self)
     }
 }
 
-impl<'a, 'py, T> IntoPyObject<'py> for &Borrowed<'a, 'py, T> {
+impl<'a, 'py, T: PyTypeCheck> IntoPyObject<'py> for &Borrowed<'a, 'py, T> {
     type Target = T;
     type Output = Borrowed<'a, 'py, Self::Target>;
     type Error = Infallible;
 
+    #[cfg(feature = "experimental-inspect")]
+    const OUTPUT_TYPE: TypeHint = T::TYPE_HINT;
+
     fn into_pyobject(self, _py: Python<'py>) -> Result<Self::Output, Self::Error> {
         Ok(*self)
     }
 }
 
-impl<'py, T> IntoPyObject<'py> for Py<T> {
+impl<'py, T: PyTypeCheck> IntoPyObject<'py> for Py<T> {
     type Target = T;
     type Output = Bound<'py, Self::Target>;
     type Error = Infallible;
 
+    #[cfg(feature = "experimental-inspect")]
+    const OUTPUT_TYPE: TypeHint = T::TYPE_HINT;
+
     fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
         Ok(self.into_bound(py))
     }
 }
 
-impl<'a, 'py, T> IntoPyObject<'py> for &'a Py<T> {
+impl<'a, 'py, T: PyTypeCheck> IntoPyObject<'py> for &'a Py<T> {
     type Target = T;
     type Output = Borrowed<'a, 'py, Self::Target>;
     type Error = Infallible;
 
+    #[cfg(feature = "experimental-inspect")]
+    const OUTPUT_TYPE: TypeHint = T::TYPE_HINT;
+
     fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
         Ok(self.bind_borrowed(py))
     }

src/impl_/pyclass.rs

@@ -11,7 +11,7 @@ use crate::{
     pycell::PyBorrowError,
     types::{any::PyAnyMethods, PyBool},
     Borrowed, IntoPyObject, IntoPyObjectExt, Py, PyAny, PyClass, PyClassGuard, PyErr, PyResult,
-    PyTypeInfo, Python,
+    PyTypeCheck, PyTypeInfo, Python,
 };
 use std::{
     ffi::CStr,
@@ -1204,7 +1204,7 @@ impl<
 
 impl<
         ClassT: PyClass,
-        U,
+        U: PyTypeCheck,
         const OFFSET: usize,
         const IMPLEMENTS_INTOPYOBJECT_REF: bool,
         const IMPLEMENTS_INTOPYOBJECT: bool,