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}