pyo3_ffi/
methodobject.rs

1#[cfg(not(RustPython))]
2use crate::Py_IS_TYPE;
3#[cfg(not(RustPython))]
4use crate::PyObject_TypeCheck;
5use crate::object::{PyObject, PyTypeObject};
6use core::ffi::{c_char, c_int, c_void};
7use core::{mem, ptr};
8
9#[cfg(all(not(Py_LIMITED_API), not(GraalPy)))]
10pub struct PyCFunctionObject {
11    pub ob_base: PyObject,
12    pub m_ml: *mut PyMethodDef,
13    pub m_self: *mut PyObject,
14    pub m_module: *mut PyObject,
15    pub m_weakreflist: *mut PyObject,
16    #[cfg(not(PyPy))]
17    pub vectorcall: Option<crate::vectorcallfunc>,
18}
19
20extern_libpython! {
21    #[cfg(not(RustPython))]
22    #[cfg_attr(all(PyPy, not(Py_3_12)), link_name = "PyPyCFunction_Type")]
23    pub static mut PyCFunction_Type: PyTypeObject;
24
25    #[cfg(RustPython)]
26    pub fn PyCFunction_CheckExact(op: *mut PyObject) -> c_int;
27    #[cfg(RustPython)]
28    pub fn PyCFunction_Check(op: *mut PyObject) -> c_int;
29}
30
31#[cfg(not(RustPython))]
32#[inline]
33pub unsafe fn PyCFunction_CheckExact(op: *mut PyObject) -> c_int {
34    Py_IS_TYPE(op, &raw mut PyCFunction_Type)
35}
36
37#[cfg(not(RustPython))]
38#[inline]
39pub unsafe fn PyCFunction_Check(op: *mut PyObject) -> c_int {
40    PyObject_TypeCheck(op, &raw mut PyCFunction_Type)
41}
42
43pub type PyCFunction =
44    unsafe extern "C" fn(slf: *mut PyObject, args: *mut PyObject) -> *mut PyObject;
45
46#[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
47pub type PyCFunctionFast = unsafe extern "C" fn(
48    slf: *mut PyObject,
49    args: *mut *mut PyObject,
50    nargs: crate::pyport::Py_ssize_t,
51) -> *mut PyObject;
52
53#[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
54#[deprecated(note = "renamed to `PyCFunctionFast`")]
55pub type _PyCFunctionFast = PyCFunctionFast;
56
57pub type PyCFunctionWithKeywords = unsafe extern "C" fn(
58    slf: *mut PyObject,
59    args: *mut PyObject,
60    kwds: *mut PyObject,
61) -> *mut PyObject;
62
63#[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
64pub type PyCFunctionFastWithKeywords = unsafe extern "C" fn(
65    slf: *mut PyObject,
66    args: *const *mut PyObject,
67    nargs: crate::pyport::Py_ssize_t,
68    kwnames: *mut PyObject,
69) -> *mut PyObject;
70
71#[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
72#[deprecated(note = "renamed to `PyCFunctionFastWithKeywords`")]
73pub type _PyCFunctionFastWithKeywords = PyCFunctionFastWithKeywords;
74
75#[cfg(not(Py_LIMITED_API))]
76pub type PyCMethod = unsafe extern "C" fn(
77    slf: *mut PyObject,
78    defining_class: *mut PyTypeObject,
79    args: *const *mut PyObject,
80    nargs: crate::pyport::Py_ssize_t,
81    kwnames: *mut PyObject,
82) -> *mut PyObject;
83
84extern_libpython! {
85    #[cfg_attr(all(PyPy, not(Py_3_12)), link_name = "PyPyCFunction_GetFunction")]
86    pub fn PyCFunction_GetFunction(f: *mut PyObject) -> Option<PyCFunction>;
87    #[cfg(any(not(PyPy), Py_3_12))]
88    pub fn PyCFunction_GetSelf(f: *mut PyObject) -> *mut PyObject;
89    #[cfg(any(not(PyPy), Py_3_12))]
90    pub fn PyCFunction_GetFlags(f: *mut PyObject) -> c_int;
91    #[cfg(not(Py_3_13))]
92    #[deprecated(note = "Python 3.9")]
93    #[cfg_attr(all(PyPy, not(Py_3_12)), link_name = "PyPyCFunction_Call")]
94    pub fn PyCFunction_Call(
95        f: *mut PyObject,
96        args: *mut PyObject,
97        kwds: *mut PyObject,
98    ) -> *mut PyObject;
99}
100
101/// Represents the [PyMethodDef](https://docs.python.org/3/c-api/structures.html#c.PyMethodDef)
102/// structure.
103///
104/// Note that CPython may leave fields uninitialized. You must ensure that
105/// `ml_name` != NULL before dereferencing or reading other fields.
106#[repr(C)]
107#[derive(Copy, Clone, PartialEq, Eq)]
108pub struct PyMethodDef {
109    pub ml_name: *const c_char,
110    pub ml_meth: PyMethodDefPointer,
111    pub ml_flags: c_int,
112    pub ml_doc: *const c_char,
113}
114
115impl PyMethodDef {
116    pub const fn zeroed() -> PyMethodDef {
117        PyMethodDef {
118            ml_name: ptr::null(),
119            ml_meth: PyMethodDefPointer {
120                Void: ptr::null_mut(),
121            },
122            ml_flags: 0,
123            ml_doc: ptr::null(),
124        }
125    }
126}
127
128impl Default for PyMethodDef {
129    fn default() -> PyMethodDef {
130        PyMethodDef {
131            ml_name: ptr::null(),
132            ml_meth: PyMethodDefPointer {
133                Void: ptr::null_mut(),
134            },
135            ml_flags: 0,
136            ml_doc: ptr::null(),
137        }
138    }
139}
140
141/// Function types used to implement Python callables.
142///
143/// This function pointer must be accompanied by the correct [ml_flags](PyMethodDef::ml_flags),
144/// otherwise the behavior is undefined.
145///
146/// See the [Python C API documentation][1] for more information.
147///
148/// [1]: https://docs.python.org/3/c-api/structures.html#implementing-functions-and-methods
149#[repr(C)]
150#[derive(Copy, Clone, Eq)]
151pub union PyMethodDefPointer {
152    /// This variant corresponds with [`METH_VARARGS`] *or* [`METH_NOARGS`] *or* [`METH_O`].
153    pub PyCFunction: PyCFunction,
154
155    /// This variant corresponds with [`METH_VARARGS`] | [`METH_KEYWORDS`].
156    pub PyCFunctionWithKeywords: PyCFunctionWithKeywords,
157
158    /// This variant corresponds with [`METH_FASTCALL`].
159    #[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
160    #[deprecated(note = "renamed to `PyCFunctionFast`")]
161    pub _PyCFunctionFast: PyCFunctionFast,
162
163    /// This variant corresponds with [`METH_FASTCALL`].
164    #[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
165    pub PyCFunctionFast: PyCFunctionFast,
166
167    /// This variant corresponds with [`METH_FASTCALL`] | [`METH_KEYWORDS`].
168    #[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
169    #[deprecated(note = "renamed to `PyCFunctionFastWithKeywords`")]
170    pub _PyCFunctionFastWithKeywords: PyCFunctionFastWithKeywords,
171
172    /// This variant corresponds with [`METH_FASTCALL`] | [`METH_KEYWORDS`].
173    #[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
174    pub PyCFunctionFastWithKeywords: PyCFunctionFastWithKeywords,
175
176    /// This variant corresponds with [`METH_METHOD`] | [`METH_FASTCALL`] | [`METH_KEYWORDS`].
177    #[cfg(not(Py_LIMITED_API))]
178    pub PyCMethod: PyCMethod,
179
180    Void: *mut c_void,
181}
182
183impl PyMethodDefPointer {
184    pub fn as_ptr(&self) -> *mut c_void {
185        // SAFETY: self is pointer sized
186        unsafe { self.Void }
187    }
188
189    pub fn is_null(&self) -> bool {
190        self.as_ptr().is_null()
191    }
192
193    pub const fn zeroed() -> PyMethodDefPointer {
194        PyMethodDefPointer {
195            Void: ptr::null_mut(),
196        }
197    }
198}
199
200impl PartialEq for PyMethodDefPointer {
201    fn eq(&self, other: &Self) -> bool {
202        self.as_ptr() == other.as_ptr()
203    }
204}
205
206impl core::fmt::Pointer for PyMethodDefPointer {
207    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
208        let ptr = self.as_ptr();
209        core::fmt::Pointer::fmt(&ptr, f)
210    }
211}
212
213const _: () =
214    assert!(mem::size_of::<PyMethodDefPointer>() == mem::size_of::<Option<extern "C" fn()>>());
215
216#[inline]
217pub unsafe fn PyCFunction_New(ml: *mut PyMethodDef, slf: *mut PyObject) -> *mut PyObject {
218    PyCFunction_NewEx(ml, slf, core::ptr::null_mut())
219}
220
221#[inline]
222pub unsafe fn PyCFunction_NewEx(
223    ml: *mut PyMethodDef,
224    slf: *mut PyObject,
225    module: *mut PyObject,
226) -> *mut PyObject {
227    PyCMethod_New(ml, slf, module, core::ptr::null_mut())
228}
229
230extern_libpython! {
231    #[cfg_attr(all(PyPy, not(Py_3_12)), link_name = "PyPyCMethod_New")]
232    pub fn PyCMethod_New(
233        ml: *mut PyMethodDef,
234        slf: *mut PyObject,
235        module: *mut PyObject,
236        cls: *mut PyTypeObject,
237    ) -> *mut PyObject;
238}
239
240/* Flag passed to newmethodobject */
241pub const METH_VARARGS: c_int = 0x0001;
242pub const METH_KEYWORDS: c_int = 0x0002;
243/* METH_NOARGS and METH_O must not be combined with the flags above. */
244pub const METH_NOARGS: c_int = 0x0004;
245pub const METH_O: c_int = 0x0008;
246
247/* METH_CLASS and METH_STATIC are a little different; these control
248the construction of methods for a class.  These cannot be used for
249functions in modules. */
250pub const METH_CLASS: c_int = 0x0010;
251pub const METH_STATIC: c_int = 0x0020;
252
253/* METH_COEXIST allows a method to be entered eventhough a slot has
254already filled the entry.  When defined, the flag allows a separate
255method, "__contains__" for example, to coexist with a defined
256slot like sq_contains. */
257
258pub const METH_COEXIST: c_int = 0x0040;
259
260/* METH_FASTCALL indicates the PEP 590 Vectorcall calling format. It may
261be specified alone or with METH_KEYWORDS. */
262#[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
263pub const METH_FASTCALL: c_int = 0x0080;
264
265// skipped METH_STACKLESS
266
267#[cfg(not(Py_LIMITED_API))]
268pub const METH_METHOD: c_int = 0x0200;
pyo3_ffi/methodobject.rs

pyo3_ffi/
methodobject.rs
