Draft: Rename pyo3::prepare_freethreaded_python

[olp-cs]

Related to #5061

---

At EuroPython Sprints with @Cheukting

[davidhewitt]

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

[olp-cs]

@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]

@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]

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

[olp-cs]

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

[davidhewitt]

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]

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]

Thank you! I'll look into this.

An issue would be helpful, yes please.

I've created it here: #5254

[davidhewitt]

@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]

@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.