Inconsistent documentation: are interned strings immortal or not?

[Prometheus3375]

Documentation

From HOWTO about python free-threading:

As of the 3.14 release, immortalization is limited to:

• Code constants: numeric literals, string literals, and tuple literals composed of other constants.
• Strings interned by sys.intern().

From sys.intern():

Interned strings are not immortal; you must keep a reference to the return value of intern() around to benefit from it.

So, are the interned strings immortal or not?

Linked PRs

• gh-144161: Clarify additional immortalization in free-threaded build #144176

[whyvineet]

As per my understanding, interned strings are immortal only in the free-threaded (no-GIL) build of Python 3.14. The free-threading HOWTO explicitly lists “strings interned by sys.intern()” among immortalized objects.

The sys.intern() documentation describes the general (non-free-threaded) behaviour, where interned strings are still mortal and require a live reference.

So the two passages refer to different configurations... the distinction likely just needs to be made explicit in the docs.

This is what I found, which can be relevant:

• https://docs.python.org/3/howto/free-threading-python.html
• Free threading docs for 3.14 still describe it as an "expected" release #137232
• Interned strings are immortal, despite what the documentation says #113993
• https://github.com/python/cpython/blob/main/InternalDocs/string_interning.md

[Prometheus3375]

Makes sense, in one thread I found such suggestion.

Depending on the Python version and implementation, interned strings may or may not be immortal; ...

Though it can be more specific.

[Prometheus3375]

I think for now it is better to modify HOWTO instead. I propose such changes:

In the free-threaded build, some objects are immortal.

The free-threaded build introduces some additional immortal objects.

And

As of the 3.14 release, immortalization is limited to: ...

As of the 3.14 release, the additional immortalization is limited to: ...

That way it is clear that immortalization of the listed objects is an addition and not the default behavior. In the regular build there are also some immortal objects like True; hence, sentence "In the free-threaded build, some objects are immortal" doesn't feel like an addition.

[whyvineet]

I do agree with you... they highlight the inconsistencies clearly and make a solid case for clarifying the behaviour of interned strings. It would be helpful to loop in @rhettinger here, since a documentation update could resolve the confusion and ensure consistency.

[ZeroIntensity]

The relevant interned strings expert is @encukou.

On the GILicious build, interned string can be immortal or mortal, so there's not a clear answer here. I believe all literal strings are immortal (e.g., if you were to do x = "hello", then "hello" would be immortal), as well as other strings embedded into the runtime (strings such as dunder method names or 1-char strings). All strings interned by the user are mortal (except when used with PyUnicode_InternFromString, I think?).

On the free-threaded build, all interned strings are immortal. We should note that in the docs for sys.intern and PyUnicode_InternInPlace. More generally though, why is it useful to you to know whether a string is immortal or not? We did add PyUnstable_IsImmortal and sys._is_immortal in 3.14, but those were primarily for debugging/testing purposes.

[encukou]

Why do you need to know? Generally, this is an implementation detail that can change between Python versions.

The sys.intern docs could be clarified to say that “Interned strings are not necessarily immortal”. But unless you've checked with sys._is_immortal or are optimizing for a very specific CPython version, you do require a live reference.