📝 Update glossary

veit · veit · commit 1311089b742a · 2025-01-21T16:02:03.000+01:00
* Add constant, singleton and immutable objects
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -32,6 +32,10 @@ Added
 Changed
 ~~~~~~~
 
+* 📝  Update glossary
+
+  * Add constant, singleton and immutable objects
+
 * 📝 Update uv sections
 
   * Reproducing and updating uv environments
diff --git a/docs/appendix/glossary.rst b/docs/appendix/glossary.rst
@@ -16,6 +16,12 @@ Glossary
            at the beginning of an argument list and/or passed as elements of an
            iteration preceded by ``*``.
 
+
+   Constant
+       Python has :term:`immutable` objects, but no constant variables.
+       Variables refer to objects, but there is no way to prevent a new
+       assignment from being made.
+
    Control flow
        Time sequence of the individual commands of a computer program.
 
@@ -95,6 +101,11 @@ Glossary
        .. seealso::
           * :py:mod:`gc`
 
+   Immutable
+       An object that cannot be mutated. The value of an immutable object cannot
+       change. :doc:`Tuples <../types/sequences-sets/tuples>` are examples of
+       immutable objects.
+
    LBYL
        Look before you leap. With this style, the preconditions are explicitly
        checked before the call. This style is in contrast to the :term:`EAFP`
@@ -111,6 +122,10 @@ Glossary
        .. seealso::
           * :doc:`/functions/params`
 
+   Singleton object
+       A singleton class can only create one instance of itself.
+       :doc:`../types/none` is an example of a singleton class in Python.
+
    Zen of Python
        Listing of Python design principles and philosophies that are helpful for
        understanding and using the language. The list can be output by entering
@@ -459,7 +474,6 @@ Glossary
           * `GitHub <https://github.com/scikit-build/scikit-build>`__
           * `PyPI <https://pypi.org/project/scikit-build>`__
 
-
    setuptools
        setuptools are the classic build system, which is very powerful, but with
        a steep learning curve and high configuration effort. From version
diff --git a/docs/control-flow/boolean.rst b/docs/control-flow/boolean.rst
@@ -53,8 +53,10 @@ considered ``True``.
     If ``x`` and ``z[0]`` have the same ID in memory, this means that we are
     referring to the same object in two places.
 
-    Most frequently, ``is`` and ``is not`` are used in conjunction with
-    :doc:`../types/none`:
+    The ``is`` operator is mostly used for values that only exist once in
+    memory, so-called :term:`singleton objects <Singleton object>`. For example,
+    checking for :doc:`../types/none` is the most common use of the ``is``
+    operator.
 
     .. code-block:: pycon
 
@@ -63,9 +65,9 @@ considered ``True``.
        >>> x is not None
        True
 
-    The Python style guide in :pep:`8` says that you should use identity to
-    compare with :doc:`../types/none`. So you should never use ``x == None``,
-    but ``x is None`` instead.
+    The Python style guide in :pep:`8` also recommends that you should check for
+    identity with :doc:`../types/none` and not for values, so never use ``x ==
+    None``, but always use ``x is None``  instead.
 
 ``and``, ``not``, ``or``
     are logical operators that we can use to link the above checks:
diff --git a/docs/functions/params.rst b/docs/functions/params.rst
@@ -224,7 +224,7 @@ Mutable objects as arguments
 ----------------------------
 
 Arguments are passed by object reference. The parameter becomes a new reference
-to the object. With immutable objects such as
+to the object. With :term:`immutable` objects such as
 :doc:`/types/sequences-sets/tuples`, :doc:`/types/strings/index` and
 :doc:`/types/numbers/index`, what is done with a parameter has no effect
 outside the function. However, if you pass a mutable object, such as a
@@ -244,7 +244,7 @@ function. Reassigning the parameter has no effect on the argument.
     >>> x, y
     (5, [2, 4, 6, 1])
 
-The variable ``x`` is not changed because it is unchangeable. Instead, the
+The variable ``x`` is not changed because it is :term:`immutable`. Instead, the
 function parameter ``n`` is set so that it refers to the new value ``6``.
 However, there is a change in ``y`` because the list it refers to has been
 changed.
diff --git a/docs/libs/batteries.rst b/docs/libs/batteries.rst
@@ -2,7 +2,7 @@
 ======================
 
 In Python, a library can consist of several components, including built-in data
-types and constants that can be used without an import statement, such as
+types and variables that can be used without an import statement, such as
 :doc:`/types/numbers/index` and :doc:`/types/sequences-sets/lists`, as well as
 some built-in :doc:`/functions/index` and :doc:`/control-flow/exceptions`. The
 largest part of the library is an extensive collection of :doc:`/modules/index`.
diff --git a/docs/packs/distribution.rst b/docs/packs/distribution.rst
@@ -340,7 +340,7 @@ directory.
 
 :file:`loaders.py`
     is an example of a module within the package that could contain the logic
-    (functions, classes, constants, :abbr:`etc. (et cetera)`) of your package.
+    (functions, classes, variables, :abbr:`etc. (et cetera)`) of your package.
 
 Other files
 -----------
diff --git a/docs/save-data/filesystem.rst b/docs/save-data/filesystem.rst
@@ -26,7 +26,7 @@ has a separate root directory for each drive, referred to as :samp:`{C:\\}`, and
 so on. Because of these differences, files have different path names on
 different operating systems. A file named :samp:`{C:\\DATA\\MYFILE}` on Windows
 could be :samp:`{/DATA/MYFILE}` on Linux and macOS. Python provides functions
-and constants that allow you to perform common pathname manipulations without
+and variables that allow you to perform common pathname manipulations without
 having to worry about such syntactical details. With a little care, you can
 write your Python programs to run correctly regardless of the underlying file
 system.
@@ -109,12 +109,12 @@ Relative pathnames
 
       .. note::
          ``os.getcwd()`` is used as a function call without arguments to make it
-         clear that the returned value is not a constant, but changes when you
-         change the value of the current working directory. In the example
-         above, the result is the home directory on one of my Linux machines. On
-         Windows machines, additional backslashes would be added to the path:
-         ``C:\\Users\\Veit``, because Windows uses the backslash ``\`` as a path
-         separator, but it has a different meaning in
+         clear that the returned value is not a :term:`constant`, but changes
+         when you change the value of the current working directory. In the
+         example above, the result is the home directory on one of my Linux
+         machines. On Windows machines, additional backslashes would be added to
+         the path: ``C:\\Users\\Veit``, because Windows uses the backslash ``\``
+         as a path separator, but it has a different meaning in
          :doc:`/types/strings/index`.
 
       To display the contents of the current directory, you can enter the
@@ -244,7 +244,7 @@ operating system-specific syntax.
        >>> os.path.expandvars("$HOME/python-basics-tutorial")
        '/home/veit/python-basics-tutorial'
 
-Useful constants and functions
+Useful variables and functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :data:`python3:os.name`
diff --git a/docs/style.rst b/docs/style.rst
@@ -67,8 +67,8 @@ Python conventions can be found in the following table:
 +-----------------------+-------------------------------+-------------------------------+
 | Class names           | CamelCase notation            | ``MyClass``                   |
 +-----------------------+-------------------------------+-------------------------------+
-| Constant names        | Capital letters with          | ``PI``                        |
-|                       | underscores                   |                               |
+| :term:`Constant`      | Capital letters with          | ``PI``                        |
+|  names                | underscores                   |                               |
 +-----------------------+-------------------------------+-------------------------------+
 | Indentation           | Four spaces per level, no     |                               |
 |                       | tabs                          |                               |
diff --git a/docs/types/numbers/index.rst b/docs/types/numbers/index.rst
@@ -112,7 +112,7 @@ Advanced numerical functions
 ----------------------------
 
 More advanced numerical functions such as trigonometry, as well as some useful
-constants, are not built into Python, but are provided in a standard module
+variables, are not built into Python, but are provided in a standard module
 called :doc:`math <python3:library/math>`. :doc:`Module </modules/index>` will
 be explained in more detail later. For now, suffice it to say that you need to
 make the maths functions available in this section by importing ``math``:
@@ -153,7 +153,7 @@ The ``math`` module provides, among other things
   :func:`python3:math.sin`,
 * the hyperbolic functions :func:`python3:math.cosh`,
   :func:`python3:math.sinh` and :func:`python3:math.tanh`
-* and the constants :data:`python3:math.e` and :data:`python3:math.pi`.
+* and the variables :data:`python3:math.e` and :data:`python3:math.pi`.
 
 Rounding half to even
 ---------------------
diff --git a/docs/types/sequences-sets/index.rst b/docs/types/sequences-sets/index.rst
@@ -5,7 +5,8 @@ Sequences (:doc:`lists` and :doc:`tuples`) and sets (:ref:`set` and
 :ref:`frozenset`) essentially differ in the following properties:
 
 +---------------+---------------+---------------+---------------+---------------+
-| Data type     | mutable       | ordered       | indexed       | duplicates    |
+| Data type     | :term:`mutable| ordered       | indexed       | duplicates    |
+|               | <immutable>`  |               |               |               |
 +===============+===============+===============+===============+===============+
 | List          | ✅            | ✅            | ✅            | ✅            |
 +---------------+---------------+---------------+---------------+---------------+
diff --git a/docs/types/sequences-sets/sets.rst b/docs/types/sequences-sets/sets.rst
@@ -94,8 +94,8 @@ Difference or remainder set
 ``frozenset``
 -------------
 
-In addition to ``set``, there is also ``frozenset``, an immutable data type. This
-means that they can also be members of other sets:
+In addition to ``set``, there is also ``frozenset``, an :term:`immutable` data
+type. This means that they can also be members of other sets:
 
 .. code-block:: pycon
    :linenos:
diff --git a/docs/types/strings/built-in-modules/index.rst b/docs/types/strings/built-in-modules/index.rst
@@ -9,7 +9,7 @@ use to manage strings:
 +-----------------------+-------------------------------------------------------------------------------+
 | Module                | Description                                                                   |
 +=======================+===============================================================================+
-| :py:mod:`string`      | compares with constants such as :py:data:`string.digits` or                   |
+| :py:mod:`string`      | compares with variables such as :py:data:`string.digits` or                   |
 |                       | :py:data:`string.whitespace`                                                  |
 +-----------------------+-------------------------------------------------------------------------------+
 | :py:mod:`re`          | searches and replaces text with regular expressions                           |
diff --git a/docs/types/strings/built-in-modules/string.rst b/docs/types/strings/built-in-modules/string.rst
@@ -172,7 +172,7 @@ the spaces at the left or right end of the original string:
 
 In this example, the newlines ``\n`` are regarded as whitespace. The exact
 assignment may differ from operating system to operating system. You can find
-out what Python considers to be whitespace by accessing the constant
+out what Python considers to be whitespace by accessing the variable
 :py:data:`string.whitespace`. For me, the following is returned:
 
 .. code-block:: pycon
@@ -268,8 +268,8 @@ character string:
 Changing strings
 ----------------
 
-:ref:`str <python3:textseq>` are immutable, but they have several methods that
-can return a modified version of the original string.
+:ref:`str <python3:textseq>` are :term:`immutable`, but they have several methods
+that can return a modified version of the original string.
 
 :py:meth:`str.replace` can be used to replace occurrences of the first
  :doc:`parameter <../../../functions/params>` with the second, for example:
diff --git a/docs/types/strings/encodings.rst b/docs/types/strings/encodings.rst
@@ -53,24 +53,21 @@ The ``string`` module
 ---------------------
 
 Python’s :doc:`string <python3:library/string>` module distinguishes the
-following string constants, all of which fall into the ASCII character set:
-
-.. code-block:: python
-
-    # Some strings for ctype-style character classification
-    whitespace = " \t\n\r\v\f"
-    ascii_lowercase = "abcdefghijklmnopqrstuvwxyz"
-    ascii_uppercase = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
-    ascii_letters = ascii_lowercase + ascii_uppercase
-    digits = "0123456789"
-    hexdigits = digits + "abcdef" + "ABCDEF"
-    octdigits = "01234567"
-    punctuation = r"""!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~"""
-    printable = digits + ascii_letters + punctuation + whitespace
-
-Most of these constants should be self-explanatory in their identifier names.
+following string variables, all of which fall into the ASCII character set:
+
+* :py:data:`string.whitespace` ``= " \t\n\r\v\f"``
+* :py:data:`string.ascii_lowercase` ``= "abcdefghijklmnopqrstuvwxyz"``
+* :py:data:`string.ascii_uppercase` ``= "ABCDEFGHIJKLMNOPQRSTUVWXYZ"``
+* :py:data:`string.ascii_letters` ``= ascii_lowercase + ascii_uppercase``
+* :py:data:`string.digits` ``= "0123456789"``
+* :py:data:`string.hexdigits` ``= digits + "abcdef" + "ABCDEF"``
+* :py:data:`string.octdigits` ``= "01234567"``
+* :py:data:`string.punctuation` ``= r"""!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~"""``
+* :py:data:`string.printable` ``= digits + ascii_letters + punctuation + whitespace``
+
+Most of these variables should be self-explanatory in their identifier names.
 ``hexdigits`` and ``octdigits`` refer to the hexadecimal and octal values
-respectively. You can use these constants for everyday string manipulation:
+respectively. You can use these variables for everyday string manipulation:
 
 .. code-block:: pycon
 
diff --git a/docs/types/strings/operators-functions.rst b/docs/types/strings/operators-functions.rst
@@ -35,7 +35,7 @@ or slices:
    'pythonistas!'
 
 However, the index and slice notation cannot be used to add, remove or replace
-elements, as character strings are immutable:
+elements, as character strings are :term:`immutable`:
 
 .. code-block:: pycon
 
@@ -95,8 +95,8 @@ Lines 13–16
 Changing character strings with list manipulations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Since :ref:`str <python3:textseq>` objects are immutable, there is no way to
-change them directly like :doc:`lists <../sequences-sets/lists>`. However, you
+Since :ref:`str <python3:textseq>` objects are :term:`immutable`, there is no way
+to change them directly like :doc:`lists <../sequences-sets/lists>`. However, you
 can convert them into lists:
 
 .. code-block:: pycon
diff --git a/docs/variables-expressions.rst b/docs/variables-expressions.rst
@@ -42,9 +42,9 @@ for the first time.
       1 4 1
 
    In this case, after the third line, ``x``, ``y`` and ``z`` all refer to the
-   same immutable integer object with the value ``1``. The next line, ``y = 4``,
-   causes ``y`` to refer to the integer object ``4``, but this does not change
-   the references of ``x`` or ``z``.
+   same :term:`immutable` integer object with the value ``1``. The next line,
+   ``y = 4``, causes ``y`` to refer to the integer object ``4``, but this does
+   not change the references of ``x`` or ``z``.
 
 Python variables can be set to any object, whereas in many other languages
 variables can only be stored in the declared type.
