🎨 Rearrange sequences and sets

Author: veit

docs/appendix/checks.rst

@@ -116,8 +116,8 @@ Checks
   * ``1 and 0`` → False
   * ``1 > 0 or []`` → True
 
-:doc:`/types/lists`
--------------------
+:doc:`/types/sequences-sets/lists`
+----------------------------------
 
 * What does :func:`len` return for each of the following cases:
 
@@ -167,7 +167,7 @@ Checks
   .. note::
      This code only removes the first occurrence of ``i``. To remove all
      occurrences of ``i`` from the list, the list could be converted to the
-     :doc:`set </types/sets>` type, for example:
+     :doc:`set </types/sequences-sets/sets>` type, for example:
 
      .. code-block:: pycon
 
@@ -198,8 +198,8 @@ Checks
 
 * What other options could you have besides explicitly checking the type?
 
-:doc:`/types/tuples`
---------------------
+:doc:`/types/sequences-sets/tuples`
+-----------------------------------
 
 * Explain why the following operations cannot be applied to the tuple ``t``:
 
@@ -216,8 +216,8 @@ Checks
 
      >>> sorted(t)
 
-:doc:`/types/sets`
-------------------
+:doc:`/types/sequences-sets/sets`
+---------------------------------
 
 * How many elements does a set have if it is formed from the following list
   ``[4, 2, 3, 2, 1]``?
@@ -267,8 +267,8 @@ Checks
      >>> d[("Veit", "Tim", "Monique")] = None
 
 * You can use a :doc:`Dictionary </types/dicts>` like a spreadsheet table by
-  using :doc:`/types/tuples` as key row and column values. Write sample code to
-  add and retrieve values.
+  using :doc:`/types/sequences-sets/tuples` as key row and column values. Write
+  sample code to add and retrieve values.
 
   .. code-block:: pycon
 

docs/control-flows/loops.rst

@@ -59,8 +59,9 @@ Line 5
 The ``for`` loop is simple but powerful because it can iterate over any iterable
 type, such as a list or a tuple. Unlike many other languages, the ``for`` loop
 in Python iterates over every element in a sequence for example a :doc:`list
-<../types/lists>` or a :doc:`tuple <../types/tuples>`), which makes it more like
-a foreach loop. The following loop uses the `Modulo
+<../types/sequences-sets/lists>` or a :doc:`tuple
+<../types/sequences-sets/tuples>`), which makes it more like a foreach loop. The
+following loop uses the `Modulo
 <https://en.wikipedia.org/wiki/Modulo_operation>`_ operator ``%`` as a condition
 for the first occurrence of an integer divisible by ``5``:
 
@@ -138,9 +139,10 @@ Each list comprehension in Python contains three elements:
     is the object or the value in an :samp:`{ITERABLE}`. In the example above,
     the value is ``i``.
 :samp:`{ITERABLE}`
-    is a :doc:`list <../types/lists>`, a :doc:`set <../types/sets>`, a generator
-    or another object that can return its elements individually. In the example
-    above, the iterable is ``range(8)``.
+    is a :doc:`list <../types/sequences-sets/lists>`, a :doc:`set
+    <../types/sequences-sets/sets>`, a generator or another object that can
+    return its elements individually. In the example above, the iterable is
+    ``range(8)``.
 
 You can also use optional conditions with list comprehensions, which are usually
 appended to the end of the expression:

docs/functions/params.rst

@@ -150,9 +150,9 @@ Variable number of arguments
 
 Python functions can also be defined to handle a variable number of arguments.
 This is possible in two ways. One method collects an unknown number of arguments
-in a :doc:`list </types/lists>`. The other method can collect an arbitrary
-number of arguments passed with a keyword that has no correspondingly named
-parameter in the function parameter list in a :doc:`dict </types/dicts>`.
+in a :doc:`list </types/sequences-sets/lists>`. The other method can collect an
+arbitrary number of arguments passed with a keyword that has no correspondingly
+named parameter in the function parameter list in a :doc:`dict </types/dicts>`.
 
 For an indeterminate number of positional arguments, prefixing the function’s
 final parameter name with a ``*`` causes all excess non-keyword arguments in a
@@ -223,12 +223,13 @@ 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/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
-the function. Reassigning the parameter has no effect on the argument.
+to the object. With 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
+:doc:`/types/sequences-sets/lists`, a :doc:`/types/dicts` or a class instance,
+any change to the object changes what the argument refers to outside the
+function. Reassigning the parameter has no effect on the argument.
 
 .. code-block:: pycon
 

docs/libs/batteries.rst

@@ -3,10 +3,11 @@
 
 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/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.
+:doc:`/types/numbers/index` and :doc:`/types/sequences-sets/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.
 
 * :ref:`data-types`
 * :ref:`files-storage`
@@ -61,7 +62,7 @@ Modules for data types
 Modules for numbers
 ~~~~~~~~~~~~~~~~~~~
 
-.. include:: ../types/numbers.rst
+.. include:: ../types/numbers/index.rst
    :start-after: number-modules:
    :end-before: end-number-modules:
 

docs/save-data/pickle.rst

@@ -40,12 +40,13 @@ 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/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
-   structures correctly by storing shared objects only once and restoring them
-   as shared objects, not as identical copies.
+   :doc:`/types/numbers/index`, :doc:`/types/sequences-sets/lists`,
+   :doc:`/types/sequences-sets/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 structures correctly by storing
+   shared objects only once and restoring them as shared objects, not as
+   identical copies.
 
 #. Loading pickled data:
 

docs/types/dicts.rst

@@ -4,11 +4,11 @@ Dictionaries
 Python’s built-in dictionary data type provides associative array functionality
 implemented using hash tables. The built-in ``len`` function returns the number
 of key-value pairs in a dictionary. The ``del`` statement can be used to delete
-a key-value pair. As with :doc:`lists` , several dictionary methods
-(:py:meth:`clear <dict.clear>`, :py:meth:`copy <dict.copy>`, :py:meth:`get
-<dict.get>`, :py:meth:`items <dict.items>`, :py:meth:`keys <dict.keys>`,
-:py:meth:`update <dict.update>` and :py:meth:`values <dict.values>`) are
-available.
+a key-value pair. As with :doc:`sequences-sets/lists` , several dictionary
+methods (:py:meth:`clear <dict.clear>`, :py:meth:`copy <dict.copy>`,
+:py:meth:`get <dict.get>`, :py:meth:`items <dict.items>`, :py:meth:`keys
+<dict.keys>`, :py:meth:`update <dict.update>` and :py:meth:`values
+<dict.values>`) are available.
 
 .. code-block:: pycon
 
@@ -25,18 +25,18 @@ available.
     'nicht vorhanden'
 
 Keys must be of immutable type, including :doc:`numbers/index`,
-:doc:`strings/index` and :doc:`tuples`.
+:doc:`strings/index` and :doc:`sequences-sets/tuples`.
 
 .. warning::
    Even if you can use different key types in a dictionary, you should avoid
    this, as it not only makes it more difficult to read, but also sorting is
    also made more difficult.
 
-Values can be any type of object, including mutable types such as :doc:`lists`
-and :doc:`dicts`. If you try to access the value of a key that is not in the
-dictionary, a ``KeyError`` exception is thrown. To avoid this error, the
-dictionary method ``get`` optionally returns a custom value if a key is not
-contained in a dictionary.
+Values can be any type of object, including mutable types such as
+:doc:`sequences-sets/lists` and :doc:`dicts`. If you try to access the value of
+a key that is not in the dictionary, a ``KeyError`` exception is thrown. To
+avoid this error, the dictionary method ``get`` optionally returns a custom
+value if a key is not contained in a dictionary.
 
 ``setdefault``
 --------------
@@ -134,8 +134,8 @@ Checks
      >>> d[("Veit", "Tim", "Monique")] = None
 
 * You can use a :doc:`Dictionary </types/dicts>` like a spreadsheet table by
-  using :doc:`/types/tuples` as key row and column values. Write sample code to
-  add and retrieve values.
+  using :doc:`/types/sequences-sets/tuples` as key row and column values. Write
+  sample code to add and retrieve values.
 
   .. code-block:: pycon
 

docs/types/index.rst

@@ -45,9 +45,7 @@ values to more complex structures like lists, dictionaries and files.
    :hidden:
 
    numbers/index
-   lists
-   tuples
-   sets
+   sequences-sets/index
    dicts
    strings/index
    files

docs/types/sequences-sets/index.rst

@@ -0,0 +1,25 @@
+Sequences and Sets
+==================
+
+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    |
++===============+===============+===============+===============+===============+
+| List          | ✅            | ✅            | ✅            | ✅            |
++---------------+---------------+---------------+---------------+---------------+
+| Tuple         | ❌            | ✅            | ✅            | ✅            |
++---------------+---------------+---------------+---------------+---------------+
+| Set           | ✅            | ❌            | ❌            | ❌            |
++---------------+---------------+---------------+---------------+---------------+
+| Frozenset     | ❌            | ❌            | ❌            | ❌            |
++---------------+---------------+---------------+---------------+---------------+
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   lists
+   tuples
+   sets

docs/types/lists.rst docs/types/sequences-sets/lists.rstdocs/types/lists.rst renamed to docs/types/sequences-sets/lists.rst

@@ -4,10 +4,10 @@ Lists
 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/index`.
-You create a list by enclosing no elements or elements separated by commas in
-square brackets, like this:
+:doc:`../strings/index`, :doc:`tuples`, :doc:`lists`, :doc:`../dicts`,
+: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:
@@ -283,9 +283,9 @@ User-defined sorting
 ::::::::::::::::::::
 
 .. note::
-   You must be able to define :doc:`../functions/index` for user-defined
-   sorting. The processing of :doc:`strings/index` will also be covered in more
-   detail later.
+   You must be able to define :doc:`../../functions/index` for user-defined
+   sorting. The processing of :doc:`../strings/index` will also be covered in
+   more detail later.
 
 Python usually sorts words lexicographically – upper case before lower case.
 However, we want to sort a list of words by the number of characters in each
@@ -309,11 +309,11 @@ The ``sorted`` function
 :::::::::::::::::::::::
 
 Lists have an inbuilt method for sorting themselves :meth:`python3:list.sort`.
-However, other iterables in Python, such as the keys of :doc:`dicts`, do not
+However, other iterables in Python, such as the keys of :doc:`../dicts`, do not
 have a sorting method. However, Python offers the built-in
 :func:`python3:sorted` function for this purpose, which returns a sorted list
 from any iterable. :func:`python3:sorted` uses the same
-:doc:`../functions/params` ``key`` and ``reverse`` as the
+:doc:`../../functions/params` ``key`` and ``reverse`` as the
 :meth:`python3:list.sort` method:
 
 .. code-block:: pycon
@@ -532,15 +532,6 @@ has any effect on the original list:
    >>> sup
    [[0], 1]
 
-Summary
--------
-
-+---------------+---------------+---------------+---------------+---------------+
-| data type     | mutable       | ordered       | indexed       | duplicates    |
-+===============+===============+===============+===============+===============+
-| list          | ✅            | ✅            | ✅            | ✅            |
-+---------------+---------------+---------------+---------------+---------------+
-
 Checks
 ------
 

docs/types/sets.rst docs/types/sequences-sets/sets.rstdocs/types/sets.rst renamed to docs/types/sequences-sets/sets.rst

@@ -6,6 +6,8 @@ situations where membership and uniqueness to the set are the most important
 information of the object. The ``in`` operator runs faster with sets than with
 :doc:`lists`:
 
+.. _set:
+
 ``set``
 -------
 
@@ -53,6 +55,8 @@ Line 19
     ``^`` is used to find the symmetrical difference, meaning elements that are
     contained in one or the other set, but not in both.
 
+.. _frozenset:
+
 ``frozenset``
 -------------
 
@@ -74,22 +78,14 @@ means that they can also be members of other sets:
    >>> x
    {1, 2, 3, 4, frozenset({1, 2, 3, 4})}
 
-Summary
--------
+Order
+-----
 
 However, the speed advantage also comes at a price: sets do not keep the
 elements in the correct order, whereas :doc:`lists` and :doc:`tuples` do. If the
 order is important to you, you should use a data structure that remembers the
 order.
 
-+---------------+---------------+---------------+---------------+---------------+
-| data type     | mutable       | ordered       | indexed       | duplicates    |
-+===============+===============+===============+===============+===============+
-| Sets          | ✅            | ❌            | ❌            | ❌            |
-+---------------+---------------+---------------+---------------+---------------+
-| Frozensets    | ❌            | ❌            | ❌            | ❌            |
-+---------------+---------------+---------------+---------------+---------------+
-
 Checks
 ------