pyo3_macros_backend/
pymethod.rs

1use std::borrow::Cow;
2use std::ffi::CString;
3
4use crate::attributes::{FromPyWithAttribute, NameAttribute, RenamingRule};
5use crate::method::{CallingConvention, ExtractErrorMode, PyArg};
6use crate::params::{impl_regular_arg_param, Holders};
7use crate::utils::{deprecated_from_py_with, PythonDoc, TypeExt as _};
8use crate::utils::{Ctx, LitCStr};
9use crate::{
10    method::{FnArg, FnSpec, FnType, SelfType},
11    pyfunction::PyFunctionOptions,
12};
13use crate::{quotes, utils};
14use proc_macro2::{Span, TokenStream};
15use quote::{format_ident, quote, quote_spanned, ToTokens};
16use syn::{ext::IdentExt, spanned::Spanned, Result};
17
18/// Generated code for a single pymethod item.
19pub struct MethodAndMethodDef {
20    /// The implementation of the Python wrapper for the pymethod
21    pub associated_method: TokenStream,
22    /// The method def which will be used to register this pymethod
23    pub method_def: TokenStream,
24}
25
26/// Generated code for a single pymethod item which is registered by a slot.
27pub struct MethodAndSlotDef {
28    /// The implementation of the Python wrapper for the pymethod
29    pub associated_method: TokenStream,
30    /// The slot def which will be used to register this pymethod
31    pub slot_def: TokenStream,
32}
33
34pub enum GeneratedPyMethod {
35    Method(MethodAndMethodDef),
36    Proto(MethodAndSlotDef),
37    SlotTraitImpl(String, TokenStream),
38}
39
40pub struct PyMethod<'a> {
41    kind: PyMethodKind,
42    method_name: String,
43    spec: FnSpec<'a>,
44}
45
46enum PyMethodKind {
47    Fn,
48    Proto(PyMethodProtoKind),
49}
50
51impl PyMethodKind {
52    fn from_name(name: &str) -> Self {
53        match name {
54            // Protocol implemented through slots
55            "__str__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__STR__)),
56            "__repr__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__REPR__)),
57            "__hash__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__HASH__)),
58            "__richcmp__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__RICHCMP__)),
59            "__get__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__GET__)),
60            "__iter__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__ITER__)),
61            "__next__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__NEXT__)),
62            "__await__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__AWAIT__)),
63            "__aiter__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__AITER__)),
64            "__anext__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__ANEXT__)),
65            "__len__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__LEN__)),
66            "__contains__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__CONTAINS__)),
67            "__concat__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__CONCAT__)),
68            "__repeat__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__REPEAT__)),
69            "__inplace_concat__" => {
70                PyMethodKind::Proto(PyMethodProtoKind::Slot(&__INPLACE_CONCAT__))
71            }
72            "__inplace_repeat__" => {
73                PyMethodKind::Proto(PyMethodProtoKind::Slot(&__INPLACE_REPEAT__))
74            }
75            "__getitem__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__GETITEM__)),
76            "__pos__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__POS__)),
77            "__neg__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__NEG__)),
78            "__abs__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__ABS__)),
79            "__invert__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__INVERT__)),
80            "__index__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__INDEX__)),
81            "__int__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__INT__)),
82            "__float__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__FLOAT__)),
83            "__bool__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__BOOL__)),
84            "__iadd__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IADD__)),
85            "__isub__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__ISUB__)),
86            "__imul__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IMUL__)),
87            "__imatmul__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IMATMUL__)),
88            "__itruediv__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__ITRUEDIV__)),
89            "__ifloordiv__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IFLOORDIV__)),
90            "__imod__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IMOD__)),
91            "__ipow__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IPOW__)),
92            "__ilshift__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__ILSHIFT__)),
93            "__irshift__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IRSHIFT__)),
94            "__iand__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IAND__)),
95            "__ixor__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IXOR__)),
96            "__ior__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__IOR__)),
97            "__getbuffer__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__GETBUFFER__)),
98            "__releasebuffer__" => PyMethodKind::Proto(PyMethodProtoKind::Slot(&__RELEASEBUFFER__)),
99            // Protocols implemented through traits
100            "__getattribute__" => {
101                PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__GETATTRIBUTE__))
102            }
103            "__getattr__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__GETATTR__)),
104            "__setattr__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__SETATTR__)),
105            "__delattr__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__DELATTR__)),
106            "__set__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__SET__)),
107            "__delete__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__DELETE__)),
108            "__setitem__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__SETITEM__)),
109            "__delitem__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__DELITEM__)),
110            "__add__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__ADD__)),
111            "__radd__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RADD__)),
112            "__sub__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__SUB__)),
113            "__rsub__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RSUB__)),
114            "__mul__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__MUL__)),
115            "__rmul__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RMUL__)),
116            "__matmul__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__MATMUL__)),
117            "__rmatmul__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RMATMUL__)),
118            "__floordiv__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__FLOORDIV__)),
119            "__rfloordiv__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RFLOORDIV__)),
120            "__truediv__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__TRUEDIV__)),
121            "__rtruediv__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RTRUEDIV__)),
122            "__divmod__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__DIVMOD__)),
123            "__rdivmod__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RDIVMOD__)),
124            "__mod__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__MOD__)),
125            "__rmod__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RMOD__)),
126            "__lshift__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__LSHIFT__)),
127            "__rlshift__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RLSHIFT__)),
128            "__rshift__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RSHIFT__)),
129            "__rrshift__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RRSHIFT__)),
130            "__and__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__AND__)),
131            "__rand__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RAND__)),
132            "__xor__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__XOR__)),
133            "__rxor__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RXOR__)),
134            "__or__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__OR__)),
135            "__ror__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__ROR__)),
136            "__pow__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__POW__)),
137            "__rpow__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__RPOW__)),
138            "__lt__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__LT__)),
139            "__le__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__LE__)),
140            "__eq__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__EQ__)),
141            "__ne__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__NE__)),
142            "__gt__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__GT__)),
143            "__ge__" => PyMethodKind::Proto(PyMethodProtoKind::SlotFragment(&__GE__)),
144            // Some tricky protocols which don't fit the pattern of the rest
145            "__call__" => PyMethodKind::Proto(PyMethodProtoKind::Call),
146            "__traverse__" => PyMethodKind::Proto(PyMethodProtoKind::Traverse),
147            "__clear__" => PyMethodKind::Proto(PyMethodProtoKind::Clear),
148            // Not a proto
149            _ => PyMethodKind::Fn,
150        }
151    }
152}
153
154enum PyMethodProtoKind {
155    Slot(&'static SlotDef),
156    Call,
157    Traverse,
158    Clear,
159    SlotFragment(&'static SlotFragmentDef),
160}
161
162impl<'a> PyMethod<'a> {
163    fn parse(
164        sig: &'a mut syn::Signature,
165        meth_attrs: &mut Vec<syn::Attribute>,
166        options: PyFunctionOptions,
167    ) -> Result<Self> {
168        let spec = FnSpec::parse(sig, meth_attrs, options)?;
169
170        let method_name = spec.python_name.to_string();
171        let kind = PyMethodKind::from_name(&method_name);
172
173        Ok(Self {
174            kind,
175            method_name,
176            spec,
177        })
178    }
179}
180
181pub fn is_proto_method(name: &str) -> bool {
182    match PyMethodKind::from_name(name) {
183        PyMethodKind::Fn => false,
184        PyMethodKind::Proto(_) => true,
185    }
186}
187
188pub fn gen_py_method(
189    cls: &syn::Type,
190    sig: &mut syn::Signature,
191    meth_attrs: &mut Vec<syn::Attribute>,
192    options: PyFunctionOptions,
193    ctx: &Ctx,
194) -> Result<GeneratedPyMethod> {
195    check_generic(sig)?;
196    ensure_function_options_valid(&options)?;
197    let method = PyMethod::parse(sig, meth_attrs, options)?;
198    let spec = &method.spec;
199    let Ctx { pyo3_path, .. } = ctx;
200
201    Ok(match (method.kind, &spec.tp) {
202        // Class attributes go before protos so that class attributes can be used to set proto
203        // method to None.
204        (_, FnType::ClassAttribute) => {
205            GeneratedPyMethod::Method(impl_py_class_attribute(cls, spec, ctx)?)
206        }
207        (PyMethodKind::Proto(proto_kind), _) => {
208            ensure_no_forbidden_protocol_attributes(&proto_kind, spec, &method.method_name)?;
209            match proto_kind {
210                PyMethodProtoKind::Slot(slot_def) => {
211                    let slot = slot_def.generate_type_slot(cls, spec, &method.method_name, ctx)?;
212                    GeneratedPyMethod::Proto(slot)
213                }
214                PyMethodProtoKind::Call => {
215                    GeneratedPyMethod::Proto(impl_call_slot(cls, method.spec, ctx)?)
216                }
217                PyMethodProtoKind::Traverse => {
218                    GeneratedPyMethod::Proto(impl_traverse_slot(cls, spec, ctx)?)
219                }
220                PyMethodProtoKind::Clear => {
221                    GeneratedPyMethod::Proto(impl_clear_slot(cls, spec, ctx)?)
222                }
223                PyMethodProtoKind::SlotFragment(slot_fragment_def) => {
224                    let proto = slot_fragment_def.generate_pyproto_fragment(cls, spec, ctx)?;
225                    GeneratedPyMethod::SlotTraitImpl(method.method_name, proto)
226                }
227            }
228        }
229        // ordinary functions (with some specialties)
230        (_, FnType::Fn(_)) => GeneratedPyMethod::Method(impl_py_method_def(
231            cls,
232            spec,
233            &spec.get_doc(meth_attrs, ctx),
234            None,
235            ctx,
236        )?),
237        (_, FnType::FnClass(_)) => GeneratedPyMethod::Method(impl_py_method_def(
238            cls,
239            spec,
240            &spec.get_doc(meth_attrs, ctx),
241            Some(quote!(#pyo3_path::ffi::METH_CLASS)),
242            ctx,
243        )?),
244        (_, FnType::FnStatic) => GeneratedPyMethod::Method(impl_py_method_def(
245            cls,
246            spec,
247            &spec.get_doc(meth_attrs, ctx),
248            Some(quote!(#pyo3_path::ffi::METH_STATIC)),
249            ctx,
250        )?),
251        // special prototypes
252        (_, FnType::FnNew) | (_, FnType::FnNewClass(_)) => {
253            GeneratedPyMethod::Proto(impl_py_method_def_new(cls, spec, ctx)?)
254        }
255
256        (_, FnType::Getter(self_type)) => GeneratedPyMethod::Method(impl_py_getter_def(
257            cls,
258            PropertyType::Function {
259                self_type,
260                spec,
261                doc: spec.get_doc(meth_attrs, ctx),
262            },
263            ctx,
264        )?),
265        (_, FnType::Setter(self_type)) => GeneratedPyMethod::Method(impl_py_setter_def(
266            cls,
267            PropertyType::Function {
268                self_type,
269                spec,
270                doc: spec.get_doc(meth_attrs, ctx),
271            },
272            ctx,
273        )?),
274        (_, FnType::FnModule(_)) => {
275            unreachable!("methods cannot be FnModule")
276        }
277    })
278}
279
280pub fn check_generic(sig: &syn::Signature) -> syn::Result<()> {
281    let err_msg = |typ| format!("Python functions cannot have generic {} parameters", typ);
282    for param in &sig.generics.params {
283        match param {
284            syn::GenericParam::Lifetime(_) => {}
285            syn::GenericParam::Type(_) => bail_spanned!(param.span() => err_msg("type")),
286            syn::GenericParam::Const(_) => bail_spanned!(param.span() => err_msg("const")),
287        }
288    }
289    Ok(())
290}
291
292fn ensure_function_options_valid(options: &PyFunctionOptions) -> syn::Result<()> {
293    if let Some(pass_module) = &options.pass_module {
294        bail_spanned!(pass_module.span() => "`pass_module` cannot be used on Python methods");
295    }
296    Ok(())
297}
298
299fn ensure_no_forbidden_protocol_attributes(
300    proto_kind: &PyMethodProtoKind,
301    spec: &FnSpec<'_>,
302    method_name: &str,
303) -> syn::Result<()> {
304    if let Some(signature) = &spec.signature.attribute {
305        // __call__ is allowed to have a signature, but nothing else is.
306        if !matches!(proto_kind, PyMethodProtoKind::Call) {
307            bail_spanned!(signature.kw.span() => format!("`signature` cannot be used with magic method `{}`", method_name));
308        }
309    }
310    if let Some(text_signature) = &spec.text_signature {
311        bail_spanned!(text_signature.kw.span() => format!("`text_signature` cannot be used with magic method `{}`", method_name));
312    }
313    Ok(())
314}
315
316/// Also used by pyfunction.
317pub fn impl_py_method_def(
318    cls: &syn::Type,
319    spec: &FnSpec<'_>,
320    doc: &PythonDoc,
321    flags: Option<TokenStream>,
322    ctx: &Ctx,
323) -> Result<MethodAndMethodDef> {
324    let Ctx { pyo3_path, .. } = ctx;
325    let wrapper_ident = format_ident!("__pymethod_{}__", spec.python_name);
326    let associated_method = spec.get_wrapper_function(&wrapper_ident, Some(cls), ctx)?;
327    let add_flags = flags.map(|flags| quote!(.flags(#flags)));
328    let methoddef_type = match spec.tp {
329        FnType::FnStatic => quote!(Static),
330        FnType::FnClass(_) => quote!(Class),
331        _ => quote!(Method),
332    };
333    let methoddef = spec.get_methoddef(quote! { #cls::#wrapper_ident }, doc, ctx);
334    let method_def = quote! {
335        #pyo3_path::impl_::pyclass::MaybeRuntimePyMethodDef::Static(
336            #pyo3_path::impl_::pymethods::PyMethodDefType::#methoddef_type(#methoddef #add_flags)
337        )
338    };
339    Ok(MethodAndMethodDef {
340        associated_method,
341        method_def,
342    })
343}
344
345/// Also used by pyclass.
346pub fn impl_py_method_def_new(
347    cls: &syn::Type,
348    spec: &FnSpec<'_>,
349    ctx: &Ctx,
350) -> Result<MethodAndSlotDef> {
351    let Ctx { pyo3_path, .. } = ctx;
352    let wrapper_ident = syn::Ident::new("__pymethod___new____", Span::call_site());
353    let associated_method = spec.get_wrapper_function(&wrapper_ident, Some(cls), ctx)?;
354    // Use just the text_signature_call_signature() because the class' Python name
355    // isn't known to `#[pymethods]` - that has to be attached at runtime from the PyClassImpl
356    // trait implementation created by `#[pyclass]`.
357    let text_signature_body = spec.text_signature_call_signature().map_or_else(
358        || quote!(::std::option::Option::None),
359        |text_signature| quote!(::std::option::Option::Some(#text_signature)),
360    );
361    let slot_def = quote! {
362        #pyo3_path::ffi::PyType_Slot {
363            slot: #pyo3_path::ffi::Py_tp_new,
364            pfunc: {
365                unsafe extern "C" fn trampoline(
366                    subtype: *mut #pyo3_path::ffi::PyTypeObject,
367                    args: *mut #pyo3_path::ffi::PyObject,
368                    kwargs: *mut #pyo3_path::ffi::PyObject,
369                ) -> *mut #pyo3_path::ffi::PyObject {
370                    #[allow(unknown_lints, non_local_definitions)]
371                    impl #pyo3_path::impl_::pyclass::PyClassNewTextSignature<#cls> for #pyo3_path::impl_::pyclass::PyClassImplCollector<#cls> {
372                        #[inline]
373                        fn new_text_signature(self) -> ::std::option::Option<&'static str> {
374                            #text_signature_body
375                        }
376                    }
377
378                    #pyo3_path::impl_::trampoline::newfunc(
379                        subtype,
380                        args,
381                        kwargs,
382                        #cls::#wrapper_ident
383                    )
384                }
385                trampoline
386            } as #pyo3_path::ffi::newfunc as _
387        }
388    };
389    Ok(MethodAndSlotDef {
390        associated_method,
391        slot_def,
392    })
393}
394
395fn impl_call_slot(cls: &syn::Type, mut spec: FnSpec<'_>, ctx: &Ctx) -> Result<MethodAndSlotDef> {
396    let Ctx { pyo3_path, .. } = ctx;
397
398    // HACK: __call__ proto slot must always use varargs calling convention, so change the spec.
399    // Probably indicates there's a refactoring opportunity somewhere.
400    spec.convention = CallingConvention::Varargs;
401
402    let wrapper_ident = syn::Ident::new("__pymethod___call____", Span::call_site());
403    let associated_method = spec.get_wrapper_function(&wrapper_ident, Some(cls), ctx)?;
404    let slot_def = quote! {
405        #pyo3_path::ffi::PyType_Slot {
406            slot: #pyo3_path::ffi::Py_tp_call,
407            pfunc: {
408                unsafe extern "C" fn trampoline(
409                    slf: *mut #pyo3_path::ffi::PyObject,
410                    args: *mut #pyo3_path::ffi::PyObject,
411                    kwargs: *mut #pyo3_path::ffi::PyObject,
412                ) -> *mut #pyo3_path::ffi::PyObject
413                {
414                    #pyo3_path::impl_::trampoline::ternaryfunc(
415                        slf,
416                        args,
417                        kwargs,
418                        #cls::#wrapper_ident
419                    )
420                }
421                trampoline
422            } as #pyo3_path::ffi::ternaryfunc as _
423        }
424    };
425    Ok(MethodAndSlotDef {
426        associated_method,
427        slot_def,
428    })
429}
430
431fn impl_traverse_slot(
432    cls: &syn::Type,
433    spec: &FnSpec<'_>,
434    ctx: &Ctx,
435) -> syn::Result<MethodAndSlotDef> {
436    let Ctx { pyo3_path, .. } = ctx;
437    if let (Some(py_arg), _) = split_off_python_arg(&spec.signature.arguments) {
438        return Err(syn::Error::new_spanned(py_arg.ty, "__traverse__ may not take `Python`. \
439            Usually, an implementation of `__traverse__(&self, visit: PyVisit<'_>) -> Result<(), PyTraverseError>` \
440            should do nothing but calls to `visit.call`. Most importantly, safe access to the GIL is prohibited \
441            inside implementations of `__traverse__`, i.e. `Python::with_gil` will panic."));
442    }
443
444    // check that the receiver does not try to smuggle an (implicit) `Python` token into here
445    if let FnType::Fn(SelfType::TryFromBoundRef(span))
446    | FnType::Fn(SelfType::Receiver {
447        mutable: true,
448        span,
449    }) = spec.tp
450    {
451        bail_spanned! { span =>
452            "__traverse__ may not take a receiver other than `&self`. Usually, an implementation of \
453            `__traverse__(&self, visit: PyVisit<'_>) -> Result<(), PyTraverseError>` \
454            should do nothing but calls to `visit.call`. Most importantly, safe access to the GIL is prohibited \
455            inside implementations of `__traverse__`, i.e. `Python::with_gil` will panic."
456        }
457    }
458
459    let rust_fn_ident = spec.name;
460
461    let associated_method = quote! {
462        pub unsafe extern "C" fn __pymethod_traverse__(
463            slf: *mut #pyo3_path::ffi::PyObject,
464            visit: #pyo3_path::ffi::visitproc,
465            arg: *mut ::std::os::raw::c_void,
466        ) -> ::std::os::raw::c_int {
467            #pyo3_path::impl_::pymethods::_call_traverse::<#cls>(slf, #cls::#rust_fn_ident, visit, arg, #cls::__pymethod_traverse__)
468        }
469    };
470    let slot_def = quote! {
471        #pyo3_path::ffi::PyType_Slot {
472            slot: #pyo3_path::ffi::Py_tp_traverse,
473            pfunc: #cls::__pymethod_traverse__ as #pyo3_path::ffi::traverseproc as _
474        }
475    };
476    Ok(MethodAndSlotDef {
477        associated_method,
478        slot_def,
479    })
480}
481
482fn impl_clear_slot(cls: &syn::Type, spec: &FnSpec<'_>, ctx: &Ctx) -> syn::Result<MethodAndSlotDef> {
483    let Ctx { pyo3_path, .. } = ctx;
484    let (py_arg, args) = split_off_python_arg(&spec.signature.arguments);
485    let self_type = match &spec.tp {
486        FnType::Fn(self_type) => self_type,
487        _ => bail_spanned!(spec.name.span() => "expected instance method for `__clear__` function"),
488    };
489    let mut holders = Holders::new();
490    let slf = self_type.receiver(cls, ExtractErrorMode::Raise, &mut holders, ctx);
491
492    if let [arg, ..] = args {
493        bail_spanned!(arg.ty().span() => "`__clear__` function expected to have no arguments");
494    }
495
496    let name = &spec.name;
497    let holders = holders.init_holders(ctx);
498    let fncall = if py_arg.is_some() {
499        quote!(#cls::#name(#slf, py))
500    } else {
501        quote!(#cls::#name(#slf))
502    };
503
504    let associated_method = quote! {
505        pub unsafe extern "C" fn __pymethod___clear____(
506            _slf: *mut #pyo3_path::ffi::PyObject,
507        ) -> ::std::os::raw::c_int {
508            #pyo3_path::impl_::pymethods::_call_clear(_slf, |py, _slf| {
509                #holders
510                let result = #fncall;
511                let result = #pyo3_path::impl_::wrap::converter(&result).wrap(result)?;
512                ::std::result::Result::Ok(result)
513            }, #cls::__pymethod___clear____)
514        }
515    };
516    let slot_def = quote! {
517        #pyo3_path::ffi::PyType_Slot {
518            slot: #pyo3_path::ffi::Py_tp_clear,
519            pfunc: #cls::__pymethod___clear____ as #pyo3_path::ffi::inquiry as _
520        }
521    };
522    Ok(MethodAndSlotDef {
523        associated_method,
524        slot_def,
525    })
526}
527
528pub(crate) fn impl_py_class_attribute(
529    cls: &syn::Type,
530    spec: &FnSpec<'_>,
531    ctx: &Ctx,
532) -> syn::Result<MethodAndMethodDef> {
533    let Ctx { pyo3_path, .. } = ctx;
534    let (py_arg, args) = split_off_python_arg(&spec.signature.arguments);
535    ensure_spanned!(
536        args.is_empty(),
537        args[0].ty().span() => "#[classattr] can only have one argument (of type pyo3::Python)"
538    );
539
540    let name = &spec.name;
541    let fncall = if py_arg.is_some() {
542        quote!(function(py))
543    } else {
544        quote!(function())
545    };
546
547    let wrapper_ident = format_ident!("__pymethod_{}__", name);
548    let python_name = spec.null_terminated_python_name(ctx);
549    let body = quotes::ok_wrap(fncall, ctx);
550
551    let associated_method = quote! {
552        fn #wrapper_ident(py: #pyo3_path::Python<'_>) -> #pyo3_path::PyResult<#pyo3_path::PyObject> {
553            let function = #cls::#name; // Shadow the method name to avoid #3017
554            let result = #body;
555            #pyo3_path::impl_::wrap::converter(&result).map_into_pyobject(py, result)
556        }
557    };
558
559    let method_def = quote! {
560        #pyo3_path::impl_::pyclass::MaybeRuntimePyMethodDef::Static(
561            #pyo3_path::impl_::pymethods::PyMethodDefType::ClassAttribute({
562                #pyo3_path::impl_::pymethods::PyClassAttributeDef::new(
563                    #python_name,
564                    #cls::#wrapper_ident
565                )
566            })
567        )
568    };
569
570    Ok(MethodAndMethodDef {
571        associated_method,
572        method_def,
573    })
574}
575
576fn impl_call_setter(
577    cls: &syn::Type,
578    spec: &FnSpec<'_>,
579    self_type: &SelfType,
580    holders: &mut Holders,
581    ctx: &Ctx,
582) -> syn::Result<TokenStream> {
583    let (py_arg, args) = split_off_python_arg(&spec.signature.arguments);
584    let slf = self_type.receiver(cls, ExtractErrorMode::Raise, holders, ctx);
585
586    if args.is_empty() {
587        bail_spanned!(spec.name.span() => "setter function expected to have one argument");
588    } else if args.len() > 1 {
589        bail_spanned!(
590            args[1].ty().span() =>
591            "setter function can have at most two arguments ([pyo3::Python,] and value)"
592        );
593    }
594
595    let name = &spec.name;
596    let fncall = if py_arg.is_some() {
597        quote!(#cls::#name(#slf, py, _val))
598    } else {
599        quote!(#cls::#name(#slf, _val))
600    };
601
602    Ok(fncall)
603}
604
605// Used here for PropertyType::Function, used in pyclass for descriptors.
606pub fn impl_py_setter_def(
607    cls: &syn::Type,
608    property_type: PropertyType<'_>,
609    ctx: &Ctx,
610) -> Result<MethodAndMethodDef> {
611    let Ctx { pyo3_path, .. } = ctx;
612    let python_name = property_type.null_terminated_python_name(ctx)?;
613    let doc = property_type.doc(ctx);
614    let mut holders = Holders::new();
615    let setter_impl = match property_type {
616        PropertyType::Descriptor {
617            field_index, field, ..
618        } => {
619            let slf = SelfType::Receiver {
620                mutable: true,
621                span: Span::call_site(),
622            }
623            .receiver(cls, ExtractErrorMode::Raise, &mut holders, ctx);
624            if let Some(ident) = &field.ident {
625                // named struct field
626                quote!({ #slf.#ident = _val; })
627            } else {
628                // tuple struct field
629                let index = syn::Index::from(field_index);
630                quote!({ #slf.#index = _val; })
631            }
632        }
633        PropertyType::Function {
634            spec, self_type, ..
635        } => impl_call_setter(cls, spec, self_type, &mut holders, ctx)?,
636    };
637
638    let wrapper_ident = match property_type {
639        PropertyType::Descriptor {
640            field: syn::Field {
641                ident: Some(ident), ..
642            },
643            ..
644        } => {
645            format_ident!("__pymethod_set_{}__", ident)
646        }
647        PropertyType::Descriptor { field_index, .. } => {
648            format_ident!("__pymethod_set_field_{}__", field_index)
649        }
650        PropertyType::Function { spec, .. } => {
651            format_ident!("__pymethod_set_{}__", spec.name)
652        }
653    };
654
655    let extract = match &property_type {
656        PropertyType::Function { spec, .. } => {
657            let (_, args) = split_off_python_arg(&spec.signature.arguments);
658            let value_arg = &args[0];
659            let (from_py_with, ident) =
660                if let Some(from_py_with) = &value_arg.from_py_with().as_ref().map(|f| &f.value) {
661                    let ident = syn::Ident::new("from_py_with", from_py_with.span());
662                    let d = deprecated_from_py_with(from_py_with).unwrap_or_default();
663                    (
664                        quote_spanned! { from_py_with.span() =>
665                            #d
666                            let #ident = #from_py_with;
667                        },
668                        ident,
669                    )
670                } else {
671                    (quote!(), syn::Ident::new("dummy", Span::call_site()))
672                };
673
674            let arg = if let FnArg::Regular(arg) = &value_arg {
675                arg
676            } else {
677                bail_spanned!(value_arg.name().span() => "The #[setter] value argument can't be *args, **kwargs or `cancel_handle`.");
678            };
679
680            let extract = impl_regular_arg_param(
681                arg,
682                ident,
683                quote!(::std::option::Option::Some(_value.into())),
684                &mut holders,
685                ctx,
686            );
687
688            quote! {
689                #from_py_with
690                let _val = #extract;
691            }
692        }
693        PropertyType::Descriptor { field, .. } => {
694            let span = field.ty.span();
695            let name = field
696                .ident
697                .as_ref()
698                .map(|i| i.to_string())
699                .unwrap_or_default();
700
701            let holder = holders.push_holder(span);
702            let ty = field.ty.clone().elide_lifetimes();
703            quote! {
704                #[allow(unused_imports)]
705                use #pyo3_path::impl_::pyclass::Probe as _;
706                let _val = #pyo3_path::impl_::extract_argument::extract_argument::<
707                    _,
708                    { #pyo3_path::impl_::pyclass::IsOption::<#ty>::VALUE }
709                >(_value.into(), &mut #holder, #name)?;
710            }
711        }
712    };
713
714    let mut cfg_attrs = TokenStream::new();
715    if let PropertyType::Descriptor { field, .. } = &property_type {
716        for attr in field
717            .attrs
718            .iter()
719            .filter(|attr| attr.path().is_ident("cfg"))
720        {
721            attr.to_tokens(&mut cfg_attrs);
722        }
723    }
724
725    let init_holders = holders.init_holders(ctx);
726    let associated_method = quote! {
727        #cfg_attrs
728        unsafe fn #wrapper_ident(
729            py: #pyo3_path::Python<'_>,
730            _slf: *mut #pyo3_path::ffi::PyObject,
731            _value: *mut #pyo3_path::ffi::PyObject,
732        ) -> #pyo3_path::PyResult<::std::os::raw::c_int> {
733            use ::std::convert::Into;
734            let _value = #pyo3_path::impl_::pymethods::BoundRef::ref_from_ptr_or_opt(py, &_value)
735                .ok_or_else(|| {
736                    #pyo3_path::exceptions::PyAttributeError::new_err("can't delete attribute")
737                })?;
738            #init_holders
739            #extract
740            let result = #setter_impl;
741            #pyo3_path::impl_::callback::convert(py, result)
742        }
743    };
744
745    let method_def = quote! {
746        #cfg_attrs
747        #pyo3_path::impl_::pyclass::MaybeRuntimePyMethodDef::Static(
748            #pyo3_path::impl_::pymethods::PyMethodDefType::Setter(
749                #pyo3_path::impl_::pymethods::PySetterDef::new(
750                    #python_name,
751                    #cls::#wrapper_ident,
752                    #doc
753                )
754            )
755        )
756    };
757
758    Ok(MethodAndMethodDef {
759        associated_method,
760        method_def,
761    })
762}
763
764fn impl_call_getter(
765    cls: &syn::Type,
766    spec: &FnSpec<'_>,
767    self_type: &SelfType,
768    holders: &mut Holders,
769    ctx: &Ctx,
770) -> syn::Result<TokenStream> {
771    let (py_arg, args) = split_off_python_arg(&spec.signature.arguments);
772    let slf = self_type.receiver(cls, ExtractErrorMode::Raise, holders, ctx);
773    ensure_spanned!(
774        args.is_empty(),
775        args[0].ty().span() => "getter function can only have one argument (of type pyo3::Python)"
776    );
777
778    let name = &spec.name;
779    let fncall = if py_arg.is_some() {
780        quote!(#cls::#name(#slf, py))
781    } else {
782        quote!(#cls::#name(#slf))
783    };
784
785    Ok(fncall)
786}
787
788// Used here for PropertyType::Function, used in pyclass for descriptors.
789pub fn impl_py_getter_def(
790    cls: &syn::Type,
791    property_type: PropertyType<'_>,
792    ctx: &Ctx,
793) -> Result<MethodAndMethodDef> {
794    let Ctx { pyo3_path, .. } = ctx;
795    let python_name = property_type.null_terminated_python_name(ctx)?;
796    let doc = property_type.doc(ctx);
797
798    let mut cfg_attrs = TokenStream::new();
799    if let PropertyType::Descriptor { field, .. } = &property_type {
800        for attr in field
801            .attrs
802            .iter()
803            .filter(|attr| attr.path().is_ident("cfg"))
804        {
805            attr.to_tokens(&mut cfg_attrs);
806        }
807    }
808
809    let mut holders = Holders::new();
810    match property_type {
811        PropertyType::Descriptor {
812            field_index, field, ..
813        } => {
814            let ty = &field.ty;
815            let field = if let Some(ident) = &field.ident {
816                ident.to_token_stream()
817            } else {
818                syn::Index::from(field_index).to_token_stream()
819            };
820
821            // TODO: on MSRV 1.77+, we can use `::std::mem::offset_of!` here, and it should
822            // make it possible for the `MaybeRuntimePyMethodDef` to be a `Static` variant.
823            let generator = quote_spanned! { ty.span() =>
824                #pyo3_path::impl_::pyclass::MaybeRuntimePyMethodDef::Runtime(
825                    || GENERATOR.generate(#python_name, #doc)
826                )
827            };
828            // This is separate so that the unsafe below does not inherit the span and thus does not
829            // trigger the `unsafe_code` lint
830            let method_def = quote! {
831                #cfg_attrs
832                {
833                    #[allow(unused_imports)]  // might not be used if all probes are positve
834                    use #pyo3_path::impl_::pyclass::Probe;
835
836                    struct Offset;
837                    unsafe impl #pyo3_path::impl_::pyclass::OffsetCalculator<#cls, #ty> for Offset {
838                        fn offset() -> usize {
839                            #pyo3_path::impl_::pyclass::class_offset::<#cls>() +
840                            #pyo3_path::impl_::pyclass::offset_of!(#cls, #field)
841                        }
842                    }
843
844                    const GENERATOR: #pyo3_path::impl_::pyclass::PyClassGetterGenerator::<
845                        #cls,
846                        #ty,
847                        Offset,
848                        { #pyo3_path::impl_::pyclass::IsPyT::<#ty>::VALUE },
849                        { #pyo3_path::impl_::pyclass::IsIntoPyObjectRef::<#ty>::VALUE },
850                        { #pyo3_path::impl_::pyclass::IsIntoPyObject::<#ty>::VALUE },
851                    > = unsafe { #pyo3_path::impl_::pyclass::PyClassGetterGenerator::new() };
852                    #generator
853                }
854            };
855
856            Ok(MethodAndMethodDef {
857                associated_method: quote! {},
858                method_def,
859            })
860        }
861        // Forward to `IntoPyCallbackOutput`, to handle `#[getter]`s returning results.
862        PropertyType::Function {
863            spec, self_type, ..
864        } => {
865            let wrapper_ident = format_ident!("__pymethod_get_{}__", spec.name);
866            let call = impl_call_getter(cls, spec, self_type, &mut holders, ctx)?;
867            let body = quote! {
868                #pyo3_path::impl_::callback::convert(py, #call)
869            };
870
871            let init_holders = holders.init_holders(ctx);
872            let associated_method = quote! {
873                #cfg_attrs
874                unsafe fn #wrapper_ident(
875                    py: #pyo3_path::Python<'_>,
876                    _slf: *mut #pyo3_path::ffi::PyObject
877                ) -> #pyo3_path::PyResult<*mut #pyo3_path::ffi::PyObject> {
878                    #init_holders
879                    let result = #body;
880                    result
881                }
882            };
883
884            let method_def = quote! {
885                #cfg_attrs
886                #pyo3_path::impl_::pyclass::MaybeRuntimePyMethodDef::Static(
887                    #pyo3_path::impl_::pymethods::PyMethodDefType::Getter(
888                        #pyo3_path::impl_::pymethods::PyGetterDef::new(
889                            #python_name,
890                            #cls::#wrapper_ident,
891                            #doc
892                        )
893                    )
894                )
895            };
896
897            Ok(MethodAndMethodDef {
898                associated_method,
899                method_def,
900            })
901        }
902    }
903}
904
905/// Split an argument of pyo3::Python from the front of the arg list, if present
906fn split_off_python_arg<'a, 'b>(args: &'a [FnArg<'b>]) -> (Option<&'a PyArg<'b>>, &'a [FnArg<'b>]) {
907    match args {
908        [FnArg::Py(py), args @ ..] => (Some(py), args),
909        args => (None, args),
910    }
911}
912
913pub enum PropertyType<'a> {
914    Descriptor {
915        field_index: usize,
916        field: &'a syn::Field,
917        python_name: Option<&'a NameAttribute>,
918        renaming_rule: Option<RenamingRule>,
919    },
920    Function {
921        self_type: &'a SelfType,
922        spec: &'a FnSpec<'a>,
923        doc: PythonDoc,
924    },
925}
926
927impl PropertyType<'_> {
928    fn null_terminated_python_name(&self, ctx: &Ctx) -> Result<LitCStr> {
929        match self {
930            PropertyType::Descriptor {
931                field,
932                python_name,
933                renaming_rule,
934                ..
935            } => {
936                let name = match (python_name, &field.ident) {
937                    (Some(name), _) => name.value.0.to_string(),
938                    (None, Some(field_name)) => {
939                        let mut name = field_name.unraw().to_string();
940                        if let Some(rule) = renaming_rule {
941                            name = utils::apply_renaming_rule(*rule, &name);
942                        }
943                        name
944                    }
945                    (None, None) => {
946                        bail_spanned!(field.span() => "`get` and `set` with tuple struct fields require `name`");
947                    }
948                };
949                let name = CString::new(name).unwrap();
950                Ok(LitCStr::new(name, field.span(), ctx))
951            }
952            PropertyType::Function { spec, .. } => Ok(spec.null_terminated_python_name(ctx)),
953        }
954    }
955
956    fn doc(&self, ctx: &Ctx) -> Cow<'_, PythonDoc> {
957        match self {
958            PropertyType::Descriptor { field, .. } => {
959                Cow::Owned(utils::get_doc(&field.attrs, None, ctx))
960            }
961            PropertyType::Function { doc, .. } => Cow::Borrowed(doc),
962        }
963    }
964}
965
966pub const __STR__: SlotDef = SlotDef::new("Py_tp_str", "reprfunc");
967pub const __REPR__: SlotDef = SlotDef::new("Py_tp_repr", "reprfunc");
968pub const __HASH__: SlotDef = SlotDef::new("Py_tp_hash", "hashfunc")
969    .ret_ty(Ty::PyHashT)
970    .return_conversion(TokenGenerator(
971        |Ctx { pyo3_path, .. }: &Ctx| quote! { #pyo3_path::impl_::callback::HashCallbackOutput },
972    ));
973pub const __RICHCMP__: SlotDef = SlotDef::new("Py_tp_richcompare", "richcmpfunc")
974    .extract_error_mode(ExtractErrorMode::NotImplemented)
975    .arguments(&[Ty::Object, Ty::CompareOp]);
976const __GET__: SlotDef = SlotDef::new("Py_tp_descr_get", "descrgetfunc")
977    .arguments(&[Ty::MaybeNullObject, Ty::MaybeNullObject]);
978const __ITER__: SlotDef = SlotDef::new("Py_tp_iter", "getiterfunc");
979const __NEXT__: SlotDef = SlotDef::new("Py_tp_iternext", "iternextfunc")
980    .return_specialized_conversion(
981        TokenGenerator(|_| quote! { IterBaseKind, IterOptionKind, IterResultOptionKind }),
982        TokenGenerator(|_| quote! { iter_tag }),
983    );
984const __AWAIT__: SlotDef = SlotDef::new("Py_am_await", "unaryfunc");
985const __AITER__: SlotDef = SlotDef::new("Py_am_aiter", "unaryfunc");
986const __ANEXT__: SlotDef = SlotDef::new("Py_am_anext", "unaryfunc").return_specialized_conversion(
987    TokenGenerator(
988        |_| quote! { AsyncIterBaseKind, AsyncIterOptionKind, AsyncIterResultOptionKind },
989    ),
990    TokenGenerator(|_| quote! { async_iter_tag }),
991);
992pub const __LEN__: SlotDef = SlotDef::new("Py_mp_length", "lenfunc").ret_ty(Ty::PySsizeT);
993const __CONTAINS__: SlotDef = SlotDef::new("Py_sq_contains", "objobjproc")
994    .arguments(&[Ty::Object])
995    .ret_ty(Ty::Int);
996const __CONCAT__: SlotDef = SlotDef::new("Py_sq_concat", "binaryfunc").arguments(&[Ty::Object]);
997const __REPEAT__: SlotDef = SlotDef::new("Py_sq_repeat", "ssizeargfunc").arguments(&[Ty::PySsizeT]);
998const __INPLACE_CONCAT__: SlotDef =
999    SlotDef::new("Py_sq_concat", "binaryfunc").arguments(&[Ty::Object]);
1000const __INPLACE_REPEAT__: SlotDef =
1001    SlotDef::new("Py_sq_repeat", "ssizeargfunc").arguments(&[Ty::PySsizeT]);
1002pub const __GETITEM__: SlotDef =
1003    SlotDef::new("Py_mp_subscript", "binaryfunc").arguments(&[Ty::Object]);
1004
1005const __POS__: SlotDef = SlotDef::new("Py_nb_positive", "unaryfunc");
1006const __NEG__: SlotDef = SlotDef::new("Py_nb_negative", "unaryfunc");
1007const __ABS__: SlotDef = SlotDef::new("Py_nb_absolute", "unaryfunc");
1008const __INVERT__: SlotDef = SlotDef::new("Py_nb_invert", "unaryfunc");
1009const __INDEX__: SlotDef = SlotDef::new("Py_nb_index", "unaryfunc");
1010pub const __INT__: SlotDef = SlotDef::new("Py_nb_int", "unaryfunc");
1011const __FLOAT__: SlotDef = SlotDef::new("Py_nb_float", "unaryfunc");
1012const __BOOL__: SlotDef = SlotDef::new("Py_nb_bool", "inquiry").ret_ty(Ty::Int);
1013
1014const __IADD__: SlotDef = SlotDef::new("Py_nb_inplace_add", "binaryfunc")
1015    .arguments(&[Ty::Object])
1016    .extract_error_mode(ExtractErrorMode::NotImplemented)
1017    .return_self();
1018const __ISUB__: SlotDef = SlotDef::new("Py_nb_inplace_subtract", "binaryfunc")
1019    .arguments(&[Ty::Object])
1020    .extract_error_mode(ExtractErrorMode::NotImplemented)
1021    .return_self();
1022const __IMUL__: SlotDef = SlotDef::new("Py_nb_inplace_multiply", "binaryfunc")
1023    .arguments(&[Ty::Object])
1024    .extract_error_mode(ExtractErrorMode::NotImplemented)
1025    .return_self();
1026const __IMATMUL__: SlotDef = SlotDef::new("Py_nb_inplace_matrix_multiply", "binaryfunc")
1027    .arguments(&[Ty::Object])
1028    .extract_error_mode(ExtractErrorMode::NotImplemented)
1029    .return_self();
1030const __ITRUEDIV__: SlotDef = SlotDef::new("Py_nb_inplace_true_divide", "binaryfunc")
1031    .arguments(&[Ty::Object])
1032    .extract_error_mode(ExtractErrorMode::NotImplemented)
1033    .return_self();
1034const __IFLOORDIV__: SlotDef = SlotDef::new("Py_nb_inplace_floor_divide", "binaryfunc")
1035    .arguments(&[Ty::Object])
1036    .extract_error_mode(ExtractErrorMode::NotImplemented)
1037    .return_self();
1038const __IMOD__: SlotDef = SlotDef::new("Py_nb_inplace_remainder", "binaryfunc")
1039    .arguments(&[Ty::Object])
1040    .extract_error_mode(ExtractErrorMode::NotImplemented)
1041    .return_self();
1042const __IPOW__: SlotDef = SlotDef::new("Py_nb_inplace_power", "ipowfunc")
1043    .arguments(&[Ty::Object, Ty::IPowModulo])
1044    .extract_error_mode(ExtractErrorMode::NotImplemented)
1045    .return_self();
1046const __ILSHIFT__: SlotDef = SlotDef::new("Py_nb_inplace_lshift", "binaryfunc")
1047    .arguments(&[Ty::Object])
1048    .extract_error_mode(ExtractErrorMode::NotImplemented)
1049    .return_self();
1050const __IRSHIFT__: SlotDef = SlotDef::new("Py_nb_inplace_rshift", "binaryfunc")
1051    .arguments(&[Ty::Object])
1052    .extract_error_mode(ExtractErrorMode::NotImplemented)
1053    .return_self();
1054const __IAND__: SlotDef = SlotDef::new("Py_nb_inplace_and", "binaryfunc")
1055    .arguments(&[Ty::Object])
1056    .extract_error_mode(ExtractErrorMode::NotImplemented)
1057    .return_self();
1058const __IXOR__: SlotDef = SlotDef::new("Py_nb_inplace_xor", "binaryfunc")
1059    .arguments(&[Ty::Object])
1060    .extract_error_mode(ExtractErrorMode::NotImplemented)
1061    .return_self();
1062const __IOR__: SlotDef = SlotDef::new("Py_nb_inplace_or", "binaryfunc")
1063    .arguments(&[Ty::Object])
1064    .extract_error_mode(ExtractErrorMode::NotImplemented)
1065    .return_self();
1066const __GETBUFFER__: SlotDef = SlotDef::new("Py_bf_getbuffer", "getbufferproc")
1067    .arguments(&[Ty::PyBuffer, Ty::Int])
1068    .ret_ty(Ty::Int)
1069    .require_unsafe();
1070const __RELEASEBUFFER__: SlotDef = SlotDef::new("Py_bf_releasebuffer", "releasebufferproc")
1071    .arguments(&[Ty::PyBuffer])
1072    .ret_ty(Ty::Void)
1073    .require_unsafe();
1074const __CLEAR__: SlotDef = SlotDef::new("Py_tp_clear", "inquiry")
1075    .arguments(&[])
1076    .ret_ty(Ty::Int);
1077
1078#[derive(Clone, Copy)]
1079enum Ty {
1080    Object,
1081    MaybeNullObject,
1082    NonNullObject,
1083    IPowModulo,
1084    CompareOp,
1085    Int,
1086    PyHashT,
1087    PySsizeT,
1088    Void,
1089    PyBuffer,
1090}
1091
1092impl Ty {
1093    fn ffi_type(self, ctx: &Ctx) -> TokenStream {
1094        let Ctx {
1095            pyo3_path,
1096            output_span,
1097        } = ctx;
1098        let pyo3_path = pyo3_path.to_tokens_spanned(*output_span);
1099        match self {
1100            Ty::Object | Ty::MaybeNullObject => quote! { *mut #pyo3_path::ffi::PyObject },
1101            Ty::NonNullObject => quote! { ::std::ptr::NonNull<#pyo3_path::ffi::PyObject> },
1102            Ty::IPowModulo => quote! { #pyo3_path::impl_::pymethods::IPowModulo },
1103            Ty::Int | Ty::CompareOp => quote! { ::std::os::raw::c_int },
1104            Ty::PyHashT => quote! { #pyo3_path::ffi::Py_hash_t },
1105            Ty::PySsizeT => quote! { #pyo3_path::ffi::Py_ssize_t },
1106            Ty::Void => quote! { () },
1107            Ty::PyBuffer => quote! { *mut #pyo3_path::ffi::Py_buffer },
1108        }
1109    }
1110
1111    fn extract(
1112        self,
1113        ident: &syn::Ident,
1114        arg: &FnArg<'_>,
1115        extract_error_mode: ExtractErrorMode,
1116        holders: &mut Holders,
1117        ctx: &Ctx,
1118    ) -> TokenStream {
1119        let Ctx { pyo3_path, .. } = ctx;
1120        match self {
1121            Ty::Object => extract_object(
1122                extract_error_mode,
1123                holders,
1124                arg,
1125                quote! { #ident },
1126                ctx
1127            ),
1128            Ty::MaybeNullObject => extract_object(
1129                extract_error_mode,
1130                holders,
1131                arg,
1132                quote! {
1133                    if #ident.is_null() {
1134                        #pyo3_path::ffi::Py_None()
1135                    } else {
1136                        #ident
1137                    }
1138                },
1139                ctx
1140            ),
1141            Ty::NonNullObject => extract_object(
1142                extract_error_mode,
1143                holders,
1144                arg,
1145                quote! { #ident.as_ptr() },
1146                ctx
1147            ),
1148            Ty::IPowModulo => extract_object(
1149                extract_error_mode,
1150                holders,
1151                arg,
1152                quote! { #ident.as_ptr() },
1153                ctx
1154            ),
1155            Ty::CompareOp => extract_error_mode.handle_error(
1156                quote! {
1157                    #pyo3_path::class::basic::CompareOp::from_raw(#ident)
1158                        .ok_or_else(|| #pyo3_path::exceptions::PyValueError::new_err("invalid comparison operator"))
1159                },
1160                ctx
1161            ),
1162            Ty::PySsizeT => {
1163                let ty = arg.ty();
1164                extract_error_mode.handle_error(
1165                    quote! {
1166                            ::std::convert::TryInto::<#ty>::try_into(#ident).map_err(|e| #pyo3_path::exceptions::PyValueError::new_err(e.to_string()))
1167                    },
1168                    ctx
1169                )
1170            }
1171            // Just pass other types through unmodified
1172            Ty::PyBuffer | Ty::Int | Ty::PyHashT | Ty::Void => quote! { #ident },
1173        }
1174    }
1175}
1176
1177fn extract_object(
1178    extract_error_mode: ExtractErrorMode,
1179    holders: &mut Holders,
1180    arg: &FnArg<'_>,
1181    source_ptr: TokenStream,
1182    ctx: &Ctx,
1183) -> TokenStream {
1184    let Ctx { pyo3_path, .. } = ctx;
1185    let name = arg.name().unraw().to_string();
1186
1187    let extract = if let Some(FromPyWithAttribute {
1188        kw,
1189        value: extractor,
1190    }) = arg.from_py_with()
1191    {
1192        let extractor = quote_spanned! { kw.span =>
1193            { let from_py_with: fn(_) -> _ = #extractor; from_py_with }
1194        };
1195
1196        quote! {
1197            #pyo3_path::impl_::extract_argument::from_py_with(
1198                unsafe { #pyo3_path::impl_::pymethods::BoundRef::ref_from_ptr(py, &#source_ptr).0 },
1199                #name,
1200                #extractor,
1201            )
1202        }
1203    } else {
1204        let holder = holders.push_holder(Span::call_site());
1205        let ty = arg.ty().clone().elide_lifetimes();
1206        quote! {{
1207            #[allow(unused_imports)]
1208            use #pyo3_path::impl_::pyclass::Probe as _;
1209            #pyo3_path::impl_::extract_argument::extract_argument::<
1210                _,
1211                { #pyo3_path::impl_::pyclass::IsOption::<#ty>::VALUE }
1212            >(
1213                unsafe { #pyo3_path::impl_::pymethods::BoundRef::ref_from_ptr(py, &#source_ptr).0 },
1214                &mut #holder,
1215                #name
1216            )
1217        }}
1218    };
1219
1220    let extracted = extract_error_mode.handle_error(extract, ctx);
1221    quote!(#extracted)
1222}
1223
1224enum ReturnMode {
1225    ReturnSelf,
1226    Conversion(TokenGenerator),
1227    SpecializedConversion(TokenGenerator, TokenGenerator),
1228}
1229
1230impl ReturnMode {
1231    fn return_call_output(&self, call: TokenStream, ctx: &Ctx) -> TokenStream {
1232        let Ctx { pyo3_path, .. } = ctx;
1233        match self {
1234            ReturnMode::Conversion(conversion) => {
1235                let conversion = TokenGeneratorCtx(*conversion, ctx);
1236                quote! {
1237                    let _result: #pyo3_path::PyResult<#conversion> = #pyo3_path::impl_::callback::convert(py, #call);
1238                    #pyo3_path::impl_::callback::convert(py, _result)
1239                }
1240            }
1241            ReturnMode::SpecializedConversion(traits, tag) => {
1242                let traits = TokenGeneratorCtx(*traits, ctx);
1243                let tag = TokenGeneratorCtx(*tag, ctx);
1244                quote! {
1245                    let _result = #call;
1246                    use #pyo3_path::impl_::pymethods::{#traits};
1247                    (&_result).#tag().convert(py, _result)
1248                }
1249            }
1250            ReturnMode::ReturnSelf => quote! {
1251                let _result: #pyo3_path::PyResult<()> = #pyo3_path::impl_::callback::convert(py, #call);
1252                _result?;
1253                #pyo3_path::ffi::Py_XINCREF(_raw_slf);
1254                ::std::result::Result::Ok(_raw_slf)
1255            },
1256        }
1257    }
1258}
1259
1260pub struct SlotDef {
1261    slot: StaticIdent,
1262    func_ty: StaticIdent,
1263    arguments: &'static [Ty],
1264    ret_ty: Ty,
1265    extract_error_mode: ExtractErrorMode,
1266    return_mode: Option<ReturnMode>,
1267    require_unsafe: bool,
1268}
1269
1270const NO_ARGUMENTS: &[Ty] = &[];
1271
1272impl SlotDef {
1273    const fn new(slot: &'static str, func_ty: &'static str) -> Self {
1274        SlotDef {
1275            slot: StaticIdent(slot),
1276            func_ty: StaticIdent(func_ty),
1277            arguments: NO_ARGUMENTS,
1278            ret_ty: Ty::Object,
1279            extract_error_mode: ExtractErrorMode::Raise,
1280            return_mode: None,
1281            require_unsafe: false,
1282        }
1283    }
1284
1285    const fn arguments(mut self, arguments: &'static [Ty]) -> Self {
1286        self.arguments = arguments;
1287        self
1288    }
1289
1290    const fn ret_ty(mut self, ret_ty: Ty) -> Self {
1291        self.ret_ty = ret_ty;
1292        self
1293    }
1294
1295    const fn return_conversion(mut self, return_conversion: TokenGenerator) -> Self {
1296        self.return_mode = Some(ReturnMode::Conversion(return_conversion));
1297        self
1298    }
1299
1300    const fn return_specialized_conversion(
1301        mut self,
1302        traits: TokenGenerator,
1303        tag: TokenGenerator,
1304    ) -> Self {
1305        self.return_mode = Some(ReturnMode::SpecializedConversion(traits, tag));
1306        self
1307    }
1308
1309    const fn extract_error_mode(mut self, extract_error_mode: ExtractErrorMode) -> Self {
1310        self.extract_error_mode = extract_error_mode;
1311        self
1312    }
1313
1314    const fn return_self(mut self) -> Self {
1315        self.return_mode = Some(ReturnMode::ReturnSelf);
1316        self
1317    }
1318
1319    const fn require_unsafe(mut self) -> Self {
1320        self.require_unsafe = true;
1321        self
1322    }
1323
1324    pub fn generate_type_slot(
1325        &self,
1326        cls: &syn::Type,
1327        spec: &FnSpec<'_>,
1328        method_name: &str,
1329        ctx: &Ctx,
1330    ) -> Result<MethodAndSlotDef> {
1331        let Ctx { pyo3_path, .. } = ctx;
1332        let SlotDef {
1333            slot,
1334            func_ty,
1335            arguments,
1336            extract_error_mode,
1337            ret_ty,
1338            return_mode,
1339            require_unsafe,
1340        } = self;
1341        if *require_unsafe {
1342            ensure_spanned!(
1343                spec.unsafety.is_some(),
1344                spec.name.span() => format!("`{}` must be `unsafe fn`", method_name)
1345            );
1346        }
1347        let arg_types: &Vec<_> = &arguments.iter().map(|arg| arg.ffi_type(ctx)).collect();
1348        let arg_idents: &Vec<_> = &(0..arguments.len())
1349            .map(|i| format_ident!("arg{}", i))
1350            .collect();
1351        let wrapper_ident = format_ident!("__pymethod_{}__", method_name);
1352        let ret_ty = ret_ty.ffi_type(ctx);
1353        let mut holders = Holders::new();
1354        let body = generate_method_body(
1355            cls,
1356            spec,
1357            arguments,
1358            *extract_error_mode,
1359            &mut holders,
1360            return_mode.as_ref(),
1361            ctx,
1362        )?;
1363        let name = spec.name;
1364        let holders = holders.init_holders(ctx);
1365        let associated_method = quote! {
1366            #[allow(non_snake_case)]
1367            unsafe fn #wrapper_ident(
1368                py: #pyo3_path::Python<'_>,
1369                _raw_slf: *mut #pyo3_path::ffi::PyObject,
1370                #(#arg_idents: #arg_types),*
1371            ) -> #pyo3_path::PyResult<#ret_ty> {
1372                let function = #cls::#name; // Shadow the method name to avoid #3017
1373                let _slf = _raw_slf;
1374                #holders
1375                #body
1376            }
1377        };
1378        let slot_def = quote! {{
1379            unsafe extern "C" fn trampoline(
1380                _slf: *mut #pyo3_path::ffi::PyObject,
1381                #(#arg_idents: #arg_types),*
1382            ) -> #ret_ty
1383            {
1384                #pyo3_path::impl_::trampoline:: #func_ty (
1385                    _slf,
1386                    #(#arg_idents,)*
1387                    #cls::#wrapper_ident
1388                )
1389            }
1390
1391            #pyo3_path::ffi::PyType_Slot {
1392                slot: #pyo3_path::ffi::#slot,
1393                pfunc: trampoline as #pyo3_path::ffi::#func_ty as _
1394            }
1395        }};
1396        Ok(MethodAndSlotDef {
1397            associated_method,
1398            slot_def,
1399        })
1400    }
1401}
1402
1403fn generate_method_body(
1404    cls: &syn::Type,
1405    spec: &FnSpec<'_>,
1406    arguments: &[Ty],
1407    extract_error_mode: ExtractErrorMode,
1408    holders: &mut Holders,
1409    return_mode: Option<&ReturnMode>,
1410    ctx: &Ctx,
1411) -> Result<TokenStream> {
1412    let Ctx { pyo3_path, .. } = ctx;
1413    let self_arg = spec
1414        .tp
1415        .self_arg(Some(cls), extract_error_mode, holders, ctx);
1416    let rust_name = spec.name;
1417    let args = extract_proto_arguments(spec, arguments, extract_error_mode, holders, ctx)?;
1418    let call = quote! { #cls::#rust_name(#self_arg #(#args),*) };
1419    Ok(if let Some(return_mode) = return_mode {
1420        return_mode.return_call_output(call, ctx)
1421    } else {
1422        quote! {
1423            let result = #call;
1424            #pyo3_path::impl_::callback::convert(py, result)
1425        }
1426    })
1427}
1428
1429struct SlotFragmentDef {
1430    fragment: &'static str,
1431    arguments: &'static [Ty],
1432    extract_error_mode: ExtractErrorMode,
1433    ret_ty: Ty,
1434}
1435
1436impl SlotFragmentDef {
1437    const fn new(fragment: &'static str, arguments: &'static [Ty]) -> Self {
1438        SlotFragmentDef {
1439            fragment,
1440            arguments,
1441            extract_error_mode: ExtractErrorMode::Raise,
1442            ret_ty: Ty::Void,
1443        }
1444    }
1445
1446    const fn extract_error_mode(mut self, extract_error_mode: ExtractErrorMode) -> Self {
1447        self.extract_error_mode = extract_error_mode;
1448        self
1449    }
1450
1451    const fn ret_ty(mut self, ret_ty: Ty) -> Self {
1452        self.ret_ty = ret_ty;
1453        self
1454    }
1455
1456    fn generate_pyproto_fragment(
1457        &self,
1458        cls: &syn::Type,
1459        spec: &FnSpec<'_>,
1460        ctx: &Ctx,
1461    ) -> Result<TokenStream> {
1462        let Ctx { pyo3_path, .. } = ctx;
1463        let SlotFragmentDef {
1464            fragment,
1465            arguments,
1466            extract_error_mode,
1467            ret_ty,
1468        } = self;
1469        let fragment_trait = format_ident!("PyClass{}SlotFragment", fragment);
1470        let method = syn::Ident::new(fragment, Span::call_site());
1471        let wrapper_ident = format_ident!("__pymethod_{}__", fragment);
1472        let arg_types: &Vec<_> = &arguments.iter().map(|arg| arg.ffi_type(ctx)).collect();
1473        let arg_idents: &Vec<_> = &(0..arguments.len())
1474            .map(|i| format_ident!("arg{}", i))
1475            .collect();
1476        let mut holders = Holders::new();
1477        let body = generate_method_body(
1478            cls,
1479            spec,
1480            arguments,
1481            *extract_error_mode,
1482            &mut holders,
1483            None,
1484            ctx,
1485        )?;
1486        let ret_ty = ret_ty.ffi_type(ctx);
1487        let holders = holders.init_holders(ctx);
1488        Ok(quote! {
1489            impl #cls {
1490                #[allow(non_snake_case)]
1491                unsafe fn #wrapper_ident(
1492                    py: #pyo3_path::Python,
1493                    _raw_slf: *mut #pyo3_path::ffi::PyObject,
1494                    #(#arg_idents: #arg_types),*
1495                ) -> #pyo3_path::PyResult<#ret_ty> {
1496                    let _slf = _raw_slf;
1497                    #holders
1498                    #body
1499                }
1500            }
1501
1502            impl #pyo3_path::impl_::pyclass::#fragment_trait<#cls> for #pyo3_path::impl_::pyclass::PyClassImplCollector<#cls> {
1503
1504                #[inline]
1505                unsafe fn #method(
1506                    self,
1507                    py: #pyo3_path::Python,
1508                    _raw_slf: *mut #pyo3_path::ffi::PyObject,
1509                    #(#arg_idents: #arg_types),*
1510                ) -> #pyo3_path::PyResult<#ret_ty> {
1511                    #cls::#wrapper_ident(py, _raw_slf, #(#arg_idents),*)
1512                }
1513            }
1514        })
1515    }
1516}
1517
1518const __GETATTRIBUTE__: SlotFragmentDef =
1519    SlotFragmentDef::new("__getattribute__", &[Ty::Object]).ret_ty(Ty::Object);
1520const __GETATTR__: SlotFragmentDef =
1521    SlotFragmentDef::new("__getattr__", &[Ty::Object]).ret_ty(Ty::Object);
1522const __SETATTR__: SlotFragmentDef =
1523    SlotFragmentDef::new("__setattr__", &[Ty::Object, Ty::NonNullObject]);
1524const __DELATTR__: SlotFragmentDef = SlotFragmentDef::new("__delattr__", &[Ty::Object]);
1525const __SET__: SlotFragmentDef = SlotFragmentDef::new("__set__", &[Ty::Object, Ty::NonNullObject]);
1526const __DELETE__: SlotFragmentDef = SlotFragmentDef::new("__delete__", &[Ty::Object]);
1527const __SETITEM__: SlotFragmentDef =
1528    SlotFragmentDef::new("__setitem__", &[Ty::Object, Ty::NonNullObject]);
1529const __DELITEM__: SlotFragmentDef = SlotFragmentDef::new("__delitem__", &[Ty::Object]);
1530
1531macro_rules! binary_num_slot_fragment_def {
1532    ($ident:ident, $name:literal) => {
1533        const $ident: SlotFragmentDef = SlotFragmentDef::new($name, &[Ty::Object])
1534            .extract_error_mode(ExtractErrorMode::NotImplemented)
1535            .ret_ty(Ty::Object);
1536    };
1537}
1538
1539binary_num_slot_fragment_def!(__ADD__, "__add__");
1540binary_num_slot_fragment_def!(__RADD__, "__radd__");
1541binary_num_slot_fragment_def!(__SUB__, "__sub__");
1542binary_num_slot_fragment_def!(__RSUB__, "__rsub__");
1543binary_num_slot_fragment_def!(__MUL__, "__mul__");
1544binary_num_slot_fragment_def!(__RMUL__, "__rmul__");
1545binary_num_slot_fragment_def!(__MATMUL__, "__matmul__");
1546binary_num_slot_fragment_def!(__RMATMUL__, "__rmatmul__");
1547binary_num_slot_fragment_def!(__FLOORDIV__, "__floordiv__");
1548binary_num_slot_fragment_def!(__RFLOORDIV__, "__rfloordiv__");
1549binary_num_slot_fragment_def!(__TRUEDIV__, "__truediv__");
1550binary_num_slot_fragment_def!(__RTRUEDIV__, "__rtruediv__");
1551binary_num_slot_fragment_def!(__DIVMOD__, "__divmod__");
1552binary_num_slot_fragment_def!(__RDIVMOD__, "__rdivmod__");
1553binary_num_slot_fragment_def!(__MOD__, "__mod__");
1554binary_num_slot_fragment_def!(__RMOD__, "__rmod__");
1555binary_num_slot_fragment_def!(__LSHIFT__, "__lshift__");
1556binary_num_slot_fragment_def!(__RLSHIFT__, "__rlshift__");
1557binary_num_slot_fragment_def!(__RSHIFT__, "__rshift__");
1558binary_num_slot_fragment_def!(__RRSHIFT__, "__rrshift__");
1559binary_num_slot_fragment_def!(__AND__, "__and__");
1560binary_num_slot_fragment_def!(__RAND__, "__rand__");
1561binary_num_slot_fragment_def!(__XOR__, "__xor__");
1562binary_num_slot_fragment_def!(__RXOR__, "__rxor__");
1563binary_num_slot_fragment_def!(__OR__, "__or__");
1564binary_num_slot_fragment_def!(__ROR__, "__ror__");
1565
1566const __POW__: SlotFragmentDef = SlotFragmentDef::new("__pow__", &[Ty::Object, Ty::Object])
1567    .extract_error_mode(ExtractErrorMode::NotImplemented)
1568    .ret_ty(Ty::Object);
1569const __RPOW__: SlotFragmentDef = SlotFragmentDef::new("__rpow__", &[Ty::Object, Ty::Object])
1570    .extract_error_mode(ExtractErrorMode::NotImplemented)
1571    .ret_ty(Ty::Object);
1572
1573const __LT__: SlotFragmentDef = SlotFragmentDef::new("__lt__", &[Ty::Object])
1574    .extract_error_mode(ExtractErrorMode::NotImplemented)
1575    .ret_ty(Ty::Object);
1576const __LE__: SlotFragmentDef = SlotFragmentDef::new("__le__", &[Ty::Object])
1577    .extract_error_mode(ExtractErrorMode::NotImplemented)
1578    .ret_ty(Ty::Object);
1579const __EQ__: SlotFragmentDef = SlotFragmentDef::new("__eq__", &[Ty::Object])
1580    .extract_error_mode(ExtractErrorMode::NotImplemented)
1581    .ret_ty(Ty::Object);
1582const __NE__: SlotFragmentDef = SlotFragmentDef::new("__ne__", &[Ty::Object])
1583    .extract_error_mode(ExtractErrorMode::NotImplemented)
1584    .ret_ty(Ty::Object);
1585const __GT__: SlotFragmentDef = SlotFragmentDef::new("__gt__", &[Ty::Object])
1586    .extract_error_mode(ExtractErrorMode::NotImplemented)
1587    .ret_ty(Ty::Object);
1588const __GE__: SlotFragmentDef = SlotFragmentDef::new("__ge__", &[Ty::Object])
1589    .extract_error_mode(ExtractErrorMode::NotImplemented)
1590    .ret_ty(Ty::Object);
1591
1592fn extract_proto_arguments(
1593    spec: &FnSpec<'_>,
1594    proto_args: &[Ty],
1595    extract_error_mode: ExtractErrorMode,
1596    holders: &mut Holders,
1597    ctx: &Ctx,
1598) -> Result<Vec<TokenStream>> {
1599    let mut args = Vec::with_capacity(spec.signature.arguments.len());
1600    let mut non_python_args = 0;
1601
1602    for arg in &spec.signature.arguments {
1603        if let FnArg::Py(..) = arg {
1604            args.push(quote! { py });
1605        } else {
1606            let ident = syn::Ident::new(&format!("arg{}", non_python_args), Span::call_site());
1607            let conversions = proto_args.get(non_python_args)
1608                .ok_or_else(|| err_spanned!(arg.ty().span() => format!("Expected at most {} non-python arguments", proto_args.len())))?
1609                .extract(&ident, arg, extract_error_mode, holders, ctx);
1610            non_python_args += 1;
1611            args.push(conversions);
1612        }
1613    }
1614
1615    if non_python_args != proto_args.len() {
1616        bail_spanned!(spec.name.span() => format!("Expected {} arguments, got {}", proto_args.len(), non_python_args));
1617    }
1618    Ok(args)
1619}
1620
1621struct StaticIdent(&'static str);
1622
1623impl ToTokens for StaticIdent {
1624    fn to_tokens(&self, tokens: &mut TokenStream) {
1625        syn::Ident::new(self.0, Span::call_site()).to_tokens(tokens)
1626    }
1627}
1628
1629#[derive(Clone, Copy)]
1630struct TokenGenerator(fn(&Ctx) -> TokenStream);
1631
1632struct TokenGeneratorCtx<'ctx>(TokenGenerator, &'ctx Ctx);
1633
1634impl ToTokens for TokenGeneratorCtx<'_> {
1635    fn to_tokens(&self, tokens: &mut TokenStream) {
1636        let Self(TokenGenerator(gen), ctx) = self;
1637        (gen)(ctx).to_tokens(tokens)
1638    }
1639}
pyo3_macros_backend/pymethod.rs

pyo3_macros_backend/
pymethod.rs
