pyo3/
marker.rs

1//! Fundamental properties of objects tied to the Python interpreter.
2//!
3//! The Python interpreter is not thread-safe. To protect the Python interpreter in multithreaded
4//! scenarios there is a global lock, the *global interpreter lock* (hereafter referred to as *GIL*)
5//! that must be held to safely interact with Python objects. This is why in PyO3 when you acquire
6//! the GIL you get a [`Python`] marker token that carries the *lifetime* of holding the GIL and all
7//! borrowed references to Python objects carry this lifetime as well. This will statically ensure
8//! that you can never use Python objects after dropping the lock - if you mess this up it will be
9//! caught at compile time and your program will fail to compile.
10//!
11//! It also supports this pattern that many extension modules employ:
12//! - Drop the GIL, so that other Python threads can acquire it and make progress themselves
13//! - Do something independently of the Python interpreter, like IO, a long running calculation or
14//!   awaiting a future
15//! - Once that is done, reacquire the GIL
16//!
17//! That API is provided by [`Python::detach`] and enforced via the [`Ungil`] bound on the
18//! closure and the return type. This is done by relying on the [`Send`] auto trait. `Ungil` is
19//! defined as the following:
20//!
21//! ```rust,no_run
22//! # #![allow(dead_code)]
23//! pub unsafe trait Ungil {}
24//!
25//! unsafe impl<T: Send> Ungil for T {}
26//! ```
27//!
28//! We piggy-back off the `Send` auto trait because it is not possible to implement custom auto
29//! traits on stable Rust. This is the solution which enables it for as many types as possible while
30//! making the API usable.
31//!
32//! In practice this API works quite well, but it comes with some drawbacks:
33//!
34//! ## Drawbacks
35//!
36//! There is no reason to prevent `!Send` types like [`Rc`] from crossing the closure. After all,
37//! [`Python::detach`] just lets other Python threads run - it does not itself launch a new
38//! thread.
39//!
40//! ```rust, compile_fail
41//! # #[cfg(feature = "nightly")]
42//! # compile_error!("this actually works on nightly")
43//! use pyo3::prelude::*;
44//! use std::rc::Rc;
45//!
46//! fn main() {
47//!     Python::attach(|py| {
48//!         let rc = Rc::new(5);
49//!
50//!         py.detach(|| {
51//!             // This would actually be fine...
52//!             println!("{:?}", *rc);
53//!         });
54//!     });
55//! }
56//! ```
57//!
58//! Because we are using `Send` for something it's not quite meant for, other code that
59//! (correctly) upholds the invariants of [`Send`] can cause problems.
60//!
61//! [`SendWrapper`] is one of those. Per its documentation:
62//!
63//! > A wrapper which allows you to move around non-Send-types between threads, as long as you
64//! > access the contained value only from within the original thread and make sure that it is
65//! > dropped from within the original thread.
66//!
67//! This will "work" to smuggle Python references across the closure, because we're not actually
68//! doing anything with threads:
69//!
70//! ```rust, no_run
71//! use pyo3::prelude::*;
72//! use pyo3::types::PyString;
73//! use send_wrapper::SendWrapper;
74//!
75//! Python::attach(|py| {
76//!     let string = PyString::new(py, "foo");
77//!
78//!     let wrapped = SendWrapper::new(string);
79//!
80//!     py.detach(|| {
81//! # #[cfg(not(feature = "nightly"))]
82//! # {
83//!         // 💥 Unsound! 💥
84//!         let smuggled: &Bound<'_, PyString> = &*wrapped;
85//!         println!("{:?}", smuggled);
86//! # }
87//!     });
88//! });
89//! ```
90//!
91//! For now the answer to that is "don't do that".
92//!
93//! # A proper implementation using an auto trait
94//!
95//! However on nightly Rust and when PyO3's `nightly` feature is
96//! enabled, `Ungil` is defined as the following:
97//!
98//! ```rust,no_run
99//! # #[cfg(any())]
100//! # {
101//! #![feature(auto_traits, negative_impls)]
102//!
103//! pub unsafe auto trait Ungil {}
104//!
105//! // It is unimplemented for the `Python` struct and Python objects.
106//! impl !Ungil for Python<'_> {}
107//! impl !Ungil for ffi::PyObject {}
108//!
109//! // `Py` wraps it in  a safe api, so this is OK
110//! unsafe impl<T> Ungil for Py<T> {}
111//! # }
112//! ```
113//!
114//! With this feature enabled, the above two examples will start working and not working, respectively.
115//!
116//! [`SendWrapper`]: https://docs.rs/send_wrapper/latest/send_wrapper/struct.SendWrapper.html
117//! [`Rc`]: std::rc::Rc
118//! [`Py`]: crate::Py
119use crate::conversion::IntoPyObject;
120use crate::err::{self, PyResult};
121use crate::internal::state::{AttachGuard, SuspendAttach};
122use crate::types::any::PyAnyMethods;
123use crate::types::{
124    PyAny, PyCode, PyCodeMethods, PyDict, PyEllipsis, PyModule, PyNone, PyNotImplemented, PyString,
125    PyType,
126};
127use crate::version::PythonVersionInfo;
128use crate::{ffi, Bound, Py, PyTypeInfo};
129use std::ffi::CStr;
130use std::marker::PhantomData;
131
132/// Types that are safe to access while the GIL is not held.
133///
134/// # Safety
135///
136/// The type must not carry borrowed Python references or, if it does, not allow access to them if
137/// the GIL is not held.
138///
139/// See the [module-level documentation](self) for more information.
140///
141/// # Examples
142///
143/// This tracking is currently imprecise as it relies on the [`Send`] auto trait on stable Rust.
144/// For example, an `Rc` smart pointer should be usable without the GIL, but we currently prevent that:
145///
146/// ```compile_fail
147/// # use pyo3::prelude::*;
148/// use std::rc::Rc;
149///
150/// Python::attach(|py| {
151///     let rc = Rc::new(42);
152///
153///     py.detach(|| {
154///         println!("{:?}", rc);
155///     });
156/// });
157/// ```
158///
159/// This also implies that the interplay between `attach` and `detach` is unsound, for example
160/// one can circumvent this protection using the [`send_wrapper`](https://docs.rs/send_wrapper/) crate:
161///
162/// ```no_run
163/// # use pyo3::prelude::*;
164/// # use pyo3::types::PyString;
165/// use send_wrapper::SendWrapper;
166///
167/// Python::attach(|py| {
168///     let string = PyString::new(py, "foo");
169///
170///     let wrapped = SendWrapper::new(string);
171///
172///     py.detach(|| {
173///         let sneaky: &Bound<'_, PyString> = &*wrapped;
174///
175///         println!("{:?}", sneaky);
176///     });
177/// });
178/// ```
179///
180/// Fixing this loophole on stable Rust has significant ergonomic issues, but it is fixed when using
181/// nightly Rust and the `nightly` feature, c.f. [#2141](https://github.com/PyO3/pyo3/issues/2141).
182#[cfg_attr(docsrs, doc(cfg(all())))] // Hide the cfg flag
183#[cfg(not(feature = "nightly"))]
184pub unsafe trait Ungil {}
185
186#[cfg_attr(docsrs, doc(cfg(all())))] // Hide the cfg flag
187#[cfg(not(feature = "nightly"))]
188unsafe impl<T: Send> Ungil for T {}
189
190#[cfg(feature = "nightly")]
191mod nightly {
192    macro_rules! define {
193        ($($tt:tt)*) => { $($tt)* }
194    }
195
196    define! {
197        /// Types that are safe to access while the GIL is not held.
198        ///
199        /// # Safety
200        ///
201        /// The type must not carry borrowed Python references or, if it does, not allow access to them if
202        /// the GIL is not held.
203        ///
204        /// See the [module-level documentation](self) for more information.
205        ///
206        /// # Examples
207        ///
208        /// Types which are `Ungil` cannot be used in contexts where the GIL was released, e.g.
209        ///
210        /// ```compile_fail
211        /// # use pyo3::prelude::*;
212        /// # use pyo3::types::PyString;
213        /// Python::attach(|py| {
214        ///     let string = PyString::new(py, "foo");
215        ///
216        ///     py.detach(|| {
217        ///         println!("{:?}", string);
218        ///     });
219        /// });
220        /// ```
221        ///
222        /// This applies to the GIL token `Python` itself as well, e.g.
223        ///
224        /// ```compile_fail
225        /// # use pyo3::prelude::*;
226        /// Python::attach(|py| {
227        ///     py.detach(|| {
228        ///         drop(py);
229        ///     });
230        /// });
231        /// ```
232        ///
233        /// On nightly Rust, this is not based on the [`Send`] auto trait and hence we are able
234        /// to prevent incorrectly circumventing it using e.g. the [`send_wrapper`](https://docs.rs/send_wrapper/) crate:
235        ///
236        /// ```compile_fail
237        /// # use pyo3::prelude::*;
238        /// # use pyo3::types::PyString;
239        /// use send_wrapper::SendWrapper;
240        ///
241        /// Python::attach(|py| {
242        ///     let string = PyString::new(py, "foo");
243        ///
244        ///     let wrapped = SendWrapper::new(string);
245        ///
246        ///     py.detach(|| {
247        ///         let sneaky: &PyString = *wrapped;
248        ///
249        ///         println!("{:?}", sneaky);
250        ///     });
251        /// });
252        /// ```
253        ///
254        /// This also enables using non-[`Send`] types in `detach`,
255        /// at least if they are not also bound to the GIL:
256        ///
257        /// ```rust
258        /// # use pyo3::prelude::*;
259        /// use std::rc::Rc;
260        ///
261        /// Python::attach(|py| {
262        ///     let rc = Rc::new(42);
263        ///
264        ///     py.detach(|| {
265        ///         println!("{:?}", rc);
266        ///     });
267        /// });
268        /// ```
269        pub unsafe auto trait Ungil {}
270    }
271
272    impl !Ungil for crate::Python<'_> {}
273
274    // This means that PyString, PyList, etc all inherit !Ungil from  this.
275    impl !Ungil for crate::PyAny {}
276
277    impl<T> !Ungil for crate::PyRef<'_, T> {}
278    impl<T> !Ungil for crate::PyRefMut<'_, T> {}
279
280    // FFI pointees
281    impl !Ungil for crate::ffi::PyObject {}
282    impl !Ungil for crate::ffi::PyLongObject {}
283
284    impl !Ungil for crate::ffi::PyThreadState {}
285    impl !Ungil for crate::ffi::PyInterpreterState {}
286    impl !Ungil for crate::ffi::PyWeakReference {}
287    impl !Ungil for crate::ffi::PyFrameObject {}
288    impl !Ungil for crate::ffi::PyCodeObject {}
289    #[cfg(not(Py_LIMITED_API))]
290    impl !Ungil for crate::ffi::PyDictKeysObject {}
291    #[cfg(not(any(Py_LIMITED_API, Py_3_10)))]
292    impl !Ungil for crate::ffi::PyArena {}
293}
294
295#[cfg(feature = "nightly")]
296pub use nightly::Ungil;
297
298/// A marker token that represents holding the GIL.
299///
300/// It serves three main purposes:
301/// - It provides a global API for the Python interpreter, such as [`Python::eval`].
302/// - It can be passed to functions that require a proof of holding the GIL, such as
303///   [`Py::clone_ref`](crate::Py::clone_ref).
304/// - Its lifetime represents the scope of holding the GIL which can be used to create Rust
305///   references that are bound to it, such as [`Bound<'py, PyAny>`].
306///
307/// Note that there are some caveats to using it that you might need to be aware of. See the
308/// [Deadlocks](#deadlocks) and [Releasing and freeing memory](#releasing-and-freeing-memory)
309/// paragraphs for more information about that.
310///
311/// # Obtaining a Python token
312///
313/// The following are the recommended ways to obtain a [`Python<'py>`] token, in order of preference:
314/// - If you already have something with a lifetime bound to the GIL, such as [`Bound<'py, PyAny>`], you can
315///   use its `.py()` method to get a token.
316/// - In a function or method annotated with [`#[pyfunction]`](crate::pyfunction) or [`#[pymethods]`](crate::pymethods) you can declare it
317///   as a parameter, and PyO3 will pass in the token when Python code calls it.
318/// - When you need to acquire the GIL yourself, such as when calling Python code from Rust, you
319///   should call [`Python::attach`] to do that and pass your code as a closure to it.
320///
321/// The first two options are zero-cost; [`Python::attach`] requires runtime checking and may need to block
322/// to acquire the GIL.
323///
324/// # Deadlocks
325///
326/// Note that the GIL can be temporarily released by the Python interpreter during a function call
327/// (e.g. importing a module). In general, you don't need to worry about this because the GIL is
328/// reacquired before returning to the Rust code:
329///
330/// ```text
331/// `Python` exists   |=====================================|
332/// GIL actually held |==========|         |================|
333/// Rust code running |=======|                |==|  |======|
334/// ```
335///
336/// This behaviour can cause deadlocks when trying to lock a Rust mutex while holding the GIL:
337///
338///  * Thread 1 acquires the GIL
339///  * Thread 1 locks a mutex
340///  * Thread 1 makes a call into the Python interpreter which releases the GIL
341///  * Thread 2 acquires the GIL
342///  * Thread 2 tries to locks the mutex, blocks
343///  * Thread 1's Python interpreter call blocks trying to reacquire the GIL held by thread 2
344///
345/// To avoid deadlocking, you should release the GIL before trying to lock a mutex or `await`ing in
346/// asynchronous code, e.g. with [`Python::detach`].
347///
348/// # Releasing and freeing memory
349///
350/// The [`Python<'py>`] type can be used to create references to variables owned by the Python
351/// interpreter, using functions such as [`Python::eval`] and [`PyModule::import`].
352#[derive(Copy, Clone)]
353pub struct Python<'py>(PhantomData<&'py AttachGuard>, PhantomData<NotSend>);
354
355/// A marker type that makes the type !Send.
356/// Workaround for lack of !Send on stable (<https://github.com/rust-lang/rust/issues/68318>).
357struct NotSend(PhantomData<*mut Python<'static>>);
358
359impl Python<'_> {
360    /// See [Python::attach]
361    #[inline]
362    #[track_caller]
363    #[deprecated(note = "use `Python::attach` instead", since = "0.26.0")]
364    pub fn with_gil<F, R>(f: F) -> R
365    where
366        F: for<'py> FnOnce(Python<'py>) -> R,
367    {
368        Self::attach(f)
369    }
370
371    /// Acquires the global interpreter lock, allowing access to the Python interpreter. The
372    /// provided closure `F` will be executed with the acquired `Python` marker token.
373    ///
374    /// If implementing [`#[pymethods]`](crate::pymethods) or [`#[pyfunction]`](crate::pyfunction),
375    /// declare `py: Python` as an argument. PyO3 will pass in the token to grant access to the GIL
376    /// context in which the function is running, avoiding the need to call `attach`.
377    ///
378    /// If the [`auto-initialize`] feature is enabled and the Python runtime is not already
379    /// initialized, this function will initialize it. See
380    #[cfg_attr(
381        not(any(PyPy, GraalPy)),
382        doc = "[`Python::initialize`](crate::marker::Python::initialize)"
383    )]
384    #[cfg_attr(PyPy, doc = "`Python::initialize")]
385    /// for details.
386    ///
387    /// If the current thread does not yet have a Python "thread state" associated with it,
388    /// a new one will be automatically created before `F` is executed and destroyed after `F`
389    /// completes.
390    ///
391    /// # Panics
392    ///
393    /// - If the [`auto-initialize`] feature is not enabled and the Python interpreter is not
394    ///   initialized.
395    /// - If the Python interpreter is in the process of [shutting down].
396    /// - If the middle of GC traversal.
397    ///
398    /// To avoid possible initialization or panics if calling in a context where the Python
399    /// interpreter might be unavailable, consider using [`Python::try_attach`].
400    ///
401    /// # Examples
402    ///
403    /// ```
404    /// use pyo3::prelude::*;
405    /// use pyo3::ffi::c_str;
406    ///
407    /// # fn main() -> PyResult<()> {
408    /// Python::attach(|py| -> PyResult<()> {
409    ///     let x: i32 = py.eval(c_str!("5"), None, None)?.extract()?;
410    ///     assert_eq!(x, 5);
411    ///     Ok(())
412    /// })
413    /// # }
414    /// ```
415    ///
416    /// [`auto-initialize`]: https://pyo3.rs/main/features.html#auto-initialize
417    /// [shutting down]: https://docs.python.org/3/glossary.html#term-interpreter-shutdown
418    #[inline]
419    #[track_caller]
420    pub fn attach<F, R>(f: F) -> R
421    where
422        F: for<'py> FnOnce(Python<'py>) -> R,
423    {
424        let guard = AttachGuard::attach();
425        f(guard.python())
426    }
427
428    /// Variant of [`Python::attach`] which will return without attaching to the Python
429    /// interpreter if the interpreter is in a state where it cannot be attached to:
430    /// - in the middle of GC traversal
431    /// - in the process of shutting down
432    /// - not initialized
433    ///
434    /// Note that due to the nature of the underlying Python APIs used to implement this,
435    /// the behavior is currently provided on a best-effort basis; it is expected that a
436    /// future CPython version will introduce APIs which guarantee this behaviour. This
437    /// function is still recommended for use in the meanwhile as it provides the best
438    /// possible behaviour and should transparently change to an optimal implementation
439    /// once such APIs are available.
440    #[inline]
441    #[track_caller]
442    pub fn try_attach<F, R>(f: F) -> Option<R>
443    where
444        F: for<'py> FnOnce(Python<'py>) -> R,
445    {
446        let guard = AttachGuard::try_attach().ok()?;
447        Some(f(guard.python()))
448    }
449
450    /// Prepares the use of Python.
451    ///
452    /// If the Python interpreter is not already initialized, this function will initialize it with
453    /// signal handling disabled (Python will not raise the `KeyboardInterrupt` exception). Python
454    /// signal handling depends on the notion of a 'main thread', which must be the thread that
455    /// initializes the Python interpreter.
456    ///
457    /// If the Python interpreter is already initialized, this function has no effect.
458    ///
459    /// This function is unavailable under PyPy because PyPy cannot be embedded in Rust (or any other
460    /// software). Support for this is tracked on the
461    /// [PyPy issue tracker](https://github.com/pypy/pypy/issues/3836).
462    ///
463    /// # Examples
464    /// ```rust
465    /// use pyo3::prelude::*;
466    ///
467    /// # fn main() -> PyResult<()> {
468    /// Python::initialize();
469    /// Python::attach(|py| py.run(pyo3::ffi::c_str!("print('Hello World')"), None, None))
470    /// # }
471    /// ```
472    #[cfg(not(any(PyPy, GraalPy)))]
473    pub fn initialize() {
474        crate::interpreter_lifecycle::initialize();
475    }
476
477    /// See [Python::attach_unchecked]
478    /// # Safety
479    ///
480    /// If [`Python::attach`] would succeed, it is safe to call this function.
481    #[inline]
482    #[track_caller]
483    #[deprecated(note = "use `Python::attach_unchecked` instead", since = "0.26.0")]
484    pub unsafe fn with_gil_unchecked<F, R>(f: F) -> R
485    where
486        F: for<'py> FnOnce(Python<'py>) -> R,
487    {
488        unsafe { Self::attach_unchecked(f) }
489    }
490
491    /// Like [`Python::attach`] except Python interpreter state checking is skipped.
492    ///
493    /// Normally when attaching to the Python interpreter, PyO3 checks that it is in
494    /// an appropriate state (e.g. it is fully initialized). This function skips
495    /// those checks.
496    ///
497    /// # Safety
498    ///
499    /// If [`Python::attach`] would succeed, it is safe to call this function.
500    #[inline]
501    #[track_caller]
502    pub unsafe fn attach_unchecked<F, R>(f: F) -> R
503    where
504        F: for<'py> FnOnce(Python<'py>) -> R,
505    {
506        let guard = unsafe { AttachGuard::attach_unchecked() };
507
508        f(guard.python())
509    }
510}
511
512impl<'py> Python<'py> {
513    /// See [Python::detach]
514    #[inline]
515    #[deprecated(note = "use `Python::detach` instead", since = "0.26.0")]
516    pub fn allow_threads<T, F>(self, f: F) -> T
517    where
518        F: Ungil + FnOnce() -> T,
519        T: Ungil,
520    {
521        self.detach(f)
522    }
523
524    /// Temporarily releases the GIL, thus allowing other Python threads to run. The GIL will be
525    /// reacquired when `F`'s scope ends.
526    ///
527    /// If you don't need to touch the Python
528    /// interpreter for some time and have other Python threads around, this will let you run
529    /// Rust-only code while letting those other Python threads make progress.
530    ///
531    /// Only types that implement [`Ungil`] can cross the closure. See the
532    /// [module level documentation](self) for more information.
533    ///
534    /// If you need to pass Python objects into the closure you can use [`Py`]`<T>`to create a
535    /// reference independent of the GIL lifetime. However, you cannot do much with those without a
536    /// [`Python`] token, for which you'd need to reacquire the GIL.
537    ///
538    /// # Example: Releasing the GIL while running a computation in Rust-only code
539    ///
540    /// ```
541    /// use pyo3::prelude::*;
542    ///
543    /// #[pyfunction]
544    /// fn sum_numbers(py: Python<'_>, numbers: Vec<u32>) -> PyResult<u32> {
545    ///     // We release the GIL here so any other Python threads get a chance to run.
546    ///     py.detach(move || {
547    ///         // An example of an "expensive" Rust calculation
548    ///         let sum = numbers.iter().sum();
549    ///
550    ///         Ok(sum)
551    ///     })
552    /// }
553    /// #
554    /// # fn main() -> PyResult<()> {
555    /// #     Python::attach(|py| -> PyResult<()> {
556    /// #         let fun = pyo3::wrap_pyfunction!(sum_numbers, py)?;
557    /// #         let res = fun.call1((vec![1_u32, 2, 3],))?;
558    /// #         assert_eq!(res.extract::<u32>()?, 6_u32);
559    /// #         Ok(())
560    /// #     })
561    /// # }
562    /// ```
563    ///
564    /// Please see the [Parallelism] chapter of the guide for a thorough discussion of using
565    /// [`Python::detach`] in this manner.
566    ///
567    /// # Example: Passing borrowed Python references into the closure is not allowed
568    ///
569    /// ```compile_fail
570    /// use pyo3::prelude::*;
571    /// use pyo3::types::PyString;
572    ///
573    /// fn parallel_print(py: Python<'_>) {
574    ///     let s = PyString::new(py, "This object cannot be accessed without holding the GIL >_<");
575    ///     py.detach(move || {
576    ///         println!("{:?}", s); // This causes a compile error.
577    ///     });
578    /// }
579    /// ```
580    ///
581    /// [`Py`]: crate::Py
582    /// [`PyString`]: crate::types::PyString
583    /// [auto-traits]: https://doc.rust-lang.org/nightly/unstable-book/language-features/auto-traits.html
584    /// [Parallelism]: https://pyo3.rs/main/parallelism.html
585    pub fn detach<T, F>(self, f: F) -> T
586    where
587        F: Ungil + FnOnce() -> T,
588        T: Ungil,
589    {
590        // Use a guard pattern to handle reacquiring the GIL,
591        // so that the GIL will be reacquired even if `f` panics.
592        // The `Send` bound on the closure prevents the user from
593        // transferring the `Python` token into the closure.
594        let _guard = unsafe { SuspendAttach::new() };
595        f()
596    }
597
598    /// Evaluates a Python expression in the given context and returns the result.
599    ///
600    /// If `globals` is `None`, it defaults to Python module `__main__`.
601    /// If `locals` is `None`, it defaults to the value of `globals`.
602    ///
603    /// If `globals` doesn't contain `__builtins__`, default `__builtins__`
604    /// will be added automatically.
605    ///
606    /// # Examples
607    ///
608    /// ```
609    /// # use pyo3::prelude::*;
610    /// # use pyo3::ffi::c_str;
611    /// # Python::attach(|py| {
612    /// let result = py.eval(c_str!("[i * 10 for i in range(5)]"), None, None).unwrap();
613    /// let res: Vec<i64> = result.extract().unwrap();
614    /// assert_eq!(res, vec![0, 10, 20, 30, 40])
615    /// # });
616    /// ```
617    pub fn eval(
618        self,
619        code: &CStr,
620        globals: Option<&Bound<'py, PyDict>>,
621        locals: Option<&Bound<'py, PyDict>>,
622    ) -> PyResult<Bound<'py, PyAny>> {
623        let code = PyCode::compile(
624            self,
625            code,
626            ffi::c_str!("<string>"),
627            crate::types::PyCodeInput::Eval,
628        )?;
629        code.run(globals, locals)
630    }
631
632    /// Executes one or more Python statements in the given context.
633    ///
634    /// If `globals` is `None`, it defaults to Python module `__main__`.
635    /// If `locals` is `None`, it defaults to the value of `globals`.
636    ///
637    /// If `globals` doesn't contain `__builtins__`, default `__builtins__`
638    /// will be added automatically.
639    ///
640    /// # Examples
641    /// ```
642    /// use pyo3::{
643    ///     prelude::*,
644    ///     types::{PyBytes, PyDict},
645    ///     ffi::c_str,
646    /// };
647    /// Python::attach(|py| {
648    ///     let locals = PyDict::new(py);
649    ///     py.run(c_str!(
650    ///         r#"
651    /// import base64
652    /// s = 'Hello Rust!'
653    /// ret = base64.b64encode(s.encode('utf-8'))
654    /// "#),
655    ///         None,
656    ///         Some(&locals),
657    ///     )
658    ///     .unwrap();
659    ///     let ret = locals.get_item("ret").unwrap().unwrap();
660    ///     let b64 = ret.cast::<PyBytes>().unwrap();
661    ///     assert_eq!(b64.as_bytes(), b"SGVsbG8gUnVzdCE=");
662    /// });
663    /// ```
664    ///
665    /// You can use [`py_run!`](macro.py_run.html) for a handy alternative of `run`
666    /// if you don't need `globals` and unwrapping is OK.
667    pub fn run(
668        self,
669        code: &CStr,
670        globals: Option<&Bound<'py, PyDict>>,
671        locals: Option<&Bound<'py, PyDict>>,
672    ) -> PyResult<()> {
673        let code = PyCode::compile(
674            self,
675            code,
676            ffi::c_str!("<string>"),
677            crate::types::PyCodeInput::File,
678        )?;
679        code.run(globals, locals).map(|obj| {
680            debug_assert!(obj.is_none());
681        })
682    }
683
684    /// Gets the Python type object for type `T`.
685    #[inline]
686    pub fn get_type<T>(self) -> Bound<'py, PyType>
687    where
688        T: PyTypeInfo,
689    {
690        T::type_object(self)
691    }
692
693    /// Imports the Python module with the specified name.
694    pub fn import<N>(self, name: N) -> PyResult<Bound<'py, PyModule>>
695    where
696        N: IntoPyObject<'py, Target = PyString>,
697    {
698        PyModule::import(self, name)
699    }
700
701    /// Gets the Python builtin value `None`.
702    #[allow(non_snake_case)] // the Python keyword starts with uppercase
703    #[inline]
704    pub fn None(self) -> Py<PyAny> {
705        PyNone::get(self).to_owned().into_any().unbind()
706    }
707
708    /// Gets the Python builtin value `Ellipsis`, or `...`.
709    #[allow(non_snake_case)] // the Python keyword starts with uppercase
710    #[inline]
711    pub fn Ellipsis(self) -> Py<PyAny> {
712        PyEllipsis::get(self).to_owned().into_any().unbind()
713    }
714
715    /// Gets the Python builtin value `NotImplemented`.
716    #[allow(non_snake_case)] // the Python keyword starts with uppercase
717    #[inline]
718    pub fn NotImplemented(self) -> Py<PyAny> {
719        PyNotImplemented::get(self).to_owned().into_any().unbind()
720    }
721
722    /// Gets the running Python interpreter version as a string.
723    ///
724    /// # Examples
725    /// ```rust
726    /// # use pyo3::Python;
727    /// Python::attach(|py| {
728    ///     // The full string could be, for example:
729    ///     // "3.10.0 (tags/v3.10.0:b494f59, Oct  4 2021, 19:00:18) [MSC v.1929 64 bit (AMD64)]"
730    ///     assert!(py.version().starts_with("3."));
731    /// });
732    /// ```
733    pub fn version(self) -> &'py str {
734        unsafe {
735            CStr::from_ptr(ffi::Py_GetVersion())
736                .to_str()
737                .expect("Python version string not UTF-8")
738        }
739    }
740
741    /// Gets the running Python interpreter version as a struct similar to
742    /// `sys.version_info`.
743    ///
744    /// # Examples
745    /// ```rust
746    /// # use pyo3::Python;
747    /// Python::attach(|py| {
748    ///     // PyO3 supports Python 3.7 and up.
749    ///     assert!(py.version_info() >= (3, 7));
750    ///     assert!(py.version_info() >= (3, 7, 0));
751    /// });
752    /// ```
753    pub fn version_info(self) -> PythonVersionInfo<'py> {
754        let version_str = self.version();
755
756        // Portion of the version string returned by Py_GetVersion up to the first space is the
757        // version number.
758        let version_number_str = version_str.split(' ').next().unwrap_or(version_str);
759
760        PythonVersionInfo::from_str(version_number_str).unwrap()
761    }
762
763    /// Lets the Python interpreter check and handle any pending signals. This will invoke the
764    /// corresponding signal handlers registered in Python (if any).
765    ///
766    /// Returns `Err(`[`PyErr`](crate::PyErr)`)` if any signal handler raises an exception.
767    ///
768    /// These signals include `SIGINT` (normally raised by CTRL + C), which by default raises
769    /// `KeyboardInterrupt`. For this reason it is good practice to call this function regularly
770    /// as part of long-running Rust functions so that users can cancel it.
771    ///
772    /// # Example
773    ///
774    /// ```rust,no_run
775    /// # #![allow(dead_code)] // this example is quite impractical to test
776    /// use pyo3::prelude::*;
777    ///
778    /// # fn main() {
779    /// #[pyfunction]
780    /// fn loop_forever(py: Python<'_>) -> PyResult<()> {
781    ///     loop {
782    ///         // As this loop is infinite it should check for signals every once in a while.
783    ///         // Using `?` causes any `PyErr` (potentially containing `KeyboardInterrupt`)
784    ///         // to break out of the loop.
785    ///         py.check_signals()?;
786    ///
787    ///         // do work here
788    ///         # break Ok(()) // don't actually loop forever
789    ///     }
790    /// }
791    /// # }
792    /// ```
793    ///
794    /// # Note
795    ///
796    /// This function calls [`PyErr_CheckSignals()`][1] which in turn may call signal handlers.
797    /// As Python's [`signal`][2] API allows users to define custom signal handlers, calling this
798    /// function allows arbitrary Python code inside signal handlers to run.
799    ///
800    /// If the function is called from a non-main thread, or under a non-main Python interpreter,
801    /// it does nothing yet still returns `Ok(())`.
802    ///
803    /// [1]: https://docs.python.org/3/c-api/exceptions.html?highlight=pyerr_checksignals#c.PyErr_CheckSignals
804    /// [2]: https://docs.python.org/3/library/signal.html
805    pub fn check_signals(self) -> PyResult<()> {
806        err::error_on_minusone(self, unsafe { ffi::PyErr_CheckSignals() })
807    }
808}
809
810impl<'unbound> Python<'unbound> {
811    /// Deprecated version of [`Python::assume_attached`]
812    ///
813    /// # Safety
814    /// See [`Python::assume_attached`]
815    #[inline]
816    #[deprecated(since = "0.26.0", note = "use `Python::assume_attached` instead")]
817    pub unsafe fn assume_gil_acquired() -> Python<'unbound> {
818        unsafe { Self::assume_attached() }
819    }
820    /// Unsafely creates a Python token with an unbounded lifetime.
821    ///
822    /// Many of PyO3 APIs use [`Python<'_>`] as proof that the calling thread is attached to the
823    /// interpreter, but this function can be used to call them unsafely.
824    ///
825    /// # Safety
826    ///
827    /// - This token and any borrowed Python references derived from it can only be safely used
828    ///   whilst the currently executing thread is actually attached to the interpreter.
829    /// - This function creates a token with an *unbounded* lifetime. Safe code can assume that
830    ///   holding a [`Python<'py>`] token means the thread is attached and stays attached for the
831    ///   lifetime `'py`. If you let it or borrowed Python references escape to safe code you are
832    ///   responsible for bounding the lifetime `'unbound` appropriately. For more on unbounded
833    ///   lifetimes, see the [nomicon].
834    ///
835    /// [nomicon]: https://doc.rust-lang.org/nomicon/unbounded-lifetimes.html
836    #[inline]
837    pub unsafe fn assume_attached() -> Python<'unbound> {
838        Python(PhantomData, PhantomData)
839    }
840}
841
842#[cfg(test)]
843mod tests {
844    use super::*;
845    use crate::{
846        internal::state::ForbidAttaching,
847        types::{IntoPyDict, PyList},
848    };
849
850    #[test]
851    fn test_eval() {
852        Python::attach(|py| {
853            // Make sure builtin names are accessible
854            let v: i32 = py
855                .eval(ffi::c_str!("min(1, 2)"), None, None)
856                .map_err(|e| e.display(py))
857                .unwrap()
858                .extract()
859                .unwrap();
860            assert_eq!(v, 1);
861
862            let d = [("foo", 13)].into_py_dict(py).unwrap();
863
864            // Inject our own global namespace
865            let v: i32 = py
866                .eval(ffi::c_str!("foo + 29"), Some(&d), None)
867                .unwrap()
868                .extract()
869                .unwrap();
870            assert_eq!(v, 42);
871
872            // Inject our own local namespace
873            let v: i32 = py
874                .eval(ffi::c_str!("foo + 29"), None, Some(&d))
875                .unwrap()
876                .extract()
877                .unwrap();
878            assert_eq!(v, 42);
879
880            // Make sure builtin names are still accessible when using a local namespace
881            let v: i32 = py
882                .eval(ffi::c_str!("min(foo, 2)"), None, Some(&d))
883                .unwrap()
884                .extract()
885                .unwrap();
886            assert_eq!(v, 2);
887        });
888    }
889
890    #[test]
891    #[cfg(not(target_arch = "wasm32"))] // We are building wasm Python with pthreads disabled
892    fn test_detach_releases_and_acquires_gil() {
893        Python::attach(|py| {
894            let b = std::sync::Arc::new(std::sync::Barrier::new(2));
895
896            let b2 = b.clone();
897            std::thread::spawn(move || Python::attach(|_| b2.wait()));
898
899            py.detach(|| {
900                // If `detach` does not release the GIL, this will deadlock because
901                // the thread spawned above will never be able to acquire the GIL.
902                b.wait();
903            });
904
905            unsafe {
906                // If the GIL is not reacquired at the end of `detach`, this call
907                // will crash the Python interpreter.
908                let tstate = ffi::PyEval_SaveThread();
909                ffi::PyEval_RestoreThread(tstate);
910            }
911        });
912    }
913
914    #[test]
915    fn test_detach_panics_safely() {
916        Python::attach(|py| {
917            let result = std::panic::catch_unwind(|| unsafe {
918                let py = Python::assume_attached();
919                py.detach(|| {
920                    panic!("There was a panic!");
921                });
922            });
923
924            // Check panic was caught
925            assert!(result.is_err());
926
927            // If `detach` is implemented correctly, this thread still owns the GIL here
928            // so the following Python calls should not cause crashes.
929            let list = PyList::new(py, [1, 2, 3, 4]).unwrap();
930            assert_eq!(list.extract::<Vec<i32>>().unwrap(), vec![1, 2, 3, 4]);
931        });
932    }
933
934    #[cfg(not(pyo3_disable_reference_pool))]
935    #[test]
936    fn test_detach_pass_stuff_in() {
937        let list = Python::attach(|py| PyList::new(py, vec!["foo", "bar"]).unwrap().unbind());
938        let mut v = vec![1, 2, 3];
939        let a = std::sync::Arc::new(String::from("foo"));
940
941        Python::attach(|py| {
942            py.detach(|| {
943                drop((list, &mut v, a));
944            });
945        });
946    }
947
948    #[test]
949    #[cfg(not(Py_LIMITED_API))]
950    fn test_acquire_gil() {
951        use std::ffi::c_int;
952
953        const GIL_NOT_HELD: c_int = 0;
954        const GIL_HELD: c_int = 1;
955
956        // Before starting the interpreter the state of calling `PyGILState_Check`
957        // seems to be undefined, so let's ensure that Python is up.
958        #[cfg(not(any(PyPy, GraalPy)))]
959        Python::initialize();
960
961        let state = unsafe { crate::ffi::PyGILState_Check() };
962        assert_eq!(state, GIL_NOT_HELD);
963
964        Python::attach(|_| {
965            let state = unsafe { crate::ffi::PyGILState_Check() };
966            assert_eq!(state, GIL_HELD);
967        });
968
969        let state = unsafe { crate::ffi::PyGILState_Check() };
970        assert_eq!(state, GIL_NOT_HELD);
971    }
972
973    #[test]
974    fn test_ellipsis() {
975        Python::attach(|py| {
976            assert_eq!(py.Ellipsis().to_string(), "Ellipsis");
977
978            let v = py
979                .eval(ffi::c_str!("..."), None, None)
980                .map_err(|e| e.display(py))
981                .unwrap();
982
983            assert!(v.eq(py.Ellipsis()).unwrap());
984        });
985    }
986
987    #[test]
988    fn test_py_run_inserts_globals() {
989        use crate::types::dict::PyDictMethods;
990
991        Python::attach(|py| {
992            let namespace = PyDict::new(py);
993            py.run(
994                ffi::c_str!("class Foo: pass\na = int(3)"),
995                Some(&namespace),
996                Some(&namespace),
997            )
998            .unwrap();
999            assert!(matches!(namespace.get_item("Foo"), Ok(Some(..))));
1000            assert!(matches!(namespace.get_item("a"), Ok(Some(..))));
1001            // 3.9 and older did not automatically insert __builtins__ if it wasn't inserted "by hand"
1002            #[cfg(not(Py_3_10))]
1003            assert!(matches!(namespace.get_item("__builtins__"), Ok(Some(..))));
1004        })
1005    }
1006
1007    #[cfg(feature = "macros")]
1008    #[test]
1009    fn test_py_run_inserts_globals_2() {
1010        use std::ffi::CString;
1011
1012        #[crate::pyclass(crate = "crate")]
1013        #[derive(Clone)]
1014        struct CodeRunner {
1015            code: CString,
1016        }
1017
1018        impl CodeRunner {
1019            fn reproducer(&mut self, py: Python<'_>) -> PyResult<()> {
1020                let variables = PyDict::new(py);
1021                variables.set_item("cls", crate::Py::new(py, self.clone())?)?;
1022
1023                py.run(self.code.as_c_str(), Some(&variables), None)?;
1024                Ok(())
1025            }
1026        }
1027
1028        #[crate::pymethods(crate = "crate")]
1029        impl CodeRunner {
1030            fn func(&mut self, py: Python<'_>) -> PyResult<()> {
1031                py.import("math")?;
1032                Ok(())
1033            }
1034        }
1035
1036        let mut runner = CodeRunner {
1037            code: CString::new(
1038                r#"
1039cls.func()
1040"#
1041                .to_string(),
1042            )
1043            .unwrap(),
1044        };
1045
1046        Python::attach(|py| {
1047            runner.reproducer(py).unwrap();
1048        });
1049    }
1050
1051    #[test]
1052    fn python_is_zst() {
1053        assert_eq!(std::mem::size_of::<Python<'_>>(), 0);
1054    }
1055
1056    #[test]
1057    fn test_try_attach_fail_during_gc() {
1058        Python::attach(|_| {
1059            assert!(Python::try_attach(|_| {}).is_some());
1060
1061            let guard = ForbidAttaching::during_traverse();
1062            assert!(Python::try_attach(|_| {}).is_none());
1063            drop(guard);
1064
1065            assert!(Python::try_attach(|_| {}).is_some());
1066        })
1067    }
1068
1069    #[test]
1070    fn test_try_attach_ok_when_detached() {
1071        Python::attach(|py| {
1072            py.detach(|| {
1073                assert!(Python::try_attach(|_| {}).is_some());
1074            });
1075        });
1076    }
1077}