pyo3/types/
function.rs

1use crate::ffi_ptr_ext::FfiPtrExt;
2use crate::py_result_ext::PyResultExt;
3use crate::types::capsule::PyCapsuleMethods;
4use crate::types::module::PyModuleMethods;
5use crate::{
6    ffi,
7    impl_::pymethods::{self, PyMethodDef},
8    types::{PyCapsule, PyDict, PyModule, PyString, PyTuple},
9};
10use crate::{Bound, Py, PyAny, PyResult, Python};
11use std::cell::UnsafeCell;
12use std::ffi::CStr;
13
14/// Represents a builtin Python function object.
15///
16/// Values of this type are accessed via PyO3's smart pointers, e.g. as
17/// [`Py<PyCFunction>`][crate::Py] or [`Bound<'py, PyCFunction>`][Bound].
18#[repr(transparent)]
19pub struct PyCFunction(PyAny);
20
21pyobject_native_type_core!(PyCFunction, pyobject_native_static_type_object!(ffi::PyCFunction_Type), #checkfunction=ffi::PyCFunction_Check);
22
23impl PyCFunction {
24    /// Create a new built-in function with keywords (*args and/or **kwargs).
25    ///
26    /// To create `name` and `doc` static strings on Rust versions older than 1.77 (which added c"" literals),
27    /// use the [`c_str!`](crate::ffi::c_str) macro.
28    pub fn new_with_keywords<'py>(
29        py: Python<'py>,
30        fun: ffi::PyCFunctionWithKeywords,
31        name: &'static CStr,
32        doc: &'static CStr,
33        module: Option<&Bound<'py, PyModule>>,
34    ) -> PyResult<Bound<'py, Self>> {
35        Self::internal_new(
36            py,
37            &PyMethodDef::cfunction_with_keywords(name, fun, doc),
38            module,
39        )
40    }
41
42    /// Create a new built-in function which takes no arguments.
43    ///
44    /// To create `name` and `doc` static strings on Rust versions older than 1.77 (which added c"" literals),
45    /// use the [`c_str!`](crate::ffi::c_str) macro.
46    pub fn new<'py>(
47        py: Python<'py>,
48        fun: ffi::PyCFunction,
49        name: &'static CStr,
50        doc: &'static CStr,
51        module: Option<&Bound<'py, PyModule>>,
52    ) -> PyResult<Bound<'py, Self>> {
53        Self::internal_new(py, &PyMethodDef::noargs(name, fun, doc), module)
54    }
55
56    /// Create a new function from a closure.
57    ///
58    /// # Examples
59    ///
60    /// ```
61    /// # use pyo3::prelude::*;
62    /// # use pyo3::{py_run, types::{PyCFunction, PyDict, PyTuple}};
63    ///
64    /// Python::with_gil(|py| {
65    ///     let add_one = |args: &Bound<'_, PyTuple>, _kwargs: Option<&Bound<'_, PyDict>>| -> PyResult<_> {
66    ///         let i = args.extract::<(i64,)>()?.0;
67    ///         Ok(i+1)
68    ///     };
69    ///     let add_one = PyCFunction::new_closure(py, None, None, add_one).unwrap();
70    ///     py_run!(py, add_one, "assert add_one(42) == 43");
71    /// });
72    /// ```
73    pub fn new_closure<'py, F, R>(
74        py: Python<'py>,
75        name: Option<&'static CStr>,
76        doc: Option<&'static CStr>,
77        closure: F,
78    ) -> PyResult<Bound<'py, Self>>
79    where
80        F: Fn(&Bound<'_, PyTuple>, Option<&Bound<'_, PyDict>>) -> R + Send + 'static,
81        for<'p> R: crate::impl_::callback::IntoPyCallbackOutput<'p, *mut ffi::PyObject>,
82    {
83        let name = name.unwrap_or(ffi::c_str!("pyo3-closure"));
84        let doc = doc.unwrap_or(ffi::c_str!(""));
85        let method_def =
86            pymethods::PyMethodDef::cfunction_with_keywords(name, run_closure::<F, R>, doc);
87        let def = method_def.as_method_def();
88
89        let capsule = PyCapsule::new(
90            py,
91            ClosureDestructor::<F> {
92                closure,
93                def: UnsafeCell::new(def),
94            },
95            Some(CLOSURE_CAPSULE_NAME.to_owned()),
96        )?;
97
98        // Safety: just created the capsule with type ClosureDestructor<F> above
99        let data = unsafe { capsule.reference::<ClosureDestructor<F>>() };
100
101        unsafe {
102            ffi::PyCFunction_NewEx(data.def.get(), capsule.as_ptr(), std::ptr::null_mut())
103                .assume_owned_or_err(py)
104                .downcast_into_unchecked()
105        }
106    }
107
108    #[doc(hidden)]
109    pub fn internal_new<'py>(
110        py: Python<'py>,
111        method_def: &PyMethodDef,
112        module: Option<&Bound<'py, PyModule>>,
113    ) -> PyResult<Bound<'py, Self>> {
114        let (mod_ptr, module_name): (_, Option<Py<PyString>>) = if let Some(m) = module {
115            let mod_ptr = m.as_ptr();
116            (mod_ptr, Some(m.name()?.unbind()))
117        } else {
118            (std::ptr::null_mut(), None)
119        };
120        let def = method_def.as_method_def();
121
122        // FIXME: stop leaking the def
123        let def = Box::into_raw(Box::new(def));
124
125        let module_name_ptr = module_name
126            .as_ref()
127            .map_or(std::ptr::null_mut(), Py::as_ptr);
128
129        unsafe {
130            ffi::PyCFunction_NewEx(def, mod_ptr, module_name_ptr)
131                .assume_owned_or_err(py)
132                .downcast_into_unchecked()
133        }
134    }
135}
136
137static CLOSURE_CAPSULE_NAME: &CStr = ffi::c_str!("pyo3-closure");
138
139unsafe extern "C" fn run_closure<F, R>(
140    capsule_ptr: *mut ffi::PyObject,
141    args: *mut ffi::PyObject,
142    kwargs: *mut ffi::PyObject,
143) -> *mut ffi::PyObject
144where
145    F: Fn(&Bound<'_, PyTuple>, Option<&Bound<'_, PyDict>>) -> R + Send + 'static,
146    for<'py> R: crate::impl_::callback::IntoPyCallbackOutput<'py, *mut ffi::PyObject>,
147{
148    use crate::types::any::PyAnyMethods;
149
150    unsafe {
151        crate::impl_::trampoline::cfunction_with_keywords(
152            capsule_ptr,
153            args,
154            kwargs,
155            |py, capsule_ptr, args, kwargs| {
156                let boxed_fn: &ClosureDestructor<F> =
157                    &*(ffi::PyCapsule_GetPointer(capsule_ptr, CLOSURE_CAPSULE_NAME.as_ptr())
158                        as *mut ClosureDestructor<F>);
159                let args = Bound::ref_from_ptr(py, &args).downcast_unchecked::<PyTuple>();
160                let kwargs = Bound::ref_from_ptr_or_opt(py, &kwargs)
161                    .as_ref()
162                    .map(|b| b.downcast_unchecked::<PyDict>());
163                let result = (boxed_fn.closure)(args, kwargs);
164                crate::impl_::callback::convert(py, result)
165            },
166        )
167    }
168}
169
170struct ClosureDestructor<F> {
171    closure: F,
172    // Wrapped in UnsafeCell because Python C-API wants a *mut pointer
173    // to this member.
174    def: UnsafeCell<ffi::PyMethodDef>,
175}
176
177// Safety: F is send and none of the fields are ever mutated
178unsafe impl<F: Send> Send for ClosureDestructor<F> {}
179
180/// Represents a Python function object.
181///
182/// Values of this type are accessed via PyO3's smart pointers, e.g. as
183/// [`Py<PyFunction>`][crate::Py] or [`Bound<'py, PyFunction>`][Bound].
184#[repr(transparent)]
185#[cfg(not(Py_LIMITED_API))]
186pub struct PyFunction(PyAny);
187
188#[cfg(not(Py_LIMITED_API))]
189pyobject_native_type_core!(PyFunction, pyobject_native_static_type_object!(ffi::PyFunction_Type), #checkfunction=ffi::PyFunction_Check);
pyo3/types/function.rs

pyo3/types/
function.rs
