pyo3_ffi/
methodobject.rs

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

pyo3_ffi/
methodobject.rs
