Suggested convention for a free threading build marker on exact Python versions

Packaging
1

The CPython upstream project only defines a naming suffix for builds with free threading enabled at the 3.13 feature release level (i.e. the installed binary is python3.13t, and the wheel ABI tag is cp313t). The t build variant suffix isn’t considered part of the version number.

In Add python 3.13 free-threaded build · Issue #320 · indygreg/python-build-standalone · GitHub @zanie pointed out that packaging projects that support retrieving and installing Python runtimes need to be more precise than that: they need a way for users to request the free threaded builds of exact versions like 3.13.0rc2, 3.13.0, 3.14.0a1, etc.

My suggestion is that affected projects adopt a convention of using an underscore separator when CPython only defines a feature release suffix. For freethreading in particular, that would give 3.13.0rc2_t, 3.13.0_t, 3.14.0a1_t, etc.

3 Likes
2

pyenv has been using the t suffix without the underscore for the exact versions too, since this PR Add 3.13.0b3t and exclude it from `pyenv latest` by colesbury · Pull Request #3001 · pyenv/pyenv · GitHub

The discussion before that might also be relevant Naming scheme for free-threaded Python · pyenv · Discussion #2998 · GitHub)

3

Omitting the underscore for any final release seems reasonable (3.13t and 3.13.0t aren’t that different visually), but I find the freethreading tag gets a bit lost without the underscore when it isn’t the only letter present (as in 3.13.0rc2t, 3.14.0a1t, etc)

Given that pyenv has already been running without the underscore for a while, though, the reasonable UX options seem to be:

  • only accept a simple t suffix, even for pre-releases (never accept _t)
  • accept a simple t suffix for final releases, accept a _t suffix for pre-releases
  • always accept either a t or _t suffix regardless of whether it’s a pre-release or a final release
1 Like
4

What about suggesting permissive in unambiguous user inputs, but normalized in tool generated outputs?

I don’t think users should get an error for including/not including an underscore, but I agree that when mixing release status with this that the underscore helps highlight it.

3 Likes
5

I like that idea.

Something like:

  • on user input, accept a t or _t suffix to request a free threaded build regardless of whether it’s a pre-release or a final release
  • in program output, emit a simple t suffix for feature release versions (to match CPython), but emit a _t suffix otherwise (to make it clearer this is an additional build variant flag rather than part of the version number)
  • prefer the normalised forms in documentation and examples

We should probably have a page on packaging.python.org referring to the free-threading project in general (not a lot of content, mainly links to other docs about how to support builds with free threading enabled), so this suggestion could go there.

1 Like
6

I found this page from the python 3.13 whatsnew documentation, which shows more alternatives already in use:

https://py-free-threading.github.io/installing_cpython/

And it seems there is a guidance about this from the steering council, to use freethreading, which Fedora and conda-forge have chosen:

The whole phrase freethreading is a bit too much I feel, so probably the t and _t suggestions discussed here are worth suggesting too.

7

Yeah, this is specifically about the shorthand forms.