Skip to content

Introspection: macro: introduce a PythonTypeHint struct #5648

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 29, 2025
+305 −223
Merged

Introspection: macro: introduce a PythonTypeHint struct #5648

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion pyo3-introspection/src/introspection.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,7 @@ fn convert_decorator(decorator: &ChunkTypeHint) -> Result<PythonIdentifier> {
if let TypeHintExpr::Identifier(i) = expr {
Ok(i)
} else {
bail!("PyO3 introspection currently only support decorators that are identifiers of a Python function")
bail!("PyO3 introspection currently only support decorators that are identifiers of a Python function, got {expr:?}")
}
}
}
Expand Down
53 changes: 22 additions & 31 deletions pyo3-macros-backend/src/frompyobject.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
use crate::attributes::{DefaultAttribute, FromPyWithAttribute, RenamingRule};
use crate::derive_attributes::{ContainerAttributes, FieldAttributes, FieldGetter};
#[cfg(feature = "experimental-inspect")]
use crate::introspection::elide_lifetimes;
use crate::type_hint::PythonTypeHint;
use crate::utils::{self, Ctx};
use proc_macro2::TokenStream;
use quote::{format_ident, quote, quote_spanned, ToTokens};
Expand Down Expand Up @@ -100,12 +100,8 @@ impl<'a> Enum<'a> {
}

#[cfg(feature = "experimental-inspect")]
fn input_type(&self, ctx: &Ctx) -> TokenStream {
let pyo3_crate_path = &ctx.pyo3_path;
let variants = self.variants.iter().map(|var| var.input_type(ctx));
quote! {
#pyo3_crate_path::inspect::TypeHint::union(&[#(#variants),*])
}
fn input_type(&self) -> PythonTypeHint {
PythonTypeHint::union(self.variants.iter().map(|var| var.input_type()))
}
}

Expand Down Expand Up @@ -457,24 +453,23 @@ impl<'a> Container<'a> {
}

#[cfg(feature = "experimental-inspect")]
fn input_type(&self, ctx: &Ctx) -> TokenStream {
let pyo3_crate_path = &ctx.pyo3_path;
fn input_type(&self) -> PythonTypeHint {
match &self.ty {
ContainerType::StructNewtype(_, from_py_with, ty) => {
Self::field_input_type(from_py_with, ty, ctx)
Self::field_input_type(from_py_with, ty)
}
ContainerType::TupleNewtype(from_py_with, ty) => {
Self::field_input_type(from_py_with, ty, ctx)
}
ContainerType::Tuple(tups) => {
let elements = tups.iter().map(|TupleStructField { from_py_with, ty }| {
Self::field_input_type(from_py_with, ty, ctx)
});
quote! { #pyo3_crate_path::inspect::TypeHint::subscript(&#pyo3_crate_path::inspect::TypeHint::builtin("tuple"), &[#(#elements),*]) }
Self::field_input_type(from_py_with, ty)
}
ContainerType::Tuple(tups) => PythonTypeHint::subscript(
PythonTypeHint::builtin("tuple"),
tups.iter().map(|TupleStructField { from_py_with, ty }| {
Self::field_input_type(from_py_with, ty)
}),
),
ContainerType::Struct(_) => {
// TODO: implement using a Protocol?
quote! { #pyo3_crate_path::inspect::TypeHint::module_attr("_typeshed", "Incomplete") }
PythonTypeHint::module_attr("_typeshed", "Incomplete")
}
}
}
Expand All @@ -483,16 +478,12 @@ impl<'a> Container<'a> {
fn field_input_type(
from_py_with: &Option<FromPyWithAttribute>,
ty: &syn::Type,
ctx: &Ctx,
) -> TokenStream {
let pyo3_crate_path = &ctx.pyo3_path;
) -> PythonTypeHint {
if from_py_with.is_some() {
// We don't know what from_py_with is doing
quote! { #pyo3_crate_path::inspect::TypeHint::module_attr("_typeshed", "Incomplete") }
PythonTypeHint::module_attr("_typeshed", "Incomplete")
} else {
let mut ty = ty.clone();
elide_lifetimes(&mut ty);
quote! { <#ty as #pyo3_crate_path::FromPyObject<'_, '_>>::INPUT_TYPE }
PythonTypeHint::from_from_py_object(ty.clone(), None)
}
}
}
Expand Down Expand Up @@ -570,22 +561,22 @@ pub fn build_derive_from_pyobject(tokens: &DeriveInput) -> Result<TokenStream> {
.all(|p| matches!(p, syn::GenericParam::Lifetime(_)))
{
match &tokens.data {
syn::Data::Enum(en) => Enum::new(en, &tokens.ident, options)?.input_type(ctx),
syn::Data::Enum(en) => Enum::new(en, &tokens.ident, options)?.input_type(),
syn::Data::Struct(st) => {
let ident = &tokens.ident;
Container::new(&st.fields, parse_quote!(#ident), options.clone())?
.input_type(ctx)
Container::new(&st.fields, parse_quote!(#ident), options.clone())?.input_type()
}
syn::Data::Union(_) => {
// Not supported at this point
quote! { #pyo3_crate_path::inspect::TypeHint::module_attr("_typeshed", "Incomplete") }
PythonTypeHint::module_attr("_typeshed", "Incomplete")
}
}
} else {
// We don't know how to deal with generic parameters
// Blocked by https://github.com/rust-lang/rust/issues/76560
quote! { #pyo3_crate_path::inspect::TypeHint::module_attr("_typeshed", "Incomplete") }
};
PythonTypeHint::module_attr("_typeshed", "Incomplete")
}
.to_introspection_token_stream(pyo3_crate_path);
quote! { const INPUT_TYPE: #pyo3_crate_path::inspect::TypeHint = #input_type; }
};
#[cfg(not(feature = "experimental-inspect"))]
Expand Down
52 changes: 21 additions & 31 deletions pyo3-macros-backend/src/intopyobject.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
use crate::attributes::{IntoPyWithAttribute, RenamingRule};
use crate::derive_attributes::{ContainerAttributes, FieldAttributes};
#[cfg(feature = "experimental-inspect")]
use crate::introspection::elide_lifetimes;
use crate::type_hint::PythonTypeHint;
use crate::utils::{self, Ctx};
use proc_macro2::{Span, TokenStream};
use quote::{format_ident, quote, quote_spanned, ToTokens};
Expand Down Expand Up @@ -360,26 +360,23 @@ impl<'a, const REF: bool> Container<'a, REF> {
}

#[cfg(feature = "experimental-inspect")]
fn output_type(&self, ctx: &Ctx) -> TokenStream {
let pyo3_crate_path = &ctx.pyo3_path;
fn output_type(&self) -> PythonTypeHint {
match &self.ty {
ContainerType::StructNewtype(field) | ContainerType::TupleNewtype(field) => {
Self::field_output_type(&None, &field.ty, ctx)
Self::field_output_type(&None, &field.ty)
}
ContainerType::Tuple(tups) => {
let elements = tups.iter().map(
ContainerType::Tuple(tups) => PythonTypeHint::subscript(
PythonTypeHint::builtin("tuple"),
tups.iter().map(
|TupleStructField {
into_py_with,
field,
}| {
Self::field_output_type(into_py_with, &field.ty, ctx)
},
);
quote! { #pyo3_crate_path::inspect::TypeHint::subscript(&#pyo3_crate_path::inspect::TypeHint::builtin("tuple"), &[#(#elements),*]) }
}
}| { Self::field_output_type(into_py_with, &field.ty) },
),
),
ContainerType::Struct(_) => {
// TODO: implement using a Protocol?
quote! { #pyo3_crate_path::inspect::TypeHint::module_attr("_typeshed", "Incomplete") }
PythonTypeHint::module_attr("_typeshed", "Incomplete")
}
}
}
Expand All @@ -388,16 +385,12 @@ impl<'a, const REF: bool> Container<'a, REF> {
fn field_output_type(
into_py_with: &Option<IntoPyWithAttribute>,
ty: &syn::Type,
ctx: &Ctx,
) -> TokenStream {
let pyo3_crate_path = &ctx.pyo3_path;
) -> PythonTypeHint {
if into_py_with.is_some() {
// We don't know what into_py_with is doing
quote! { #pyo3_crate_path::inspect::TypeHint::module_attr("_typeshed", "Incomplete") }
PythonTypeHint::module_attr("_typeshed", "Incomplete")
} else {
let mut ty = ty.clone();
elide_lifetimes(&mut ty);
quote! { <#ty as #pyo3_crate_path::IntoPyObject<'_>>::OUTPUT_TYPE }
PythonTypeHint::from_into_py_object(ty.clone(), None)
}
}
}
Expand Down Expand Up @@ -477,12 +470,8 @@ impl<'a, const REF: bool> Enum<'a, REF> {
}

#[cfg(feature = "experimental-inspect")]
fn output_type(&self, ctx: &Ctx) -> TokenStream {
let pyo3_crate_path = &ctx.pyo3_path;
let variants = self.variants.iter().map(|var| var.output_type(ctx));
quote! {
#pyo3_crate_path::inspect::TypeHint::union(&[#(#variants),*])
}
fn output_type(&self) -> PythonTypeHint {
PythonTypeHint::union(self.variants.iter().map(|var| var.output_type()))
}
}

Expand Down Expand Up @@ -586,7 +575,7 @@ pub fn build_derive_into_pyobject<const REF: bool>(tokens: &DeriveInput) -> Resu
.all(|p| matches!(p, syn::GenericParam::Lifetime(_)))
{
match &tokens.data {
syn::Data::Enum(en) => Enum::<REF>::new(en, &tokens.ident)?.output_type(ctx),
syn::Data::Enum(en) => Enum::<REF>::new(en, &tokens.ident)?.output_type(),
syn::Data::Struct(st) => {
let ident = &tokens.ident;
Container::<REF>::new(
Expand All @@ -595,18 +584,19 @@ pub fn build_derive_into_pyobject<const REF: bool>(tokens: &DeriveInput) -> Resu
parse_quote!(#ident),
options,
)?
.output_type(ctx)
.output_type()
}
syn::Data::Union(_) => {
// Not supported at this point
quote! { #pyo3_crate_path::inspect::TypeHint::module_attr("_typeshed", "Incomplete") }
PythonTypeHint::module_attr("_typeshed", "Incomplete")
}
}
} else {
// We don't know how to deal with generic parameters
// Blocked by https://github.com/rust-lang/rust/issues/76560
quote! { #pyo3_crate_path::inspect::TypeHint::module_attr("_typeshed", "Incomplete") }
};
PythonTypeHint::module_attr("_typeshed", "Incomplete")
}
.to_introspection_token_stream(pyo3_crate_path);
quote! { const OUTPUT_TYPE: #pyo3_path::inspect::TypeHint = #output_type; }
};
#[cfg(not(feature = "experimental-inspect"))]
Expand Down
Loading
Loading