gh-113993: Don't immortalize in PyUnicode_InternInPlace; keep immortalizing in other API (#121364)

* Switch PyUnicode_InternInPlace to _PyUnicode_InternMortal, clarify docs

* Document immortality in some functions that take `const char *`

This is PyUnicode_InternFromString;
PyDict_SetItemString, PyObject_SetAttrString;
PyObject_DelAttrString; PyUnicode_InternFromString;
and the PyModule_Add convenience functions.

Always point out a non-immortalizing alternative.

* Don't immortalize user-provided attr names in _ctypes
This commit is contained in:
Petr Viktorin 2024-07-16 15:36:21 +02:00 committed by GitHub
parent d7a099d7ae
commit b4aedb23ae
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 82 additions and 10 deletions

View file

@ -1490,18 +1490,43 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
existing interned string that is the same as :c:expr:`*p_unicode`, it sets :c:expr:`*p_unicode` to
it (releasing the reference to the old string object and creating a new
:term:`strong reference` to the interned string object), otherwise it leaves
:c:expr:`*p_unicode` alone and interns it (creating a new :term:`strong reference`).
:c:expr:`*p_unicode` alone and interns it.
(Clarification: even though there is a lot of talk about references, think
of this function as reference-neutral; you own the object after the call
if and only if you owned it before the call.)
of this function as reference-neutral. You must own the object you pass in;
after the call you no longer own the passed-in reference, but you newly own
the result.)
This function never raises an exception.
On error, it leaves its argument unchanged without interning it.
Instances of subclasses of :py:class:`str` may not be interned, that is,
:c:expr:`PyUnicode_CheckExact(*p_unicode)` must be true. If it is not,
then -- as with any other error -- the argument is left unchanged.
Note that interned strings are not “immortal”.
You must keep a reference to the result to benefit from interning.
.. c:function:: PyObject* PyUnicode_InternFromString(const char *str)
A combination of :c:func:`PyUnicode_FromString` and
:c:func:`PyUnicode_InternInPlace`, returning either a new Unicode string
object that has been interned, or a new ("owned") reference to an earlier
interned string object with the same value.
:c:func:`PyUnicode_InternInPlace`, meant for statically allocated strings.
Return a new ("owned") reference to either a new Unicode string object
that has been interned, or an earlier interned string object with the
same value.
Python may keep a reference to the result, or make it :term:`immortal`,
preventing it from being garbage-collected promptly.
For interning an unbounded number of different strings, such as ones coming
from user input, prefer calling :c:func:`PyUnicode_FromString` and
:c:func:`PyUnicode_InternInPlace` directly.
.. impl-detail::
Strings interned this way are made :term:`immortal`.
PyUnicodeWriter
^^^^^^^^^^^^^^^