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