rename `pyo3::prepare_freethreaded_python` to `Python::initialize` #5247

olp-cs · 2025-07-19T15:40:27Z

Related to #5061

At EuroPython Sprints with @Cheukting

davidhewitt · 2025-07-20T12:55:53Z

Thanks for the contribution! Other than needing a newsfragment, what makes this WIP? I'd love to merge for the upcoming release.

olp-cs · 2025-07-20T13:06:22Z

@davidhewitt Some of the tests were failing for me locally on the main branch (even before the changes), with different error messages on Linux and macOS, so I wanted to test it additionally. I submitted it here to look at the CI/CD results. If you think that everything is fine, then you are free to merge it, of course.

olp-cs · 2025-07-20T20:28:29Z

@davidhewitt
Update: I’ve managed to run the tests successfully in the following macOS 11.7.10 environment:

platform darwin -- Python 3.12.7, pytest-8.4.1, pluggy-1.6.0
rustc 1.88.0 (6b00bc388 2025-06-23)

The tests are now passing in the main branch and in the initialize_python branch.

However, the tests on the main branch were failing in the default environment of GitHub Codespaces. I can collect all details and create an issue if you think it might be helpful to investigate this further (another option would be to create a .devcontainer for reproducible builds).

$ uname -a
Linux codespaces-528582 6.8.0-1027-azure #32~22.04.1-Ubuntu SMP Thu Apr  3 20:26:27 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux

$ nox -s test
...
error: 3 targets failed:
    `--lib`
    `--test test_datetime`
    `--test test_pyerr_debug_unformattable`
nox > Command cargo test --no-fail-fast --no-default-features --all-targets failed with exit code 101
nox > Session test failed.

Icxolu

Did we rule out Python::initialize? That would sounds intuitive to me and it would be near to the other functions that interact with the runtime like Python::attach and Python::detach. Might be nice for discoveribility.

Icxolu · 2025-07-21T16:31:23Z

src/interpreter_lifecycle.rs

 /// ```
 #[cfg(not(any(PyPy, GraalPy)))]
-pub fn prepare_freethreaded_python() {
+pub fn initialize_python() {


I think we should keep the old name with a deprecation added to offer a smoother transition to users.

olp-cs · 2025-07-21T18:19:55Z

I agree, it makes sense. I'll need to look into the implementation.

davidhewitt · 2025-07-21T19:03:52Z

Python::initialize is also fine with me, it probably is slightly better from a discoverability perspective. 👍

However, the tests on the main branch were failing in the default environment of GitHub Codespaces. I can collect all details and create an issue if you think it might be helpful to investigate this further (another option would be to create a .devcontainer for reproducible builds).

An issue would be helpful, yes please.

Cheukting · 2025-07-21T19:13:35Z

Nicely done @olp-cs! You may find this helpful: https://rustwiki.org/en/reference/attributes/diagnostics.html#the-deprecated-attribute

An example of it in PyO3 can be found here:

pyo3/pyo3-ffi/src/intrcheck.rs

Line 13 in 7836f15

#[deprecated(note = "use PyOS_AfterFork_Child instead")]

olp-cs · 2025-07-22T06:37:43Z

Thank you! I'll look into this.

An issue would be helpful, yes please.

I've created it here: #5254

davidhewitt · 2025-07-26T18:20:49Z

@olp-cs just checking to see when you expect to have a chance to return to this? I think the agreement is that Python::initialize is slightly preferred and we need to preserve the existing API as a deprecation.

Reason why I ask - I'd love to get this into the 0.26 release, which I'd like to publish in the next week or two. I prefer to leave time for contributors to cycle back when they can and fully understand everyone has different availability and resources. In this case this rename really fits being released alongside the rename of Python::with_gil -> Python:attach which is already ready to go in 0.26.

If you don't have availability to finish this in the next couple weeks, I totally understand. I can push to this branch and finish this off if you will forgive me 🙏 .

olp-cs · 2025-07-27T18:56:00Z

@davidhewitt Thank you for the explanations! If you don't hear back from me by 30 July, feel free to take it over. Apologies for the delay, I was at another conference right after EuroPython, and I've just came back from Prague. I'll try to get back to this issue within the next couple of days.

olp-cs · 2025-07-29T14:24:34Z

I've updated the PR.

Main changes to be reviewed:

src/interpreter_lifecycle.rs
guide/src/migration.md

…y-all`

davidhewitt

Thank you very much for coming back round to this! This looks great, with just one tiny nit which I'd prefer adjusted before merge please 🙏

davidhewitt · 2025-07-29T19:24:46Z

src/interpreter_lifecycle.rs

+impl Python<'_> {
+    /// Prepares the use of Python.
+    ///
+    /// If the Python interpreter is not already initialized, this function will initialize it with
+    /// signal handling disabled (Python will not raise the `KeyboardInterrupt` exception). Python
+    /// signal handling depends on the notion of a 'main thread', which must be the thread that
+    /// initializes the Python interpreter.
+    ///
+    /// If the Python interpreter is already initialized, this function has no effect.
+    ///
+    /// This function is unavailable under PyPy because PyPy cannot be embedded in Rust (or any other
+    /// software). Support for this is tracked on the
+    /// [PyPy issue tracker](https://github.com/pypy/pypy/issues/3836).
+    ///
+    /// # Examples
+    /// ```rust
+    /// use pyo3::prelude::*;
+    ///
+    /// # fn main() -> PyResult<()> {
+    /// Python::initialize();
+    /// Python::attach(|py| py.run(pyo3::ffi::c_str!("print('Hello World')"), None, None))
+    /// # }
+    /// ```
+    pub fn initialize() {


It's a handy feature of Rust to be able to split impl Type methods across multiple files, though I generally prefer to avoid it if I can. I think I'd rather we made the function here just an internal free function pub(crate) fn initialize and then we can add this new Python::initialize method with all the documentation in src/marker.rs

The Python::initialize method can then just call crate::interpreter_lifecycle::initialize(), exactly like the deprecated prepare_freethreaded_python does just below.

I think we just raced here 😁

Icxolu

Thanks! This looks pretty good to me, just some minor things from my side

src/lib.rs

Icxolu · 2025-07-29T19:19:49Z

src/interpreter_lifecycle.rs

+    /// Python::attach(|py| py.run(pyo3::ffi::c_str!("print('Hello World')"), None, None))
+    /// # }
+    /// ```
+    pub fn initialize() {


I think I would prefer if we move this into marker.rs (where Python is defined), probably next to attach would make sense to me. What do you think @davidhewitt

Yep I was thinking the same 😂

#5247 (comment)

guide/src/features.md

src/interpreter_lifecycle.rs

olp-cs · 2025-07-29T20:37:18Z

@davidhewitt @Icxolu Thank you for your detailed feedback and suggestions! I really appreciate it. I think it’s better structured now, but please let me know if there’s anything else I should change.

davidhewitt

Brilliant, thank you!

olp-cs added 2 commits July 19, 2025 16:24

Rename pyo3::prepare_freethreaded_python to pyo3::initialize_python

82dc131

Rename pyo3::prepare_freethreaded_python to pyo3::initialize_python

44d577e

davidhewitt mentioned this pull request Jul 19, 2025

0.26 Release #5249

Closed

Add newsfragment

1d0fe4b

olp-cs changed the title ~~Draft: Rename pyo3::prepare_freethreaded_python to pyo3::initialize_python~~ Rename pyo3::prepare_freethreaded_python to pyo3::initialize_python Jul 20, 2025

Icxolu reviewed Jul 21, 2025

View reviewed changes

olp-cs changed the title ~~Rename pyo3::prepare_freethreaded_python to pyo3::initialize_python~~ Draft: Rename pyo3::prepare_freethreaded_python Jul 22, 2025

Rename to Python::initialize; update migration docs

0a7cf41

olp-cs changed the title ~~Draft: Rename pyo3::prepare_freethreaded_python~~ rename pyo3::prepare_freethreaded_python to Python::initialize Jul 29, 2025

Fix Clippy errors for PyPy 3.9, 3.10, 3.11 when running `nox -s clipp…

608a898

…y-all`

davidhewitt reviewed Jul 29, 2025

View reviewed changes

Icxolu reviewed Jul 29, 2025

View reviewed changes

Update after reviews

7e8cc0d

call local function instead

b5379e8

davidhewitt approved these changes Jul 30, 2025

View reviewed changes

davidhewitt enabled auto-merge July 30, 2025 08:11

Merge branch 'main' into initialize-python

745792a

davidhewitt added this pull request to the merge queue Aug 1, 2025

Merged via the queue into PyO3:main with commit 16d039b Aug 1, 2025
42 of 43 checks passed

davidhewitt mentioned this pull request Aug 1, 2025

Rename pyo3::prepare_freethreaded_python to something more meaningful #5061

Closed

olp-cs deleted the initialize-python branch August 1, 2025 15:22

rename pyo3::prepare_freethreaded_python to Python::initialize #5247

rename pyo3::prepare_freethreaded_python to Python::initialize #5247

Uh oh!

Conversation

olp-cs commented Jul 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidhewitt commented Jul 20, 2025

Uh oh!

olp-cs commented Jul 20, 2025

Uh oh!

olp-cs commented Jul 20, 2025

Uh oh!

Icxolu left a comment

Choose a reason for hiding this comment

Uh oh!

Icxolu Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

olp-cs commented Jul 21, 2025

Uh oh!

davidhewitt commented Jul 21, 2025

Uh oh!

Cheukting commented Jul 21, 2025

Uh oh!

olp-cs commented Jul 22, 2025

Uh oh!

davidhewitt commented Jul 26, 2025

Uh oh!

olp-cs commented Jul 27, 2025

Uh oh!

olp-cs commented Jul 29, 2025

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

davidhewitt Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Icxolu Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Icxolu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Icxolu Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

davidhewitt Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

olp-cs commented Jul 29, 2025

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rename `pyo3::prepare_freethreaded_python` to `Python::initialize` #5247

rename `pyo3::prepare_freethreaded_python` to `Python::initialize` #5247

olp-cs commented Jul 19, 2025 •

edited

Loading