Balls
=====

Let's consider the following two dictionaries:

    #. A dictionary, we shall call *id_city_D*, where the key is an :class:`int` with a person's *ID number* and the value is a :class:`str` with the name of her/his city of residence. For example:

        .. literalinclude:: ballsD_gen.test
            :language: python3
            :start-after: --ini11
            :end-before: --fi11

    #. A dictionary, we shall call *id_balls_D*, where the key is an :class:`int` with a person's *ID number* and the associated value is a :class:`list` of  :class:`str` with the name of the *swing and blues dances* that person likes to dance. For example:

        .. literalinclude:: ballsD_gen.test
            :language: python3
            :start-after: --ini12
            :end-before: --fi12

In this context, you are required to deliver the following functions in the module :mod:`balls` (file :file:`balls.py`):

------------------------------------------------------------------------------------------------

The first function is:

    .. py:function:: ballsD_inv(id_city_D, id_balls_D)

such that

    **given** *id_city_D*, *id_balls_D*,  :class:`dict` as described above.

    **returns** the inverted :class:`dict` of *id_balls_D* but only with the persons included in *id_city_D*,
    namely a :class:`dict` where keys are the dance names (:class:`str`) in *id_balls_D*
    and the associated value to each dance is a list of the dancers that like that dance
    and have a key in *id_city_D*.

For example:

    .. literalinclude:: ballsD_inv.test
        :language: python3
        :start-after: --ini
        :end-before: --fi

Observe that the id ``44555666`` is not included anywhere in the resulting dict's values because it is not a key in ``id_city_d``.

Doctests are available in the :download:`ballsD_inv.test` file.

------------------------------------------------------------------------------------------------

The second function is:

    .. py:function:: ballsD_gen(id_city_D, id_balls_D)

such that

    **given** the :class:`dict` *id_city_D* and *id_balls_D*  as described at the beginning

    **returns** a :class:`dict` where the key is a :class:`str` with a city name included in *id_city_D* and
    the associated value is a :class:`list` of two-component :class:`tuple`, one for each dance and dancer from that city according to *id_balls_D*.
    Specificly, each :class:`tuple` has two values: an :class:`int` with the dancer *Id number* and a :class:`str` which is the name of the dance.
    The dancers that do not appear in *id_city_D* must be listed under the ``'X'`` key.

    Notice that the cities where there is no dancer are not included in the dictionary's keys.

    For instance, in the following example the Id ``44555666`` is not a key in *id_city_D*,
    therefore it is listed under the ``'X'`` and the associated value is a list which includes three tuples with that *ID number*, one for each dance s/he likes.

For example:

    .. literalinclude:: ballsD_gen.test
        :language: python3
        :start-after: --ini11
        :end-before: --fi2

Doctests are available in the :download:`ballsD_gen.test` file.

------------------------------------------------------------------------------------------------

The third function is:

    .. py:function:: ballsD_sort(balls_D)

such that

    **given** a :class:`dict` as the one produced by the previous function

    **modifies** it by ordering the lists for each entry according to the following criteria:

        #. Alphabetically by the name of the dance.
        #. Increasingly by the Id number.

For example:

    .. literalinclude:: ballsD_sort.test
        :language: python3
        :start-after: --ini
        :end-before: --fi

Doctests are available in the :download:`ballsD_sort.test` file.