gh-110481, doc: Add "immortal" term to the glossary (#112180)

diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst
index b14fa6a0a982e25437ae0e63576a289ba51ead94..b4dc4849d044e1c6c3a3b215c30258769f17f39a 100644 (file)
--- a/Doc/c-api/bool.rst
+++ b/Doc/c-api/bool.rst
@@ -26,19 +26,19 @@ are available, however.
 .. c:var:: PyObject* Py_False
 
    The Python ``False`` object.  This object has no methods and is
-   `immortal <https://peps.python.org/pep-0683/>`_.
+   :term:`immortal`.
 
-.. versionchanged:: 3.12
-   :c:data:`Py_False` is immortal.
+   .. versionchanged:: 3.12
+      :c:data:`Py_False` is :term:`immortal`.
 
 
 .. c:var:: PyObject* Py_True
 
    The Python ``True`` object.  This object has no methods and is
-   `immortal <https://peps.python.org/pep-0683/>`_.
+   :term:`immortal`.
 
-.. versionchanged:: 3.12
-   :c:data:`Py_True` is immortal.
+   .. versionchanged:: 3.12
+      :c:data:`Py_True` is :term:`immortal`.
 
 
 .. c:macro:: Py_RETURN_FALSE

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index d164d1a752e2951f53b1814ebf607ba268ffc15e..e89641f74c7491e9906e5a19de272d37afd6f6c7 100644 (file)
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1485,7 +1485,7 @@ otherwise immutable (e.g. ``None``, ``(1, 5)``) can't normally be shared
 because of the refcount.  One simple but less-efficient approach around
 this is to use a global lock around all use of some state (or object).
 Alternately, effectively immutable objects (like integers or strings)
-can be made safe in spite of their refcounts by making them "immortal".
+can be made safe in spite of their refcounts by making them :term:`immortal`.
 In fact, this has been done for the builtin singletons, small integers,
 and a number of other builtin objects.
 

diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index 0c2ed8af33d43003d4d34ab8abdea2c2da349abe..47a8fbb2cd9c97e6129984e4de2c97a634a3e3bc 100644 (file)
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -1170,7 +1170,7 @@ PyConfig
 
    .. c:member:: int show_ref_count
 
-      Show total reference count at exit (excluding immortal objects)?
+      Show total reference count at exit (excluding :term:`immortal` objects)?
 
       Set to ``1`` by :option:`-X showrefcount <-X>` command line option.
 

diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst
index dd8bfb561042518effac3154023278f92b3f6d07..f1941fc4bc4e8502cc8fe84f736e39e5b91b5cdd 100644 (file)
--- a/Doc/c-api/none.rst
+++ b/Doc/c-api/none.rst
@@ -16,10 +16,10 @@ same reason.
 .. c:var:: PyObject* Py_None
 
    The Python ``None`` object, denoting lack of value.  This object has no methods
-   and is `immortal <https://peps.python.org/pep-0683/>`_.
+   and is :term:`immortal`.
 
-.. versionchanged:: 3.12
-   :c:data:`Py_None` is immortal.
+   .. versionchanged:: 3.12
+      :c:data:`Py_None` is :term:`immortal`.
 
 .. c:macro:: Py_RETURN_NONE
 

diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst
index 118af7a1a8cf90f4f5703ff3b7e66e28c854d655..68119a27b18ec2637497f796674cd6ed68e8227b 100644 (file)
--- a/Doc/c-api/refcounting.rst
+++ b/Doc/c-api/refcounting.rst
@@ -17,7 +17,7 @@ of Python objects.
 
    Note that the returned value may not actually reflect how many
    references to the object are actually held.  For example, some
-   objects are "immortal" and have a very high refcount that does not
+   objects are :term:`immortal` and have a very high refcount that does not
    reflect the actual number of references.  Consequently, do not rely
    on the returned value to be accurate, other than a value of 0 or 1.
 
@@ -34,9 +34,7 @@ of Python objects.
 
    Set the object *o* reference counter to *refcnt*.
 
-   Note that this function has no effect on
-   `immortal <https://peps.python.org/pep-0683/>`_
-   objects.
+   This function has no effect on :term:`immortal` objects.
 
    .. versionadded:: 3.9
 
@@ -49,6 +47,8 @@ of Python objects.
    Indicate taking a new :term:`strong reference` to object *o*,
    indicating it is in use and should not be destroyed.
 
+   This function has no effect on :term:`immortal` objects.
+
    This function is usually used to convert a :term:`borrowed reference` to a
    :term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be
    used to create a new :term:`strong reference`.
@@ -113,6 +113,8 @@ of Python objects.
    Release a :term:`strong reference` to object *o*, indicating the
    reference is no longer used.
 
+   This function has no effect on :term:`immortal` objects.
+
    Once the last :term:`strong reference` is released
    (i.e. the object's reference count reaches 0),
    the object's type's deallocation

diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index 9e880c6b7f25adbef823a5d8372a18750d6c28ce..27a1757c745d8bf216a579b91c54c8188f0b1b19 100644 (file)
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -119,8 +119,7 @@ Ellipsis Object
 .. c:var:: PyObject *Py_Ellipsis
 
    The Python ``Ellipsis`` object.  This object has no methods.  Like
-   :c:data:`Py_None`, it is an `immortal <https://peps.python.org/pep-0683/>`_.
-   singleton object.
+   :c:data:`Py_None`, it is an :term:`immortal` singleton object.
 
    .. versionchanged:: 3.12
       :c:data:`Py_Ellipsis` is immortal.

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index dad745348f9b4b8336b671dc2b31998c99a97469..6b517b95f97013856dc7bd69591efb6a2e14f3ee 100644 (file)
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -579,6 +579,16 @@ Glossary
       :ref:`idle` is a basic editor and interpreter environment
       which ships with the standard distribution of Python.
 
+   immortal
+      If an object is immortal, its reference count is never modified, and
+      therefore it is never deallocated.
+
+      Built-in strings and singletons are immortal objects. For example,
+      :const:`True` and :const:`None` singletons are immmortal.
+
+      See `PEP 683 – Immortal Objects, Using a Fixed Refcount
+      <https://peps.python.org/pep-0683/>`_ for more information.
+
    immutable
       An object with a fixed value.  Immutable objects include numbers, strings and
       tuples.  Such an object cannot be altered.  A new object has to
@@ -1056,7 +1066,7 @@ Glossary
    reference count
       The number of references to an object.  When the reference count of an
       object drops to zero, it is deallocated.  Some objects are
-      "immortal" and have reference counts that are never modified, and
+      :term:`immortal` and have reference counts that are never modified, and
       therefore the objects are never deallocated.  Reference counting is
       generally not visible to Python code, but it is a key element of the
       :term:`CPython` implementation.  Programmers can call the

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 4d24606a1653e5277552253f0d6d39d26683551e..bf9aaca2a696ded98ce94941cbdae31016463a77 100644 (file)
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -831,7 +831,7 @@ always available.
 
    Note that the returned value may not actually reflect how many
    references to the object are actually held.  For example, some
-   objects are "immortal" and have a very high refcount that does not
+   objects are :term:`immortal` and have a very high refcount that does not
    reflect the actual number of references.  Consequently, do not rely
    on the returned value to be accurate, other than a value of 0 or 1.
 
@@ -1182,8 +1182,8 @@ always available.
    names used in Python programs are automatically interned, and the dictionaries
    used to hold module, class or instance attributes have interned keys.
 
-   Interned strings are not immortal; you must keep a reference to the return
-   value of :func:`intern` around to benefit from it.
+   Interned strings are not :term:`immortal`; you must keep a reference to the
+   return value of :func:`intern` around to benefit from it.
 
 
 .. function:: is_finalizing()