kickerde_api_client.mapping
===========================

.. py:module:: kickerde_api_client.mapping

.. autoapi-nested-parse::

   Mapping and transformation features.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/kickerde_api_client/mapping/league/index
   /autoapi/kickerde_api_client/mapping/league_list/index
   /autoapi/kickerde_api_client/mapping/league_season_info/index
   /autoapi/kickerde_api_client/mapping/my_team_sync/index
   /autoapi/kickerde_api_client/mapping/season_list/index
   /autoapi/kickerde_api_client/mapping/team/index


Attributes
----------

.. autoapisummary::

   kickerde_api_client.mapping.Submapper
   kickerde_api_client.mapping.SubmapperKey


Classes
-------

.. autoapisummary::

   kickerde_api_client.mapping.XmlMappingHelper


Functions
---------

.. autoapisummary::

   kickerde_api_client.mapping.map_default


Package Contents
----------------

.. py:data:: Submapper
   :type:  TypeAlias
   :value: Callable[[str, Any], tuple[str, Any] | None]


   Function that accepts a key-value pair and returns another
   (transformed) key-value pair. Used for on-the-fly post-processing
   while mapping an object hierarchy from a source to a target format.

   A `Submapper` is conceptually similar to, but not the same thing as,
   a callback function used in the `postprocessor` kwarg of the
   :py:meth:`xmltodict.parse` function. A submapper is less flexible than
   a `postprocessor` kwarg because the latter accepts a complex path
   that points to an element location in the object hierarchy. On the
   other hand, a submapper assumes a fixed (implied) location, so it
   only accepts `key` and `value` as arguments but not the element’s
   location in the hierarchy.

   (The name `Submapper` was chosen to emphasize that any given
   function of this type is usually focused on mapping a specific
   sub-element in an object hierarchy.)

   A submapper may return `None` instead of a key-value pair. If a
   caller receives `None` as a return value, it is supposed to discard
   the element, i.e. not include it in the target hierarchy.


.. py:data:: SubmapperKey
   :type:  TypeAlias
   :value: str | tuple[str, ...]


   Immutable key that describes a location in an object hierarchy.
   Used internally to look up functions of the :py:obj:`.Submapper`
   type by location.

   If the key is a **string**, then the key matches a location if and
   only if the element name is equal to the key.

   Example: The key `"baz"` matches elements located at `foo.bar.baz`
   and `qux.baz`. However, it does not match `qux.baz.quux`.

   If the key is a **tuple of strings**, then it matches a location if
   and only if the tuple is equal to the chain of element names.

   Example: The key `("foo", "bar", "baz")` matches elements located
   at `foo.bar.baz`. It does not match any other elements.


.. py:class:: XmlMappingHelper(submappers)

   Mapping helper designed to be plugged into
   :py:meth:`xmltodict.parse`.

   The purpose of this helper class is to aggregate and dispatch
   :py:obj:`.Submapper` functions for various elements in an
   XML document while the document is being parsed.

   The :py:meth:`.map` method of this class is designed to be
   plugged into the `postprocessor` kwarg of the
   :py:meth:`xmltodict.parse` function.


   .. py:attribute:: filter_rules
      :type:  collections.abc.MutableSequence[collections.abc.Callable[Ellipsis, bool]]


   .. py:attribute:: submappers


   .. py:method:: map(path, original_key, value)

      Transforms an XML key-value pair into a Pythonic type that
      matches the domain type as closely as possible.



.. py:function:: map_default(key, value)

   Mapping helper that maps the `id` property to an integer and
   keeps everything else as is.