add PyCode::compile to create executable code objects (#5217)

Icxolu · web-flow · commit 2dc118e588ed · 2025-07-04T19:34:31.000Z
diff --git a/newsfragments/5217.added.md b/newsfragments/5217.added.md
@@ -0,0 +1 @@
+add `PyCode::compile` and `PyCodeMethods::run` to create and execute code objects
diff --git a/pyo3-ffi/src/cpython/code.rs b/pyo3-ffi/src/cpython/code.rs
@@ -4,7 +4,7 @@ use crate::pyport::Py_ssize_t;
 #[cfg(not(GraalPy))]
 use std::os::raw::c_char;
 use std::os::raw::{c_int, c_void};
-#[cfg(not(any(PyPy, GraalPy)))]
+#[cfg(not(PyPy))]
 use std::ptr::addr_of_mut;
 
 // skipped private _PY_MONITORING_LOCAL_EVENTS
@@ -71,14 +71,14 @@ pub const CO_FUTURE_GENERATOR_STOP: c_int = 0x8_0000;
 
 pub const CO_MAXBLOCKS: usize = 20;
 
-#[cfg(not(any(PyPy, GraalPy)))]
+#[cfg(not(PyPy))]
 #[cfg_attr(windows, link(name = "pythonXY"))]
 extern "C" {
     pub static mut PyCode_Type: PyTypeObject;
 }
 
 #[inline]
-#[cfg(not(any(PyPy, GraalPy)))]
+#[cfg(not(PyPy))]
 pub unsafe fn PyCode_Check(op: *mut PyObject) -> c_int {
     (Py_TYPE(op) == addr_of_mut!(PyCode_Type)) as c_int
 }
diff --git a/src/marker.rs b/src/marker.rs
@@ -117,21 +117,18 @@
 //! [`Rc`]: std::rc::Rc
 //! [`Py`]: crate::Py
 use crate::conversion::IntoPyObject;
-use crate::err::PyErr;
 use crate::err::{self, PyResult};
-use crate::ffi_ptr_ext::FfiPtrExt;
 use crate::gil::{GILGuard, SuspendGIL};
 use crate::impl_::not_send::NotSend;
-use crate::py_result_ext::PyResultExt;
 use crate::types::any::PyAnyMethods;
 use crate::types::{
-    PyAny, PyDict, PyEllipsis, PyModule, PyNone, PyNotImplemented, PyString, PyType,
+    PyAny, PyCode, PyCodeMethods, PyDict, PyEllipsis, PyModule, PyNone, PyNotImplemented, PyString,
+    PyType,
 };
 use crate::version::PythonVersionInfo;
 use crate::{ffi, Bound, PyObject, PyTypeInfo};
 use std::ffi::CStr;
 use std::marker::PhantomData;
-use std::os::raw::c_int;
 
 /// Types that are safe to access while the GIL is not held.
 ///
@@ -567,7 +564,13 @@ impl<'py> Python<'py> {
         globals: Option<&Bound<'py, PyDict>>,
         locals: Option<&Bound<'py, PyDict>>,
     ) -> PyResult<Bound<'py, PyAny>> {
-        self.run_code(code, ffi::Py_eval_input, globals, locals)
+        let code = PyCode::compile(
+            self,
+            code,
+            ffi::c_str!("<string>"),
+            crate::types::PyCodeInput::Eval,
+        )?;
+        code.run(globals, locals)
     }
 
     /// Executes one or more Python statements in the given context.
@@ -611,79 +614,17 @@ impl<'py> Python<'py> {
         globals: Option<&Bound<'py, PyDict>>,
         locals: Option<&Bound<'py, PyDict>>,
     ) -> PyResult<()> {
-        let res = self.run_code(code, ffi::Py_file_input, globals, locals);
-        res.map(|obj| {
+        let code = PyCode::compile(
+            self,
+            code,
+            ffi::c_str!("<string>"),
+            crate::types::PyCodeInput::File,
+        )?;
+        code.run(globals, locals).map(|obj| {
             debug_assert!(obj.is_none());
         })
     }
 
-    /// Runs code in the given context.
-    ///
-    /// `start` indicates the type of input expected: one of `Py_single_input`,
-    /// `Py_file_input`, or `Py_eval_input`.
-    ///
-    /// If `globals` is `None`, it defaults to Python module `__main__`.
-    /// If `locals` is `None`, it defaults to the value of `globals`.
-    fn run_code(
-        self,
-        code: &CStr,
-        start: c_int,
-        globals: Option<&Bound<'py, PyDict>>,
-        locals: Option<&Bound<'py, PyDict>>,
-    ) -> PyResult<Bound<'py, PyAny>> {
-        let mptr = unsafe {
-            ffi::compat::PyImport_AddModuleRef(ffi::c_str!("__main__").as_ptr())
-                .assume_owned_or_err(self)?
-        };
-        let attr = mptr.getattr(crate::intern!(self, "__dict__"))?;
-        let globals = match globals {
-            Some(globals) => globals,
-            None => attr.downcast::<PyDict>()?,
-        };
-        let locals = locals.unwrap_or(globals);
-
-        // If `globals` don't provide `__builtins__`, most of the code will fail if Python
-        // version is <3.10. That's probably not what user intended, so insert `__builtins__`
-        // for them.
-        //
-        // See also:
-        // - https://github.com/python/cpython/pull/24564 (the same fix in CPython 3.10)
-        // - https://github.com/PyO3/pyo3/issues/3370
-        let builtins_s = crate::intern!(self, "__builtins__");
-        let has_builtins = globals.contains(builtins_s)?;
-        if !has_builtins {
-            crate::sync::with_critical_section(globals, || {
-                // check if another thread set __builtins__ while this thread was blocked on the critical section
-                let has_builtins = globals.contains(builtins_s)?;
-                if !has_builtins {
-                    // Inherit current builtins.
-                    let builtins = unsafe { ffi::PyEval_GetBuiltins() };
-
-                    // `PyDict_SetItem` doesn't take ownership of `builtins`, but `PyEval_GetBuiltins`
-                    // seems to return a borrowed reference, so no leak here.
-                    if unsafe {
-                        ffi::PyDict_SetItem(globals.as_ptr(), builtins_s.as_ptr(), builtins)
-                    } == -1
-                    {
-                        return Err(PyErr::fetch(self));
-                    }
-                }
-                Ok(())
-            })?;
-        }
-
-        let code_obj = unsafe {
-            ffi::Py_CompileString(code.as_ptr(), ffi::c_str!("<string>").as_ptr(), start)
-                .assume_owned_or_err(self)?
-        };
-
-        unsafe {
-            ffi::PyEval_EvalCode(code_obj.as_ptr(), globals.as_ptr(), locals.as_ptr())
-                .assume_owned_or_err(self)
-                .downcast_into_unchecked()
-        }
-    }
-
     /// Gets the Python type object for type `T`.
     #[inline]
     pub fn get_type<T>(self) -> Bound<'py, PyType>
@@ -766,7 +707,7 @@ impl<'py> Python<'py> {
     /// Lets the Python interpreter check and handle any pending signals. This will invoke the
     /// corresponding signal handlers registered in Python (if any).
     ///
-    /// Returns `Err(`[`PyErr`]`)` if any signal handler raises an exception.
+    /// Returns `Err(`[`PyErr`](crate::PyErr)`)` if any signal handler raises an exception.
     ///
     /// These signals include `SIGINT` (normally raised by CTRL + C), which by default raises
     /// `KeyboardInterrupt`. For this reason it is good practice to call this function regularly
@@ -939,6 +880,8 @@ mod tests {
     #[test]
     #[cfg(not(Py_LIMITED_API))]
     fn test_acquire_gil() {
+        use std::ffi::c_int;
+
         const GIL_NOT_HELD: c_int = 0;
         const GIL_HELD: c_int = 1;
 
diff --git a/src/types/code.rs b/src/types/code.rs
@@ -1,5 +1,9 @@
-use crate::ffi;
-use crate::PyAny;
+use super::PyAnyMethods as _;
+use super::PyDict;
+use crate::ffi_ptr_ext::FfiPtrExt;
+use crate::py_result_ext::PyResultExt;
+use crate::{ffi, Bound, PyAny, PyErr, PyResult, Python};
+use std::ffi::CStr;
 
 /// Represents a Python code object.
 ///
@@ -8,22 +12,146 @@ use crate::PyAny;
 #[repr(transparent)]
 pub struct PyCode(PyAny);
 
+#[cfg(not(any(Py_LIMITED_API, PyPy)))]
 pyobject_native_type_core!(
     PyCode,
     pyobject_native_static_type_object!(ffi::PyCode_Type),
     #checkfunction=ffi::PyCode_Check
 );
 
+#[cfg(any(Py_LIMITED_API, PyPy))]
+pyobject_native_type_named!(PyCode);
+
+#[cfg(any(Py_LIMITED_API, PyPy))]
+impl crate::PyTypeCheck for PyCode {
+    const NAME: &'static str = "PyCode";
+    #[cfg(feature = "experimental-inspect")]
+    const PYTHON_TYPE: &'static str = "types.CodeType";
+
+    fn type_check(object: &Bound<'_, PyAny>) -> bool {
+        let py = object.py();
+        static TYPE: crate::sync::GILOnceCell<crate::Py<super::PyType>> =
+            crate::sync::GILOnceCell::new();
+
+        TYPE.import(py, "types", "CodeType")
+            .and_then(|ty| object.is_instance(ty))
+            .unwrap_or_default()
+    }
+}
+
+/// Compilation mode of [`PyCode::compile`]
+pub enum PyCodeInput {
+    /// Python grammar for isolated expressions
+    Eval,
+    /// Python grammar for sequences of statements as read from a file
+    File,
+}
+
+impl PyCode {
+    /// Compiles code in the given context.
+    ///
+    /// `input` decides whether `code` is treated as
+    /// - [`PyCodeInput::Eval`]: an isolated expression
+    /// - [`PyCodeInput::File`]: a sequence of statements
+    pub fn compile<'py>(
+        py: Python<'py>,
+        code: &CStr,
+        filename: &CStr,
+        input: PyCodeInput,
+    ) -> PyResult<Bound<'py, PyCode>> {
+        let start = match input {
+            PyCodeInput::Eval => ffi::Py_eval_input,
+            PyCodeInput::File => ffi::Py_file_input,
+        };
+        unsafe {
+            ffi::Py_CompileString(code.as_ptr(), filename.as_ptr(), start)
+                .assume_owned_or_err(py)
+                .downcast_into_unchecked()
+        }
+    }
+}
+
+/// Implementation of functionality for [`PyCode`].
+///
+/// These methods are defined for the `Bound<'py, PyCode>` smart pointer, so to use method call
+/// syntax these methods are separated into a trait, because stable Rust does not yet support
+/// `arbitrary_self_types`.
+pub trait PyCodeMethods<'py> {
+    /// Runs code object.
+    ///
+    /// If `globals` is `None`, it defaults to Python module `__main__`.
+    /// If `locals` is `None`, it defaults to the value of `globals`.
+    fn run(
+        &self,
+        globals: Option<&Bound<'py, PyDict>>,
+        locals: Option<&Bound<'py, PyDict>>,
+    ) -> PyResult<Bound<'py, PyAny>>;
+}
+
+impl<'py> PyCodeMethods<'py> for Bound<'py, PyCode> {
+    fn run(
+        &self,
+        globals: Option<&Bound<'py, PyDict>>,
+        locals: Option<&Bound<'py, PyDict>>,
+    ) -> PyResult<Bound<'py, PyAny>> {
+        let mptr = unsafe {
+            ffi::compat::PyImport_AddModuleRef(ffi::c_str!("__main__").as_ptr())
+                .assume_owned_or_err(self.py())?
+        };
+        let attr = mptr.getattr(crate::intern!(self.py(), "__dict__"))?;
+        let globals = match globals {
+            Some(globals) => globals,
+            None => attr.downcast::<PyDict>()?,
+        };
+        let locals = locals.unwrap_or(globals);
+
+        // If `globals` don't provide `__builtins__`, most of the code will fail if Python
+        // version is <3.10. That's probably not what user intended, so insert `__builtins__`
+        // for them.
+        //
+        // See also:
+        // - https://github.com/python/cpython/pull/24564 (the same fix in CPython 3.10)
+        // - https://github.com/PyO3/pyo3/issues/3370
+        let builtins_s = crate::intern!(self.py(), "__builtins__");
+        let has_builtins = globals.contains(builtins_s)?;
+        if !has_builtins {
+            crate::sync::with_critical_section(globals, || {
+                // check if another thread set __builtins__ while this thread was blocked on the critical section
+                let has_builtins = globals.contains(builtins_s)?;
+                if !has_builtins {
+                    // Inherit current builtins.
+                    let builtins = unsafe { ffi::PyEval_GetBuiltins() };
+
+                    // `PyDict_SetItem` doesn't take ownership of `builtins`, but `PyEval_GetBuiltins`
+                    // seems to return a borrowed reference, so no leak here.
+                    if unsafe {
+                        ffi::PyDict_SetItem(globals.as_ptr(), builtins_s.as_ptr(), builtins)
+                    } == -1
+                    {
+                        return Err(PyErr::fetch(self.py()));
+                    }
+                }
+                Ok(())
+            })?;
+        }
+
+        unsafe {
+            ffi::PyEval_EvalCode(self.as_ptr(), globals.as_ptr(), locals.as_ptr())
+                .assume_owned_or_err(self.py())
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
-    use super::*;
-    use crate::types::PyTypeMethods;
-    use crate::{PyTypeInfo, Python};
-
     #[test]
+    #[cfg(not(any(Py_LIMITED_API, PyPy)))]
     fn test_type_object() {
+        use crate::types::PyTypeMethods;
+        use crate::{PyTypeInfo, Python};
+
         Python::attach(|py| {
-            assert_eq!(PyCode::type_object(py).name().unwrap(), "code");
+            assert_eq!(super::PyCode::type_object(py).name().unwrap(), "code");
         })
     }
 }
diff --git a/src/types/mod.rs b/src/types/mod.rs
@@ -5,8 +5,7 @@ pub use self::boolobject::{PyBool, PyBoolMethods};
 pub use self::bytearray::{PyByteArray, PyByteArrayMethods};
 pub use self::bytes::{PyBytes, PyBytesMethods};
 pub use self::capsule::{PyCapsule, PyCapsuleMethods};
-#[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
-pub use self::code::PyCode;
+pub use self::code::{PyCode, PyCodeInput, PyCodeMethods};
 pub use self::complex::{PyComplex, PyComplexMethods};
 #[allow(deprecated)]
 pub use self::datetime::{
@@ -223,7 +222,6 @@ pub(crate) mod boolobject;
 pub(crate) mod bytearray;
 pub(crate) mod bytes;
 pub(crate) mod capsule;
-#[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
 mod code;
 pub(crate) mod complex;
 pub(crate) mod datetime;

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+add `PyCode::compile` and `PyCodeMethods::run` to create and execute code objects