Method,

ClassMethod,

StaticMethod,

GetSet,

Slot,

Attr,

ExtendClass,

Member,

fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {

let s = match self {

Self::Method => "pymethod",

Self::ClassMethod => "pyclassmethod",

Self::StaticMethod => "pystaticmethod",

Self::GetSet => "pygetset",

Self::Slot => "pyslot",

Self::Attr => "pyattr",

Self::ExtendClass => "extend_class",

Self::Member => "pymember",

};

s.fmt(f)

}

type Err = String;

fn from_str(s: &str) -> core::result::Result<Self, Self::Err> {

Ok(match s {

"pymethod" => Self::Method,

"pyclassmethod" => Self::ClassMethod,

"pystaticmethod" => Self::StaticMethod,

"pygetset" => Self::GetSet,

"pyslot" => Self::Slot,

"pyattr" => Self::Attr,

"extend_class" => Self::ExtendClass,

"pymember" => Self::Member,

s => {

return Err(s.to_owned());

}

})

}

is_trait: bool,

attribute_items: ItemNursery,

method_items: MethodNursery,

getset_items: GetSetNursery,

member_items: MemberNursery,

extend_slots_items: ItemNursery,

class_extensions: Vec<TokenStream>,

errors: Vec<syn::Error>,

context: &mut ImplContext,

items: impl Iterator<Item = &'a mut Item>,

) where

Item: ItemLike + ToTokens + GetIdent + syn_ext::ext::ItemAttrExt + 'a,

for item in items {

let r = item.try_split_attr_mut(|attrs, item| {

let (py_items, cfgs) = attrs_to_content_items(attrs, impl_item_new::<Item>)?;

for py_item in py_items.iter().rev() {

let r = py_item.gen_impl_item(ImplItemArgs::<Item> {

item,

attrs,

context,

cfgs: cfgs.as_slice(),

});

context.errors.ok_or_push(r);

}

Ok(())

});

context.errors.ok_or_push(r);

}

context.errors.ok_or_push(context.method_items.validate());

context.errors.ok_or_push(context.getset_items.validate());

context.errors.ok_or_push(context.member_items.validate());

let mut context = ImplContext::default();

let mut tokens = match item {

Item::Impl(mut imp) => {

extract_items_into_context(&mut context, imp.items.iter_mut());

let (impl_ty, payload_guess) = match imp.self_ty.as_ref() {

syn::Type::Path(syn::TypePath {

path: syn::Path { segments, .. },

..

}) if segments.len() == 1 => {

let segment = &segments[0];

let payload_ty = if segment.ident == "Py" || segment.ident == "PyRef" {

match &segment.arguments {

syn::PathArguments::AngleBracketed(

syn::AngleBracketedGenericArguments { args, .. },

) if args.len() == 1 => {

let arg = &args[0];

match arg {

syn::GenericArgument::Type(syn::Type::Path(

syn::TypePath {

path: syn::Path { segments, .. },

..

},

)) if segments.len() == 1 => segments[0].ident.clone(),

_ => {

return Err(syn::Error::new_spanned(

segment,

"Py{Ref}<T> is expected but Py{Ref}<?> is found",

));

}

}

}

_ => {

return Err(syn::Error::new_spanned(

segment,

"Py{Ref}<T> is expected but Py{Ref}? is found",

));

}

}

} else {

if !matches!(segment.arguments, syn::PathArguments::None) {

return Err(syn::Error::new_spanned(

segment,

"PyImpl can only be implemented for Py{Ref}<T> or T",

));

}

segment.ident.clone()

};

(segment.ident.clone(), payload_ty)

}

_ => {

return Err(syn::Error::new_spanned(

imp.self_ty,

"PyImpl can only be implemented for Py{Ref}<T> or T",

));

}

};

let ExtractedImplAttrs {

payload: attr_payload,

flags,

with_impl,

with_method_defs,

with_slots,

itemsize,

} = extract_impl_attrs(attr, &impl_ty)?;

let payload_ty = attr_payload.unwrap_or(payload_guess);

let method_def = &context.method_items;

let getset_impl = &context.getset_items;

let member_impl = &context.member_items;

let extend_impl = context.attribute_items.validate()?;

let slots_impl = context.extend_slots_items.validate()?;

let class_extensions = &context.class_extensions;

let extra_methods = [

parse_quote! {

const __OWN_METHOD_DEFS: &'static [::rustpython_vm::function::PyMethodDef] = &#method_def;

},

parse_quote! {

fn __extend_py_class(

ctx: &'static ::rustpython_vm::Context,

class: &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType>,

) {

#getset_impl

#member_impl

#extend_impl

#(#class_extensions)*

}

},

{

let itemsize_impl = itemsize.as_ref().map(|size| {

quote! {

slots.itemsize = #size;

}

});

parse_quote! {

fn __extend_slots(slots: &mut ::rustpython_vm::types::PyTypeSlots) {

#itemsize_impl

#slots_impl

}

}

},

];

imp.items.extend(extra_methods);

let is_main_impl = impl_ty == payload_ty;

if is_main_impl {

let method_defs = if with_method_defs.is_empty() {

quote!(#impl_ty::__OWN_METHOD_DEFS)

} else {

quote!(

rustpython_vm::function::PyMethodDef::__const_concat_arrays::<

{ #impl_ty::__OWN_METHOD_DEFS.len() #(+ #with_method_defs.len())* },

>(&[#impl_ty::__OWN_METHOD_DEFS, #(#with_method_defs,)*])

)

};

quote! {

#imp

impl ::rustpython_vm::class::PyClassImpl for #payload_ty {

const TP_FLAGS: ::rustpython_vm::types::PyTypeFlags = #flags;

fn impl_extend_class(

ctx: &'static ::rustpython_vm::Context,

class: &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType>,

) {

#impl_ty::__extend_py_class(ctx, class);

#with_impl

}

const METHOD_DEFS: &'static [::rustpython_vm::function::PyMethodDef] = &#method_defs;

fn extend_slots(slots: &mut ::rustpython_vm::types::PyTypeSlots) {

#with_slots

#impl_ty::__extend_slots(slots);

}

}

}

} else {

imp.into_token_stream()

}

}

Item::Trait(mut trai) => {

let mut context = ImplContext {

is_trait: true,

..Default::default()

};

let mut has_extend_slots = false;

for item in &trai.items {

let has = match item {

syn::TraitItem::Fn(item) => item.sig.ident == "extend_slots",

_ => false,

};

if has {

has_extend_slots = has;

break;

}

}

extract_items_into_context(&mut context, trai.items.iter_mut());

let ExtractedImplAttrs {

with_impl,

with_slots,

..

} = extract_impl_attrs(attr, &trai.ident)?;

let method_def = &context.method_items;

let getset_impl = &context.getset_items;

let member_impl = &context.member_items;

let extend_impl = &context.attribute_items.validate()?;

let slots_impl = &context.extend_slots_items.validate()?;

let class_extensions = &context.class_extensions;

let call_extend_slots = if has_extend_slots {

quote! {

Self::extend_slots(slots);

}

} else {

quote! {}

};

let extra_methods = [

parse_quote! {

const __OWN_METHOD_DEFS: &'static [::rustpython_vm::function::PyMethodDef] = &#method_def;

},

parse_quote! {

fn __extend_py_class(

ctx: &'static ::rustpython_vm::Context,

class: &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType>,

) {

#getset_impl

#member_impl

#extend_impl

#with_impl

#(#class_extensions)*

}

},

parse_quote! {

fn __extend_slots(slots: &mut ::rustpython_vm::types::PyTypeSlots) {

#with_slots

#slots_impl

#call_extend_slots

}

},

];

trai.items.extend(extra_methods);

trai.into_token_stream()

}

item => item.into_token_stream(),

};

if let Some(error) = context.errors.into_error() {

let error = Diagnostic::from(error);

tokens = quote! {

#tokens

#error

}

}

Ok(tokens)

let Item::Struct(item_struct) = item else {

// Only validate structs - enums with base are already an error elsewhere

return Ok(None);

};

// Get the base type name for error messages

let base_name = base_path

.segments

.last()

.map_or_else(|| quote!(#base_path).to_string(), |s| s.ident.to_string());

match &item_struct.fields {

syn::Fields::Named(fields) => {

let Some(first_field) = fields.named.first() else {

bail_span!(

item_struct,

"#[pyclass] with base = {base_name} requires the first field to be of type {base_name}, but the struct has no fields"

);

};

if !type_matches_path(&first_field.ty, base_path) {

bail_span!(

first_field,

"#[pyclass] with base = {base_name} requires the first field to be of type {base_name}"

);

}

let ident = first_field.ident.as_ref().map(|id| quote! { #id });

Ok(ident)

}

syn::Fields::Unnamed(fields) => {

let Some(first_field) = fields.unnamed.first() else {

bail_span!(

item_struct,

"#[pyclass] with base = {base_name} requires the first field to be of type {base_name}, but the struct has no fields"

);

};

if !type_matches_path(&first_field.ty, base_path) {

bail_span!(

first_field,

"#[pyclass] with base = {base_name} requires the first field to be of type {base_name}"

);

}

Ok(Some(quote! { 0 }))

}

syn::Fields::Unit => {

bail_span!(

item_struct,

"#[pyclass] with base = {base_name} requires the first field to be of type {base_name}, but the struct is a unit struct"

);

}

}

let Item::Struct(ref mut s) = item else {

return item;

};

let has_repr = s.attrs.iter().any(|attr| attr.path().is_ident("repr"));

if !has_repr {

s.attrs.push(parse_quote!(#[repr(C)]));

}

item

// Compare by converting both to string representation for macro hygiene

let ty_str = quote!(#ty).to_string().replace(' ', "");

let path_str = quote!(#path).to_string().replace(' ', "");

// Check if both are the same or if the type ends with the path's last segment

if ty_str == path_str {

return true;

}

// Also match if just the last segment matches (e.g., foo::Bar matches Bar)

let syn::Type::Path(type_path) = ty else {

return false;

};

let Some(type_last) = type_path.path.segments.last() else {

return false;

};

let Some(path_last) = path.segments.last() else {

return false;

};

type_last.ident == path_last.ident

ident: &Ident,

name: &str,

module_name: Option<&str>,

base: Option<syn::Path>,

metaclass: Option<String>,

unhashable: bool,

attrs: &[Attribute],

) -> Result<TokenStream> {

let doc = attrs.doc().or_else(|| {

let module_name = module_name.unwrap_or("builtins");

DB.get(&format!("{module_name}.{name}"))

.copied()

.map(str::to_owned)

});

let doc = if let Some(doc) = doc {

quote!(Some(#doc))

} else {

quote!(None)

};

let module_class_name = if let Some(module_name) = module_name {

format!("{module_name}.{name}")

} else {

name.to_owned()

};

let module_name = match module_name {

Some(v) => quote!(Some(#v) ),

None => quote!(None),

};

let unhashable = if unhashable {

quote!(true)

} else {

quote!(false)

};

let is_pystruct = attrs.iter().any(|attr| {

attr.path().is_ident("derive")

&& if let Ok(Meta::List(l)) = attr.parse_meta() {

l.nested

.into_iter()

.any(|n| n.get_ident().is_some_and(|p| p == "PyStructSequence"))

} else {

false

}

});

// Check if the type has #[repr(transparent)] - only then we can safely

// generate PySubclass impl (requires same memory layout as base type)

let is_repr_transparent = attrs.iter().any(|attr| {

attr.path().is_ident("repr")

&& if let Ok(Meta::List(l)) = attr.parse_meta() {

l.nested

.into_iter()

.any(|n| n.get_ident().is_some_and(|p| p == "transparent"))

} else {

false

}

});

// If repr(transparent) with a base, the type has the same memory layout as base,

// so basicsize should be 0 (no additional space beyond the base type)

// Otherwise, basicsize = sizeof(payload). The header size is added in __basicsize__ getter.

let basicsize = if is_repr_transparent && base.is_some() {

quote!(0)

} else {

quote!(std::mem::size_of::<#ident>())

};

if base.is_some() && is_pystruct {

bail_span!(ident, "PyStructSequence cannot have `base` class attr",);

}

let base_class = if is_pystruct {

Some(quote! { rustpython_vm::builtins::PyTuple })

} else {

base.as_ref().map(|typ| {

quote_spanned! { ident.span() => #typ }

})

}

.map(|typ| {

quote! {

fn static_baseclass() -> &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType> {

use rustpython_vm::class::StaticType;

#typ::static_type()

}

}

});

let meta_class = metaclass.map(|typ| {

let typ = Ident::new(&typ, ident.span());

quote! {

fn static_metaclass() -> &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType> {

use rustpython_vm::class::StaticType;

#typ::static_type()

}

}

});

let base_or_object = if let Some(ref base) = base {

quote! { #base }

} else {

quote! { ::rustpython_vm::builtins::PyBaseObject }

};

// Generate PySubclass impl for #[repr(transparent)] types with base class

// (tuple struct assumed, so &self.0 works)

let subclass_impl = if !is_pystruct && is_repr_transparent {

base.as_ref().map(|typ| {

quote! {

impl ::rustpython_vm::class::PySubclass for #ident {

type Base = #typ;

#[inline]

fn as_base(&self) -> &Self::Base {

&self.0

}

}

}

})

} else {

None

};

let tokens = quote! {

impl ::rustpython_vm::class::PyClassDef for #ident {

const NAME: &'static str = #name;

const MODULE_NAME: Option<&'static str> = #module_name;

const TP_NAME: &'static str = #module_class_name;

const DOC: Option<&'static str> = #doc;

const BASICSIZE: usize = #basicsize;

const UNHASHABLE: bool = #unhashable;

type Base = #base_or_object;

}

impl ::rustpython_vm::class::StaticType for #ident {

fn static_cell() -> &'static ::rustpython_vm::common::static_cell::StaticCell<::rustpython_vm::builtins::PyTypeRef> {

::rustpython_vm::common::static_cell! {

static CELL: ::rustpython_vm::builtins::PyTypeRef;

}

&CELL

}

#meta_class

#base_class

}

#subclass_impl

};

Ok(tokens)

if matches!(item, syn::Item::Use(_)) {

return Ok(quote!(#item));

}

let fake_ident = Ident::new("pyclass", item.span());

let (class_meta, class_name, module_name, base, metaclass, unhashable) = {

let (ident, _) = pyclass_ident_and_attrs(&item)?;

let class_meta = ClassItemMeta::from_nested(ident.clone(), fake_ident, attr.into_iter())?;

let class_name = class_meta.class_name()?;

let module_name = class_meta.module()?;

let base = class_meta.base()?;

let metaclass = class_meta.metaclass()?;

let unhashable = class_meta.unhashable()?;

(

class_meta,

class_name,

module_name,

base,

metaclass,

unhashable,

)

};

// When a base is specified:

// 1. Validate that the first *declared* field has the base type.

// 2. Auto-insert #[repr(C)] so the compiler preserves declaration order,

// keeping the base field at offset 0 as the inherited getter dispatcher requires.

// 3. Emit a compile-time offset_of! assertion as a safety net for structs that

// already carry an explicit repr that does not guarantee offset 0.

let base_field_token = if let Some(ref base_path) = base {

validate_base_field(&item, base_path)?

} else {

None

};

let item = if base.is_some() {

ensure_repr_c(item)

} else {

item

};

let (ident, attrs) = pyclass_ident_and_attrs(&item)?;

let offset_assert = match (&base, &base_field_token) {

(Some(_), Some(field)) => quote! {

const _: () = ::core::assert!(

::core::mem::offset_of!(#ident, #field) == 0,

concat!(

"The base field of `", stringify!(#ident), "` is not at offset 0. \

)

);

},

_ => quote! {},

};

let class_def = generate_class_def(

ident,

&class_name,

module_name.as_deref(),

base.clone(),

metaclass,

unhashable,

attrs,

)?;

const ALLOWED_TRAVERSE_OPTS: &[&str] = &["manual"];

// Generate MaybeTraverse impl with both traverse and clear support

//

// For traverse:

// 1. no `traverse` at all: HAS_TRAVERSE = false, try_traverse does nothing

// 2. `traverse = "manual"`: HAS_TRAVERSE = true, but no #[derive(Traverse)]

// 3. `traverse`: HAS_TRAVERSE = true, and #[derive(Traverse)]

//

// For clear (tp_clear):

// 1. no `clear`: HAS_CLEAR = HAS_TRAVERSE (default: same as traverse)

// 2. `clear` or `clear = true`: HAS_CLEAR = true, try_clear calls Traverse::clear

// 3. `clear = false`: HAS_CLEAR = false (rare: traverse without clear)

let has_traverse = class_meta.inner().contains_key("traverse");

let has_clear = if class_meta.inner().contains_key("clear") {

// If clear attribute is present, use its value

class_meta.inner()._bool("clear")?

} else {

// If clear attribute is absent, default to same as traverse

has_traverse

};

let derive_trace = if has_traverse {

// _optional_str returns Err when key exists without value (e.g., `traverse` vs `traverse = "manual"`)

// We want to derive Traverse in that case, so we handle Err as Ok(None)

let value = class_meta.inner()._optional_str("traverse").ok().flatten();

if let Some(s) = value {

if !ALLOWED_TRAVERSE_OPTS.contains(&s.as_str()) {

bail_span!(

item,

"traverse attribute only accept {ALLOWED_TRAVERSE_OPTS:?} as value or no value at all",

);

}

assert_eq!(s, "manual");

quote! {}

} else {

quote! {#[derive(Traverse)]}

}

} else {

quote! {}

};

let maybe_traverse_code = {

let try_traverse_body = if has_traverse {

quote! {

::rustpython_vm::object::Traverse::traverse(self, tracer_fn);

}

} else {

quote! {

// do nothing

}

};

let try_clear_body = if has_clear {

quote! {

::rustpython_vm::object::Traverse::clear(self, out);

}

} else {

quote! {

// do nothing

}

};

quote! {

impl ::rustpython_vm::object::MaybeTraverse for #ident {

const HAS_TRAVERSE: bool = #has_traverse;

const HAS_CLEAR: bool = #has_clear;

fn try_traverse(&self, tracer_fn: &mut ::rustpython_vm::object::TraverseFn) {

#try_traverse_body

}

fn try_clear(&mut self, out: &mut ::std::vec::Vec<::rustpython_vm::PyObjectRef>) {

#try_clear_body

}

}

}

};

// Generate PyPayload impl based on whether base exists

#[allow(clippy::collapsible_else_if)]

let impl_payload = if let Some(base_type) = &base {

let class_fn = if let Some(ctx_type_name) = class_meta.ctx_name()? {

let ctx_type_ident = Ident::new(&ctx_type_name, ident.span());

quote! { ctx.types.#ctx_type_ident }

} else {

quote! { <Self as ::rustpython_vm::class::StaticType>::static_type() }

};

quote! {

// static_assertions::const_assert!(std::mem::size_of::<#base_type>() <= std::mem::size_of::<#ident>());

impl ::rustpython_vm::PyPayload for #ident {

const PAYLOAD_TYPE_ID: ::core::any::TypeId = <#base_type as ::rustpython_vm::PyPayload>::PAYLOAD_TYPE_ID;

#[inline]

unsafe fn validate_downcastable_from(obj: &::rustpython_vm::PyObject) -> bool {

<Self as ::rustpython_vm::class::PyClassDef>::BASICSIZE <= obj.class().slots.basicsize && obj.class().fast_issubclass(<Self as ::rustpython_vm::class::StaticType>::static_type())

}

fn class(ctx: &::rustpython_vm::vm::Context) -> &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType> {

#class_fn

}

}

}

} else {

if let Some(ctx_type_name) = class_meta.ctx_name()? {

let ctx_type_ident = Ident::new(&ctx_type_name, ident.span());

quote! {

impl ::rustpython_vm::PyPayload for #ident {

fn class(ctx: &::rustpython_vm::vm::Context) -> &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType> {

ctx.types.#ctx_type_ident

}

}

}

} else {

quote! {}

}

};

let empty_impl = if let Some(attrs) = class_meta.impl_attrs()? {

let attrs: Meta = parse_quote! (#attrs);

quote! {

#[pyclass(#attrs)]

impl #ident {}

}

} else {

quote! {}

};

let ret = quote! {

#derive_trace

#item

#offset_assert

#maybe_traverse_code

#class_def

#impl_payload

#empty_impl

};

Ok(ret)

let (ident, _attrs) = pyexception_ident_and_attrs(item)?;

let fake_ident = Ident::new("pyclass", item.span());

let class_meta = ExceptionItemMeta::from_nested(ident.clone(), fake_ident, attr.into_iter())?;

let class_name = class_meta.class_name()?;

let base_class_name = class_meta.base()?;

let impl_pyclass = if class_meta.has_impl()? {

quote! {

#[pyexception]

impl #ident {}

}

} else {

quote! {}

};

let ret = quote! {

#[pyclass(module = false, name = #class_name, base = #base_class_name)]

#item

#impl_pyclass

};

Ok(ret)

let Item::Impl(imp) = item else {

return item.into_token_stream();

};

// Check if with(Constructor) is specified. If Constructor trait is used, don't generate slot_new

let mut extra_attrs = Vec::new();

let mut with_items = vec![];

for nested in &attr {

if let NestedMeta::Meta(Meta::List(MetaList { path, nested, .. })) = nested {

// If we already found the constructor trait, no need to keep looking for it

if path.is_ident("with") {

for meta in nested {

with_items.push(meta.get_ident().expect("with() has non-ident item").clone());

}

continue;

}

extra_attrs.push(NestedMeta::Meta(Meta::List(MetaList {

path: path.clone(),

paren_token: Default::default(),

nested: nested.clone(),

})));

}

}

let with_contains = |with_items: &[Ident], s: &str| {

// Check if Constructor is in the list

with_items.iter().any(|ident| ident == s)

};

let syn::ItemImpl {

generics,

self_ty,

items,

..

} = &imp;

let slot_new = if with_contains(&with_items, "Constructor") {

quote!()

} else {

with_items.push(Ident::new("Constructor", Span::call_site()));

quote! {

impl ::rustpython_vm::types::Constructor for #self_ty {

type Args = ::rustpython_vm::function::FuncArgs;

fn slot_new(

cls: ::rustpython_vm::builtins::PyTypeRef,

args: ::rustpython_vm::function::FuncArgs,

vm: &::rustpython_vm::VirtualMachine,

) -> ::rustpython_vm::PyResult {

<Self as ::rustpython_vm::class::PyClassDef>::Base::slot_new(cls, args, vm)

}

fn py_new(

_cls: &::rustpython_vm::Py<::rustpython_vm::builtins::PyType>,

_args: Self::Args,

_vm: &::rustpython_vm::VirtualMachine

) -> ::rustpython_vm::PyResult<Self> {

unreachable!("slot_new is defined")

}

}

}

};

// SimpleExtendsException: inherits BaseException_init from the base class via MRO.

// Only exceptions that explicitly specify `with(Initializer)` will have

// their own __init__ in __dict__.

let slot_init = quote!();

let extra_attrs_tokens = quote!(#(#extra_attrs),*);

quote! {

#[pyclass(flags(BASETYPE, HAS_DICT), with(#(#with_items),*), #extra_attrs_tokens)]

impl #generics #self_ty {

#(#items)*

}

#slot_new

#slot_init

}

(

$(#[$meta:meta])*

$vis:vis struct $name:ident

) => {

$(#[$meta])*

$vis struct $name {

inner: ContentItemInner<AttrName>,

}

impl ContentItem for $name {

type AttrName = AttrName;

fn inner(&self) -> &ContentItemInner<AttrName> {

&self.inner

}

}

};

item: &'a Item,

attrs: &'a mut Vec<Attribute>,

context: &'a mut ImplContext,

cfgs: &'a [Attribute],