pyo3/interpreter_lifecycle.rs
1#[cfg(not(any(PyPy, GraalPy)))]
2use crate::{ffi, internal::state::AttachGuard, Python};
3
4static START: std::sync::Once = std::sync::Once::new();
5
6#[cfg(not(any(PyPy, GraalPy)))]
7pub(crate) fn initialize() {
8 // Protect against race conditions when Python is not yet initialized and multiple threads
9 // concurrently call 'initialize()'. Note that we do not protect against
10 // concurrent initialization of the Python runtime by other users of the Python C API.
11 START.call_once_force(|_| unsafe {
12 // Use call_once_force because if initialization panics, it's okay to try again.
13 if ffi::Py_IsInitialized() == 0 {
14 ffi::Py_InitializeEx(0);
15
16 // Release the GIL.
17 ffi::PyEval_SaveThread();
18 }
19 });
20}
21
22/// Executes the provided closure with an embedded Python interpreter.
23///
24/// This function initializes the Python interpreter, executes the provided closure, and then
25/// finalizes the Python interpreter.
26///
27/// After execution all Python resources are cleaned up, and no further Python APIs can be called.
28/// Because many Python modules implemented in C do not support multiple Python interpreters in a
29/// single process, it is not safe to call this function more than once. (Many such modules will not
30/// initialize correctly on the second run.)
31///
32/// # Panics
33/// - If the Python interpreter is already initialized before calling this function.
34///
35/// # Safety
36/// - This function should only ever be called once per process (usually as part of the `main`
37/// function). It is also not thread-safe.
38/// - No Python APIs can be used after this function has finished executing.
39/// - The return value of the closure must not contain any Python value, _including_ `PyResult`.
40///
41/// # Examples
42///
43/// ```rust
44/// unsafe {
45/// pyo3::with_embedded_python_interpreter(|py| {
46/// if let Err(e) = py.run(c"print('Hello World')", None, None) {
47/// // We must make sure to not return a `PyErr`!
48/// e.print(py);
49/// }
50/// });
51/// }
52/// ```
53#[cfg(not(any(PyPy, GraalPy)))]
54pub unsafe fn with_embedded_python_interpreter<F, R>(f: F) -> R
55where
56 F: for<'p> FnOnce(Python<'p>) -> R,
57{
58 assert_eq!(
59 unsafe { ffi::Py_IsInitialized() },
60 0,
61 "called `with_embedded_python_interpreter` but a Python interpreter is already running."
62 );
63
64 unsafe { ffi::Py_InitializeEx(0) };
65
66 let result = {
67 let guard = unsafe { AttachGuard::assume() };
68 let py = guard.python();
69 // Import the threading module - this ensures that it will associate this thread as the "main"
70 // thread, which is important to avoid an `AssertionError` at finalization.
71 py.import("threading").unwrap();
72
73 // Execute the closure.
74 f(py)
75 };
76
77 // Finalize the Python interpreter.
78 unsafe { ffi::Py_Finalize() };
79
80 result
81}
82
83/// If PyO3 is currently running `Py_InitializeEx` inside the `Once` guard,
84/// block until it completes. Needed because `Py_InitializeEx` sets the
85/// `initialized` flag in the interpreter to true before it finishes all its
86/// steps (in particular, before it imports `site.py`).
87///
88/// This must only be called after `Py_IsInitialized()` has returned true.
89///
90/// If the `Once` was never started (e.g. the interpreter was initialized
91/// externally, not through PyO3), `call_once` runs the empty closure and
92/// returns — this is fine because `initialize()` checks
93/// `Py_IsInitialized()` inside its closure and skips `Py_InitializeEx` if
94/// the interpreter is already running. If the `Once` is currently in
95/// progress (another thread is inside `initialize()`), `call_once` blocks
96/// until it completes.
97pub(crate) fn wait_for_initialization() {
98 // TODO: use START.wait_force() on MSRV 1.86
99 // TODO: may not be needed on Python 3.15 (https://github.com/python/cpython/pull/146303)
100 START.call_once(|| {
101 assert_ne!(unsafe { crate::ffi::Py_IsInitialized() }, 0);
102 });
103}
104
105pub(crate) fn ensure_initialized() {
106 // Maybe auto-initialize the interpreter:
107 // - If auto-initialize feature set and supported, try to initialize the interpreter.
108 // - If the auto-initialize feature is set but unsupported, emit hard errors only when the
109 // extension-module feature is not activated - extension modules don't care about
110 // auto-initialize so this avoids breaking existing builds.
111 // - Otherwise, just check the interpreter is initialized.
112 #[cfg(all(feature = "auto-initialize", not(any(PyPy, GraalPy))))]
113 {
114 initialize();
115 }
116 #[cfg(not(all(feature = "auto-initialize", not(any(PyPy, GraalPy)))))]
117 {
118 // This is a "hack" to make running `cargo test` for PyO3 convenient (i.e. no need
119 // to specify `--features auto-initialize` manually). Tests within the crate itself
120 // all depend on the auto-initialize feature for conciseness but Cargo does not
121 // provide a mechanism to specify required features for tests.
122 #[cfg(not(any(PyPy, GraalPy)))]
123 if option_env!("CARGO_PRIMARY_PACKAGE").is_some() {
124 initialize();
125 }
126
127 START.call_once_force(|_| unsafe {
128 // Use call_once_force because if there is a panic because the interpreter is
129 // not initialized, it's fine for the user to initialize the interpreter and
130 // retry.
131 assert_ne!(
132 crate::ffi::Py_IsInitialized(),
133 0,
134 "The Python interpreter is not initialized and the `auto-initialize` \
135 feature is not enabled.\n\n\
136 Consider calling `Python::initialize()` before attempting \
137 to use Python APIs."
138 );
139 });
140 }
141}