🎨 Rearrange numbers section

Author: veit

docs/appendix/checks.rst

@@ -50,8 +50,8 @@ Checks
   ``very_very_long_var_name``
       ✅ ok, but very long and therefore only recommended if you want to differentiate between many very similar variables
 
-:doc:`/types/numbers`
----------------------
+:doc:`/types/numbers/index`
+---------------------------
 
 * Create some number variables (integers, floating point numbers and complex
   numbers). Experiment a little with what happens when you perform operations
@@ -81,6 +81,9 @@ Checks
 
   .. blacken-docs:on
 
+:doc:`/types/numbers/complex`
+-----------------------------
+
 * Load the :mod:`math` module and try out some of the functions. Then load the
   :mod:`cmath` module and do the same.
 
@@ -101,6 +104,9 @@ Checks
      >>> sqrt(3)
      1.7320508075688772
 
+:doc:`/types/numbers/bool`
+--------------------------
+
 * Decide whether the following statements are true or false:
 
   * ``1`` → True

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 :doc:`/types/tuples`,
-:doc:`/types/strings/index` and :doc:`/types/numbers`, what is done with a
+: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 :doc:`/types/lists`, a :doc:`/types/dicts` or a class
 instance, any change to the object changes what the argument refers to outside

docs/libs/batteries.rst

@@ -3,7 +3,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
-:doc:`/types/numbers` and :doc:`/types/lists`, as well as some built-in
+:doc:`/types/numbers/index` and :doc:`/types/lists`, as well as some built-in
 :doc:`/functions/index` and :doc:`/control-flows/exceptions`. The largest part
 of the library is an extensive collection of :doc:`/modules/index`. If you have
 Python installed, there are also several libraries available for you to use.

docs/save-data/pickle.rst

@@ -40,7 +40,7 @@ this state in a file called ``data.pickle`` as follows:
    instances of user-defined classes. :py:func:`pickle.dump` saves everything.
 
    The pickle module can store almost anything in this way. It can handle
-   :doc:`/types/numbers`, :doc:`/types/lists`, :doc:`/types/tuples`,
+   :doc:`/types/numbers/index`, :doc:`/types/lists`, :doc:`/types/tuples`,
    :doc:`/types/dicts`, :doc:`/types/strings/index` and pretty much anything
    made up of these object types, including all class instances. It also
    handles shared objects, cyclic references and other complex storage

docs/types/dicts.rst

@@ -24,8 +24,8 @@ available.
     >>> x.get(5, "nicht vorhanden")
     'nicht vorhanden'
 
-Keys must be of immutable type, including :doc:`numbers`, :doc:`strings/index`
-and :doc:`tuples`.
+Keys must be of immutable type, including :doc:`numbers/index`,
+:doc:`strings/index` and :doc:`tuples`.
 
 .. warning::
    Even if you can use different key types in a dictionary, you should avoid

docs/types/index.rst

@@ -44,7 +44,7 @@ values to more complex structures like lists, dictionaries and files.
    :titlesonly:
    :hidden:
 
-   numbers
+   numbers/index
    lists
    tuples
    sets

docs/types/lists.rst

@@ -5,9 +5,9 @@ A list in Python is similar to an array in Java or C: an ordered collection of
 objects. However, unlike lists in many other languages, Python lists can contain
 different types of elements; a list element can be any Python object, including
 :doc:`strings/index`, :doc:`tuples`, :doc:`lists`, :doc:`dicts`,
-:doc:`../functions/index`, :doc:`files` and any kind of :doc:`numbers`. You
-create a list by enclosing no elements or elements separated by commas in square
-brackets, like this:
+:doc:`../functions/index`, :doc:`files` and any kind of :doc:`numbers/index`.
+You create a list by enclosing no elements or elements separated by commas in
+square brackets, like this:
 
 .. code-block:: python
    :linenos:
@@ -381,8 +381,8 @@ Minimum or maximum of a list
 
 You can use :func:`max` and :func:`min` to find the largest and smallest
 element of a list. You will probably use :func:`max` and :func:`min` mainly for
-:doc:`numeric </types/numbers>` lists, but you can also use them for lists with
-arbitrary elements; however, if the comparison of these types does not make
+:doc:`numeric </types/numbers/index>` lists, but you can also use them for lists
+with arbitrary elements; however, if the comparison of these types does not make
 sense, this will result in an error:
 
 .. code-block:: pycon

docs/types/none.rst

@@ -2,9 +2,9 @@ None
 ====
 
 In addition to the standard types such as :doc:`strings/index` and
-:doc:`numbers`, Python has a special data type that defines a single special
-data object called ``None``. As the name suggests, ``None`` is used to represent
-an empty value. It appears in various forms in Python.
+:doc:`numbers/index`, Python has a special data type that defines a single
+special data object called ``None``. As the name suggests, ``None`` is used to
+represent an empty value. It appears in various forms in Python.
 
 ``None`` is often useful in everyday Python programming as a placeholder to
 indicate a data structure where meaningful data can eventually be found, even if

docs/types/numbers/bool.rst

@@ -0,0 +1,33 @@
+Boolean values
+==============
+
+Boolean values are used in the following examples:
+
+.. code-block:: pycon
+
+    >>> x = False
+    >>> x
+    False
+    >>> not x
+    True
+
+.. code-block:: pycon
+
+    >>> y = True * 2
+    >>> y
+    2
+
+Apart from their representation as ``True`` and ``False``, Boolean values
+behave like the numbers ``1`` (``True``) and ``0`` (``False``).
+
+Checks
+------
+
+* Decide whether the following statements are true or false:
+
+  * ``1``
+  * ``0``
+  * ``-1``
+  * ``[0]``
+  * ``1 and 0``
+  * ``1 > 0 or []``

docs/types/numbers/complex.rst

@@ -0,0 +1,74 @@
+Complex numbers
+===============
+
+Complex numbers consist of a real part and an `imaginary part
+<https://en.wikipedia.org/wiki/Imaginary_number>`_, which is given the suffix
+``j`` in Python.
+
+.. code-block:: pycon
+
+    >>> 7 + 2j
+    (7+2j)
+
+.. note::
+
+    Python expresses the resulting complex number in parentheses to indicate
+    that the output represents the value of a single object:
+
+.. code-block:: pycon
+
+    >>> (5 + 3j) ** (3 + 5j)
+    (-7.04464115622119-11.276062812695923j)
+
+.. code-block:: pycon
+
+    >>> x = (5 + 3j) * (6 + 8j)
+    >>> x
+    (6+58j)
+    >>> x.real
+    6.0
+    >>> x.imag
+    58.0
+
+Complex numbers consist of a real part and an imaginary part with the suffix
+``j``. In the preceding code, the variable ``x`` is assigned to a complex
+number. You can get its „real“ part with the attribute notation ``x.real`` and
+the „imaginary“ part with ``x.imag``.
+
+Advanced functions
+------------------
+
+The functions in the :doc:`math <python3:library/math>` module are not
+applicable to complex numbers; one of the reasons for this is probably that the
+square root of ``-1`` is supposed to produce an error. Therefore, similar
+functions for complex numbers have been provided in the :doc:`cmath
+<python3:library/cmath>` module:
+
+:func:`python3:cmath.acos`, :func:`python3:cmath.acosh`, :func:`python3:cmath.asin`, :func:`python3:cmath.asinh`, :func:`python3:cmath.atan`, :func:`python3:cmath.atanh`, :func:`python3:cmath.cos`, :func:`python3:cmath.cosh`, :func:`python3:cmath.e`, :func:`python3:cmath.exp`, :func:`python3:cmath.log`, :func:`python3:cmath.log10`, :func:`python3:cmath.pi`, :func:`python3:cmath.sin`, :func:`python3:cmath.sinh`, :func:`python3:cmath.sqrt`, :func:`python3:cmath.tan`, :func:`python3:cmath.tanh`.
+
+To make it clear in the code that these functions are special functions for
+complex numbers, and to avoid name conflicts with the more normal equivalents,
+it is recommended to simply import the module to explicitly refer to the
+``cmath`` package when using the function, for example:
+
+.. code-block:: pycon
+
+    >>> import cmath
+    >>> cmath.sqrt(-2)
+    1.4142135623730951j
+
+.. warning::
+
+    Now it becomes clearer why we do not recommend importing all functions of a
+    module with :samp:`from {MODULE} import \*`. If you would import the module
+    ``math`` first and then the module ``cmath``, the functions in ``cmath``
+    would have priority over those of ``math``. Also, when understanding the
+    code, it is much more tedious to find out the source of the functions used.
+
+Checks
+------
+
+* Load the :mod:`math` module and try out some of the functions. Then load the
+  :mod:`cmath` module and do the same.
+
+* How can you restore the functions of the :mod:`math` module?