rename pyo3::prepare_freethreaded_python to Python::initialize

examples/plugin/src/main.rs

@@ -7,7 +7,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     //"export" our API module to the python runtime
     pyo3::append_to_inittab!(pylib_module);
     //spawn runtime
-    pyo3::prepare_freethreaded_python();
+    pyo3::initialize_python();
     //import path for python
     let path = Path::new("./python_plugin/");
     //do useful work

guide/src/building-and-distribution.md

@@ -278,7 +278,7 @@ If you encounter these or other complications when linking the interpreter stati
 
 ### Import your module when embedding the Python interpreter
 
-When you run your Rust binary with an embedded interpreter, any `#[pymodule]` created modules won't be accessible to import unless added to a table called `PyImport_Inittab` before the embedded interpreter is initialized. This will cause Python statements in your embedded interpreter such as `import your_new_module` to fail. You can call the macro [`append_to_inittab`]({{#PYO3_DOCS_URL}}/pyo3/macro.append_to_inittab.html) with your module before initializing the Python interpreter to add the module function into that table. (The Python interpreter will be initialized by calling `prepare_freethreaded_python`, `with_embedded_python_interpreter`, or `Python::attach` with the [`auto-initialize`](features.md#auto-initialize) feature enabled.)
+When you run your Rust binary with an embedded interpreter, any `#[pymodule]` created modules won't be accessible to import unless added to a table called `PyImport_Inittab` before the embedded interpreter is initialized. This will cause Python statements in your embedded interpreter such as `import your_new_module` to fail. You can call the macro [`append_to_inittab`]({{#PYO3_DOCS_URL}}/pyo3/macro.append_to_inittab.html) with your module before initializing the Python interpreter to add the module function into that table. (The Python interpreter will be initialized by calling `initialize_python`, `with_embedded_python_interpreter`, or `Python::attach` with the [`auto-initialize`](features.md#auto-initialize) feature enabled.)
 
 ## Cross Compiling
 

guide/src/features.md

@@ -45,9 +45,9 @@ section for further detail.
 
 ### `auto-initialize`
 
-This feature changes [`Python::attach`]({{#PYO3_DOCS_URL}}/pyo3/marker/struct.Python.html#method.attach) to automatically initialize a Python interpreter (by calling [`prepare_freethreaded_python`]({{#PYO3_DOCS_URL}}/pyo3/fn.prepare_freethreaded_python.html)) if needed.
+This feature changes [`Python::attach`]({{#PYO3_DOCS_URL}}/pyo3/marker/struct.Python.html#method.attach) to automatically initialize a Python interpreter (by calling [`initialize_python`]({{#PYO3_DOCS_URL}}/pyo3/fn.initialize_python.html)) if needed.
 
-If you do not enable this feature, you should call `pyo3::prepare_freethreaded_python()` before attempting to call any other Python APIs.
+If you do not enable this feature, you should call `pyo3::initialize_python()` before attempting to call any other Python APIs.
 
 ## Advanced Features
 

newsfragments/5247.changed.md

@@ -0,0 +1 @@
+Rename `pyo3::prepare_freethreaded_python` to `pyo3::initialize_python`

src/conversions/chrono.rs

@@ -23,7 +23,7 @@
 //! use pyo3::{Python, PyResult, IntoPyObject, types::PyAnyMethods};
 //!
 //! fn main() -> PyResult<()> {
-//!     pyo3::prepare_freethreaded_python();
+//!     pyo3::initialize_python();
 //!     Python::attach(|py| {
 //!         // Build some chrono values
 //!         let chrono_datetime = Utc.with_ymd_and_hms(2022, 1, 1, 12, 0, 0).unwrap();

src/conversions/chrono_tz.rs

@@ -24,7 +24,7 @@
 //! use pyo3::{Python, PyResult, IntoPyObject, types::PyAnyMethods};
 //!
 //! fn main() -> PyResult<()> {
-//!     pyo3::prepare_freethreaded_python();
+//!     pyo3::initialize_python();
 //!     Python::attach(|py| {
 //!         // Convert to Python
 //!         let py_tzinfo = Tz::Europe__Paris.into_pyobject(py)?;

src/conversions/either.rs

@@ -29,7 +29,7 @@
 //! use pyo3::{Python, PyResult, IntoPyObject, types::PyAnyMethods};
 //!
 //! fn main() -> PyResult<()> {
-//!     pyo3::prepare_freethreaded_python();
+//!     pyo3::initialize_python();
 //!     Python::attach(|py| {
 //!         // Create a string and an int in Python.
 //!         let py_str = "crab".into_pyobject(py)?;

src/conversions/jiff.rs

@@ -28,7 +28,7 @@
 //! # fn main() -> () {}
 //! # #[cfg(not(windows))]
 //! fn main() -> PyResult<()> {
-//!     pyo3::prepare_freethreaded_python();
+//!     pyo3::initialize_python();
 //!     Python::attach(|py| {
 //!         // Build some jiff values
 //!         let jiff_zoned = Zoned::now();

src/conversions/time.rs

@@ -21,7 +21,7 @@
 //! use pyo3::{Python, PyResult, IntoPyObject, types::PyAnyMethods};
 //!
 //! fn main() -> PyResult<()> {
-//!     pyo3::prepare_freethreaded_python();
+//!     pyo3::initialize_python();
 //!     Python::attach(|py| {
 //!         // Create a fixed date and time (2022-01-01 12:00:00 UTC)
 //!         let date = Date::from_calendar_date(2022, Month::January, 1).unwrap();

src/interpreter_lifecycle.rs

@@ -21,14 +21,14 @@ static START: std::sync::Once = std::sync::Once::new();
 /// use pyo3::prelude::*;
 ///
 /// # fn main() -> PyResult<()> {
-/// pyo3::prepare_freethreaded_python();
+/// pyo3::initialize_python();
 /// Python::attach(|py| py.run(pyo3::ffi::c_str!("print('Hello World')"), None, None))
 /// # }
 /// ```
 #[cfg(not(any(PyPy, GraalPy)))]
-pub fn prepare_freethreaded_python() {
+pub fn initialize_python() {
     // Protect against race conditions when Python is not yet initialized and multiple threads
-    // concurrently call 'prepare_freethreaded_python()'. Note that we do not protect against
+    // concurrently call 'initialize_python()'. Note that we do not protect against
     // concurrent initialization of the Python runtime by other users of the Python C API.
     START.call_once_force(|_| unsafe {
         // Use call_once_force because if initialization panics, it's okay to try again.
@@ -111,7 +111,7 @@ pub(crate) fn ensure_initialized() {
     //  - Otherwise, just check the interpreter is initialized.
     #[cfg(all(feature = "auto-initialize", not(any(PyPy, GraalPy))))]
     {
-        prepare_freethreaded_python();
+        initialize_python();
     }
     #[cfg(not(all(feature = "auto-initialize", not(any(PyPy, GraalPy)))))]
     {
@@ -121,7 +121,7 @@ pub(crate) fn ensure_initialized() {
         // provide a mechanism to specify required features for tests.
         #[cfg(not(any(PyPy, GraalPy)))]
         if option_env!("CARGO_PRIMARY_PACKAGE").is_some() {
-            prepare_freethreaded_python();
+            initialize_python();
         }
 
         START.call_once_force(|_| unsafe {
@@ -133,7 +133,7 @@ pub(crate) fn ensure_initialized() {
                 0,
                 "The Python interpreter is not initialized and the `auto-initialize` \
                         feature is not enabled.\n\n\
-                        Consider calling `pyo3::prepare_freethreaded_python()` before attempting \
+                        Consider calling `pyo3::initialize_python()` before attempting \
                         to use Python APIs."
             );
         });

src/lib.rs

@@ -345,9 +345,7 @@ pub use crate::conversion::{FromPyObject, IntoPyObject, IntoPyObjectExt};
 pub use crate::err::{DowncastError, DowncastIntoError, PyErr, PyErrArguments, PyResult, ToPyErr};
 pub use crate::instance::{Borrowed, Bound, BoundObject, Py, PyObject};
 #[cfg(not(any(PyPy, GraalPy)))]
-pub use crate::interpreter_lifecycle::{
-    prepare_freethreaded_python, with_embedded_python_interpreter,
-};
+pub use crate::interpreter_lifecycle::{initialize_python, with_embedded_python_interpreter};
 pub use crate::marker::Python;
 pub use crate::pycell::{PyRef, PyRefMut};
 pub use crate::pyclass::PyClass;

src/macros.rs

@@ -169,7 +169,7 @@ macro_rules! wrap_pymodule {
 /// Add the module to the initialization table in order to make embedded Python code to use it.
 /// Module name is the argument.
 ///
-/// Use it before [`prepare_freethreaded_python`](crate::prepare_freethreaded_python) and
+/// Use it before [`initialize_python`](crate::initialize_python) and
 /// leave feature `auto-initialize` off
 #[cfg(not(any(PyPy, GraalPy)))]
 #[macro_export]

src/marker.rs

@@ -379,9 +379,9 @@ impl Python<'_> {
     /// initialized, this function will initialize it. See
     #[cfg_attr(
         not(any(PyPy, GraalPy)),
-        doc = "[`prepare_freethreaded_python`](crate::prepare_freethreaded_python)"
+        doc = "[`initialize_python`](crate::initialize_python)"
     )]
-    #[cfg_attr(PyPy, doc = "`prepare_freethreaded_python`")]
+    #[cfg_attr(PyPy, doc = "`initialize_python`")]
     /// for details.
     ///
     /// If the current thread does not yet have a Python "thread state" associated with it,
@@ -889,7 +889,7 @@ mod tests {
         // Before starting the interpreter the state of calling `PyGILState_Check`
         // seems to be undefined, so let's ensure that Python is up.
         #[cfg(not(any(PyPy, GraalPy)))]
-        crate::prepare_freethreaded_python();
+        crate::initialize_python();
 
         let state = unsafe { crate::ffi::PyGILState_Check() };
         assert_eq!(state, GIL_NOT_HELD);