Repository navigation
Inconsistent documentation: are interned strings immortal or not? #144161
Description
Activity
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:
Reacted by SviataslauMakes 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.
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.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.
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 withPyUnicode_InternFromString, I think?).On the free-threaded build, all interned strings are immortal. We should note that in the docs for
sys.internandPyUnicode_InternInPlace. More generally though, why is it useful to you to know whether a string is immortal or not? We did addPyUnstable_IsImmortalandsys._is_immortalin 3.14, but those were primarily for debugging/testing purposes.Why do you need to know? Generally, this is an implementation detail that can change between Python versions.
The
sys.interndocs could be clarified to say that “Interned strings are not necessarily immortal”. But unless you've checked withsys._is_immortalor are optimizing for a very specific CPython version, you do require a live reference.Since #144277 got merged, we can reopen the PR for this issue. Is anybody working on it?
Could you answer our questions above first? We'd like to know why you care about whether interned strings are immortal, and that context can hint as to what needs to change in the docs.
I personally do not care whether they are immortal or not. I usually keep references to interned strings, for example, in class namespaces, so they are basically immortal in the regular build too.
I wasn't familiar with free-threaded build, so I decided to learn more about it via HOWTO linked above. At first, I got an impression that immortalization is present only in the free-threaded build (that's not the case). At second, when I clicked on sys.intern() link in the paragraph about immortalization, I was met with the note that interned strings are not immortal and got confused. Changes introduced in #144176 are addressing both my concerns sufficiently.
Documentation
From HOWTO about python free-threading:
From sys.intern():
So, are the interned strings immortal or not?
Linked PRs