📝 Update the review of values and identity

veit · Feb 25, 2024 · 5a80132 · 5a80132
1 parent 4f72956
commit 5a80132
Show file tree

Hide file tree

Showing 2 changed files with 62 additions and 40 deletions.
diff --git a/docs/control-flows/boolean.rst b/docs/control-flows/boolean.rst
@@ -7,25 +7,50 @@ example, the empty list ``[]`` or the empty string ``""``) are all considered
 ``False``. The Boolean constant ``True`` and everything else is considered
 ``True``.
 
-You can create comparison expressions by using the comparison operators (``<``,
-``<=``, ``==``, ``>``, ``>=``, ``!=``, ``is``, ``is not``, ``in``, ``not in``)
-and the logical operators (``and``, ``not``, ``or``) , which all return ``True``
-or ``False``:
+``<``, ``<=``, ``==``, ``>``, ``>=``
+    compares values.
+``is``, ``is not``, ``in``, ``not in``
+    checks the identity.
+``and``, ``not``, ``or``
+    are logical operators that can be used to link the above checks.
 
 .. code-block:: python
 
-    >>> x = 3
-    >>> y = 3.0
-    >>> z = [3, 4, 5]
-    >>> x == y
-    True
-    >>> x is y
+   >>> x = 3
+   >>> y = 3.0
+   >>> z = [3, 4, 5]
+   >>> x == y
+   True
+   >>> x is y
+   False
+   >>> x is not y
+   True
+   >>> x in z
+   True
+   >>> id(x)
+   4375911432
+   >>> id(y)
+   4367574480
+   >>> id(z[0])
+   4375911432
+
+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`:
+
+.. code-block:: python
+
+    >>> x is None
     False
-    >>> x == y
-    True
-    >>> x in z
+    >>> 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 enter ``x
+is None`` instead.
+
 However, you should never compare calculated floating point numbers with each
 other:
 

diff --git a/docs/style.rst b/docs/style.rst
@@ -52,33 +52,30 @@ prescribed. However, there are preferred stylistic conventions for Python, which
 are contained in the *Python Enhancement Proposal* (PEP) 8. A selection of
 Python conventions can be found in the following table:
 
-+-----------------------+-----------------------+-------------------------------+
-| Context               | Recommendation        | Example                       |
-+=======================+=======================+===============================+
-| Module and package    | short, lower case,    | ``math``, ``sys``             |
-| names                 | underscores only if   |                               |
-|                       | necessary             |                               |
-+-----------------------+-----------------------+-------------------------------+
-| Function names        | lower case,           | ``my_func()``                 |
-|                       | underscores if        |                               |
-|                       | necessary             |                               |
-+-----------------------+-----------------------+-------------------------------+
-| Variable names        | lower case, with      | ``my_var``                    |
-|                       | underscores if        |                               |
-|                       | necessary             |                               |
-+-----------------------+-----------------------+-------------------------------+
-| Class names           | CamelCase notation    | ``MyClass``                   |
-+-----------------------+-----------------------+-------------------------------+
-| Constant names        | Capital letters with  | ``PI``                        |
-|                       | underscores           |                               |
-+-----------------------+-----------------------+-------------------------------+
-| Indentation           | Four spaces per level,|                               |
-|                       | no tabs               |                               |
-+-----------------------+-----------------------+-------------------------------+
-| Compare               | not explicitly with   | ``if my_var:``,               |
-|                       | ``True`` or           | ``if not my_var:``            |
-|                       | ``False``             |                               |
-+-----------------------+-----------------------+-------------------------------+
++-----------------------+-------------------------------+-------------------------------+
+| Context               | Recommendation                | Example                       |
++=======================+===============================+===============================+
+| Module and package    | short, lower case,            | ``math``, ``sys``             |
+| names                 | underscores only if necessary |                               |
++-----------------------+-------------------------------+-------------------------------+
+| Function names        | lower case, underscores if    | ``my_func()``                 |
+|                       | necessary                     |                               |
++-----------------------+-------------------------------+-------------------------------+
+| Variable names        | lower case, with underscores  | ``my_var``                    |
+|                       | if necessary                  |                               |
++-----------------------+-------------------------------+-------------------------------+
+| Class names           | CamelCase notation            | ``MyClass``                   |
++-----------------------+-------------------------------+-------------------------------+
+| Constant names        | Capital letters with          | ``PI``                        |
+|                       | underscores                   |                               |
++-----------------------+-------------------------------+-------------------------------+
+| Indentation           | Four spaces per level, no     |                               |
+|                       | tabs                          |                               |
++-----------------------+-------------------------------+-------------------------------+
+| Compare               | not explicitly with ``True``  | ``if my_var:``,               |
+|                       | or ``False``, see also        | ``if not my_var:``            |
+|                       | :doc:`control-flows/boolean`  |                               |
++-----------------------+-------------------------------+-------------------------------+
 
 .. seealso::