Metadata-Version: 2.4
Name: ut_aod
Version: 2.0.0.20251020
Summary: Utilities for Arrays of Dictionaries
Author-email: Bernd Stroehle <bernd.stroehle@gmail.com>
Maintainer-email: Bernd Stroehle <bernd.stroehle@gmail.com>
License-Expression: GPL-3.0-only WITH Classpath-exception-2.0 OR BSD-3-Clause
Project-URL: Source Code, https://github.com/bs29/ut_aod/tree/master
Project-URL: Homepage, https://kosakya.de/
Project-URL: Documentation, https://ka-apc.readthedocs.io/en/latest
Project-URL: Apache-2.0 License, https://apache.org/licenses/LICENSE-2.0
Project-URL: GPLv3 License, https://www.gnu.org/licenses/gpl-3.0.en.html
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Natural Language :: English
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: pandas>=2.3.3
Requires-Dist: polars>=1.34.0
Requires-Dist: ut_dic>=1.0.0.20251013
Requires-Dist: ut_log>=1.0.0.20251013
Dynamic: license-file

######
ut_aod
######

********
Overview
********

.. start short_desc

**Utilities for Arrays of Dictionaries**

.. end short_desc

************
Installation
************

.. start installation

Package ``ut_aod`` can be installed from PyPI.

To install with ``pip``:

.. code-block:: shell

	$ python -m pip install ut_aod

***************
Package logging 
***************

(c.f.: `https://pypi.org/project/ut-log/`)

*************
Package files
*************

Classification
==============

The Package ``ut_aod`` consist of the following file types (c.f.: **Appendix**: `Python Glossary`):

#. **Special files:**

   a. *py.typed*

#. **Special modules:**

   a. *__init__.py*
   #. *__version__.py*

#. **Modules**

   a. *aod.py*

*******
Modules
*******

Module: aod.py
==============

The Array of Dictionaries module ``aod.py`` contains the static classes ``AoD`` and ``IoD``
and the dictionary of callables ``doc``.

Class: AoD
----------

The static Class ``AoD`` is used to manage arrays of dictionaries; it contains
no variables and only static- or class-methods.


Methods
^^^^^^^

  .. Methods-of-class-AoD-label:
  .. table:: *Methods of class AoD*

   +------------------------------------+------------------------------------------------------+
   |Name                                |Short description                                     |
   +====================================+======================================================+
   |add                                 |Append the object to the Array of dictionaries if the |
   |                                    |object is a dictionary or extend it with the objects  |
   |                                    |the the object is a list.                             |
   +------------------------------------+------------------------------------------------------+
   |add_mapped_dic_value                |Add the dictionary element mapped by the function to  |
   |                                    |the array of dictionaries.                            |
   +------------------------------------+------------------------------------------------------+
   |append_unique                       |Append dictionary to array of dictionaries if it does |
   |                                    |not exist in the dictionary.                          |
   +------------------------------------+------------------------------------------------------+
   |apply_function                      |Apply the function to the array of dictionaries.      |
   +------------------------------------+------------------------------------------------------+
   |dic_found_with_empty_value          |Return True or raise an exception if the array of     |
   |                                    |dictionaries contains a dictionary with empty value   |
   |                                    |and the execption switch is True.                     |
   +------------------------------------+------------------------------------------------------+
   |merge_aod                           |Merge two array of dictionaries.                      |
   +------------------------------------+------------------------------------------------------+
   |merge_dic                           |Merge array of dictionaries with dictionary.          |
   +------------------------------------+------------------------------------------------------+
   |nvl                                 |Replace empty array of dictionaries.                  |
   +------------------------------------+------------------------------------------------------+
   |put                                 |Write transformed array of dictionaries to a csv file |
   |                                    |file with a selected I/O function.                    |
   +------------------------------------+------------------------------------------------------+
   |sh_doaod_split_by_value_is_not_empty|Converted array of dictionaries to dictionary of array|
   |                                    |of dictionaries by using conditional split.           |
   +------------------------------------+------------------------------------------------------+
   |sh_dod                              |Convert array of dictionaries to dictionaries of      |
   |                                    |dictionaries.                                         |
   +------------------------------------+------------------------------------------------------+
   |sh_key_value_found                  |Show True if an element exists in the array of        |
   |                                    |dictionaries which contains the key, value pair.      |
   +------------------------------------+------------------------------------------------------+
   |sh_unique                           |Deduplicate array of dictionaries.                    |
   +------------------------------------+------------------------------------------------------+
   |split_by_value_is_not_empty         |Split array of dictionaries by the condition "the     |
   |                                    |given key value is not empty".                        |
   +------------------------------------+------------------------------------------------------+
   |to_aoa of_keys_values               |Convert array of dictionaries to array of arrays using|
   |                                    |keys of any dictionary and values of all dictionaries.|
   +------------------------------------+------------------------------------------------------+
   |to_aoa of_values                    |Convert array of dictionaries to array of arrays using|
   |                                    |values of all dictionaries.                           |
   +------------------------------------+------------------------------------------------------+
   |to_aoa                              |Convert array of dictionaries to array of arrays      |
   |                                    |controlled by key- and value-switch.                  |
   +------------------------------------+------------------------------------------------------+
   |to_arr of_key_values                |Convert array of dictionaries to array of arrays using|
   |                                    |keys of any dictionary and values of all dictionaries.|
   +------------------------------------+------------------------------------------------------+
   |to_csv_with_dictwriterows           |Write array of dictionaries to csv file with pandas.  |
   +------------------------------------+------------------------------------------------------+
   |to_csv_with_pd                      |Write array of dictionaries to csv file with pandas.  |
   +------------------------------------+------------------------------------------------------+
   |to_csv_with_pl                      |Write array of dictionaries to csv file with polars.  |
   +------------------------------------+------------------------------------------------------+
   |to_dic_by_dic                       |Convert array of dictionaries to dictionary by using  |
   |                                    |the key                                               |
   +------------------------------------+------------------------------------------------------+
   |to_dic_by_ix                        |Convert array of dictionaries to dictionary by using  |
   |                                    |lowercase keys.                                       |
   +------------------------------------+------------------------------------------------------+
   |to_doaod_by_key                     |Convert array of dictionaries to dictionary of arrays |
   |                                    |of dictionaries by using the key.                     |
   +------------------------------------+------------------------------------------------------+
   |to_unique_by_key                    |Convert array of dictionaries to unique array of      |
   |                                    |dictionaries by selecting dictionaries with key.      |
   +------------------------------------+------------------------------------------------------+
   |union_distinct                      |Make the array of dictionaries unique.                |
   +------------------------------------+------------------------------------------------------+

Method: add
^^^^^^^^^^^

Description
"""""""""""

Add an object to an array of dictionaries.

#. If the objects is a dictionary:

   * the object is appended to the array of dictionaries

#. If the objects is an array of dictionaries:

   * the object extends the array of dictionaries

Parameter
"""""""""

  .. Parameter-of-Method-add-label:
  .. table:: *Parameter of Method add*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |obj |TyAny|Object               |
   +----+-----+---------------------+

Return Value
""""""""""""

  .. Return-value-of-Method-add-label:
  .. table:: *Return value of Method add*

   +--------+-----+--------------------------+
   |Name    |Type |Description               |
   +========+=====+==========================+
   |_aod_new|TyAoD|New array of dictionaries.|
   +--------+-----+--------------------------+

Method: add_mapped_dic_value
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Description
"""""""""""

Add the mapped dictionary value of the given key to the array of dictionaries.

Parameter
"""""""""

  .. Parameter-of-Method-add_mapped_dic_value-label:
  .. table:: *Parameter of Method add_mapped_dic_value*

   +----+----------+---------------------+
   |Name|Type      |Description          |
   +====+==========+=====================+
   |cls |class     |Current class        |
   +----+----------+---------------------+
   |aod |TyAoD     |Array of dictionaries|
   +----+----------+---------------------+
   |dic |TnDic     |Dictionary           |
   +----+----------+---------------------+
   |key |TnAny     |Key of dictionary    |
   +----+----------+---------------------+
   |fnc |TyCallable|Function             |
   +----+----------+---------------------+

Return Value
""""""""""""

  .. Return-value-of-Method-add-label:
  .. table:: *Return value of Method add*

   +--------+-----+--------------------------+
   |Name    |Type |Description               |
   +========+=====+==========================+
   |_aod_new|TyAoD|New array of dictionaries.|
   +--------+-----+--------------------------+

Method: add_mapped_dic_value
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   
Description
"""""""""""

#. Apply the given function to the value of the given dictionary for
   the key.
#. The result is used to extend the given array of dictionaries.

Parameter
"""""""""

  .. Parameter-of_Method-extend_if_not_empty-label:
  .. table:: *Parameter of Method extend_if_not_empty*

   +--------+----------+---------------------+
   |Name    |Type      |Description          |
   +========+==========+=====================+
   |aod     |TyAoD     |Array of dictionaries|
   +--------+----------+---------------------+
   |dic     |TyDic     |Dictionary           |
   +--------+----------+---------------------+
   |key     |TnAny     |Dictionary key       |
   +--------+----------+---------------------+
   |function|TyCallable|Function             |
   +--------+----------+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of_Method-extend_if_not_empty-label:
  .. table:: *Return value of Method extend_if_not_empty*

   +--------+-----+-------------------------+
   |Name    |Type |Description              |
   +========+=====+=========================+
   |_aod_new|TyAoD|New array of dictionaries|
   +--------+-----+-------------------------+
   
Method: append_unique
^^^^^^^^^^^^^^^^^^^^^

Description
"""""""""""

Append the dictionary to the array of dictionaries if it does not exist in the array.

Parameter
"""""""""

  .. Parameter-of-Method-append_unique-label:
  .. table:: *Parameter of Method append_unique*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |dic |TyDic|Dictionary           |
   +----+-----+---------------------+

Method: apply_function
^^^^^^^^^^^^^^^^^^^^^^

Description
"""""""""""

Create a new array of dictionaries by applying the function to each element
of the array of dictionaries.

Parameter
"""""""""

  .. Parameter-of-Method-apply_function-label:
  .. table:: *Parameter of Method apply_function*

   +------+----------+-------------------------------+
   |Name  |Type      |Description                    |
   +======+==========+===============================+
   |aod   |TyAoD     |Array of dictionaries          |
   +------+----------+-------------------------------+
   |fnc   |TnCallable|Function                       |
   +------+----------+-------------------------------+
   |kwargs|TnDic     |Dictionary of keyword arguments|
   +------+----------+-------------------------------+

Return value
""""""""""""

  .. Return-value-of-Method-apply_function-label:
  .. table:: *Return value of Method apply_function*

   +-------+-----+-------------------------+
   |Name   |Type |Description              |
   +=======+=====+=========================+
   |aod_new|TyAoD|new array of dictionaries|
   +-------+-----+-------------------------+

Method: dic_found_with_empty_value
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^       
   
Description
"""""""""""

The Method ``dic_found_with_empty_value`` performs the following steps:
#. Loop thru the array of dictionaries;

   If the dictionary value for the key is empty and 
       if the switch "sw_raise" is True then
           raise an Exception
       else
           return True.

#. return False

Parameter
"""""""""

  .. Parameter-of_Method-dic_found_with_empty_value-label:
  .. table:: *Parameter of Method dic_found_with_empty_value*

   +--------+------+-------+---------------------+
   |Name    |Type  |Default|Description          |
   +========+======+=======+=====================+
   |aod     |TyAoD |       |Array of dictionaries|
   +--------+------+-------+---------------------+
   |key     |TyStr |       |Dictionary key       |
   +--------+------+-------+---------------------+
   |sw_raise|TyBool|False  |Raise switch         |
   +--------+------+-------+---------------------+

Return Value
""""""""""""

  .. Return-value-of_Method-dic_found_with_empty_value-label:
  .. table:: *Return value of Method dic_found_with_empty_value*

   +----+------+----------------------------+
   |Name|Type  |Description                 |
   +====+======+============================+
   |    |TyBool|key is found in a dictionary|
   +----+------+----------------------------+
   
Method: merge_aod
^^^^^^^^^^^^^^^^^
  
Description
"""""""""""

Merge two arrays of dictionaries.
Every dictionary of the first array of dictionaries is merged
with all dictionaries of the second array of dictionaries.

Parameter
"""""""""

  .. Parameter-of_Method-join_aod-label:
  .. table:: *Parameter of Method join_aod*

   +----+-----+----------------------------+
   |Name|Type |Description                 |
   +====+=====+============================+
   |aod0|TyAoD|First array of dictionaries |
   +----+-----+----------------------------+
   |aod1|TyAoD|Second array of dictionaries|
   +----+-----+----------------------------+
   
Return Value
""""""""""""

  .. Return-value-of_Method-join_aod-label:
  .. table:: *Return value of Method join_aod*

   +--------+-----+-------------------------+
   |Name    |Type |Description              |
   +========+=====+=========================+
   |_aod_new|TyAoD|New array of dictionaries|
   +--------+-----+-------------------------+
   
Method: merge_dic
^^^^^^^^^^^^^^^^^
   
Description
"""""""""""

Merge array of dictionaries with a dictionary.
Every dictionary of the array of dictionaries is merged with the dictionary.
   
Parameter
"""""""""

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |dic |TyDic|Dictionary           |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of_Method-merge_dic-label:
  .. table:: *Return value of Method merge_dic*

   +--------+-----+-------------------------+
   |Name    |Type |Description              |
   +========+=====+=========================+
   |_aod_new|TyAoD|New array of dictionaries|
   +--------+-----+-------------------------+
   
Method: nvl
^^^^^^^^^^^
   
Description
"""""""""""

If the array of dictionaries is undefined then return the
empty array otherwise return the array of dictionaries.

Parameter
"""""""""

  .. Parameter-of_Method-nvl-label:
  .. table:: *Parameter of Method nvl*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TnAoD|Array of dictionaries|
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of_Method-nvl-label:
  .. table:: *Return value of Method nvl*

   +-------+-----+-------------------------+
   |Name   |Type |Description              |
   +=======+=====+=========================+
   |aod_new|TyArr|New array of dictionaries|
   +-------+-----+-------------------------+
   
Method: put
^^^^^^^^^^^
   
Description
"""""""""""

#. Transform array of dictionaries (1.argument) with a transformer function (3.argument)
#. If the I/O function is defined for the given dataframe type (4.argument).
   #. write result to a csv file with the given path name (2.argument).

Parameter
"""""""""

  .. Parameter-of_Method-put-label:
  .. table:: *Parameter of Method put*

   +-------+------+---------------------+
   |Name   |Type  |Description          |
   +=======+======+=====================+
   |aod    |TyAoD |Array of dictionaries|
   +-------+------+---------------------+
   |path   |TyPath|Csv file path        |
   +-------+------+---------------------+
   |fnc_aod|TyAoD |AoD function         |
   +-------+------+---------------------+
   |df_type|TyStr |Dataframe type       |
   +-------+------+---------------------+
   
Method: sh_doaod_split_by_value_is_not_empty
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   
Description
"""""""""""

#. Create 2-dimensional dict. of array of dictionaries from given array of dictionaries
   and key to split the array of dictionaries into 2 array of dictionaries by
   the two conditions

   * The key is contained in the dictionary and the value empty.
   * The key is contained in the dictionary and the value is not empty.

#. The first array of dictionaries is created by the condition and is assigned to 
   the new dictionary of array of dictionaries using the given key.

#. The second array of dictionaries is created by the negation of the condition and 
   is assigned to the new dictionary of array of dictionaries using the given key.

Parameter
"""""""""

  .. Parameter-of_Method-sh_doaod_split_by_value_is_not_empty-label:
  .. table:: *Parameter of Method sh_doaod_split_by_value_is_not_empty*

   +-----+-----+--------------------------------------+
   |Name |Type |Description                           |
   +=====+=====+======================================+
   |aod  |TyAoD|Array of dictionaries                 |
   +-----+-----+--------------------------------------+
   |key  |Any  |Dictionary key                        |
   +-----+-----+--------------------------------------+
   |key_n|Any  |key of the array of dictionaries      |
   |     |     |wich satisfies the condition.         |
   +-----+-----+--------------------------------------+
   |key_y|Any  |key of the array of dictionaries which|
   |     |     |does not satisfies the condition.     |
   +-----+-----+--------------------------------------+
   
Return value
""""""""""""

  .. Return-value-of_Method-sh_doaod_split_by_value_is_not_empty-label:
  .. table:: *Return value of Method sh_doaod_split_by_value_is_not_empty*

   +-----+-------+-----------------------------------+
   |Name |Type   |Description                        |
   +=====+=======+===================================+
   |doaod|TyDoAoD|Dictionary of array of dictionaries|
   +-----+-------+-----------------------------------+
   
Method: sh_dod
^^^^^^^^^^^^^^
   
Description
"""""""""""

Create dictionary of dictionaries from the array of dictionaries and the key.       

Parameter
"""""""""

  .. Parameter-of_Method-sh_dod-label:
  .. table:: *Parameter of Method sh_dod*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |key |Any  |Key                  |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return value-of_Method-sh_dod-label:
  .. table:: *Return value of Method sh_dod*

   +----+-----+--------------------------+
   |Name|Type |Description               |
   +====+=====+==========================+
   |dod |TyDoD|Dictionary of dictionaries|
   +----+-----+--------------------------+
   
Method: sh_unique
^^^^^^^^^^^^^^^^^

Description
"""""""""""

Deduplicate array of dictionaries (1.argument).
   
Parameter
"""""""""

  .. Parameter-of_Method-sh_unique-label:
  .. table:: *Parameter of Method sh_unique*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |key |Any  |Key                  |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return value-of_Method-sh_unique-label:
  .. table:: *Return value of Method sh_unique*

   +-------+-----+-------------------------+
   |Name   |Type |Description              |
   +=======+=====+=========================+
   |aod_new|TyAoD|New array of dictionaties|
   +-------+-----+-------------------------+
   
Method: split_by_value_is_not_empty
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^      
   
Description
"""""""""""

Split the given array of dictionary into 2 arrays of dictionary by the condition 
"the key is contained in the dictionary and the value is not empty"

Parameter
"""""""""

  .. Parameter-of_Method-split_by_value_is_not_empty-label:
  .. table:: *Parameter of Method split_by_value_is_not_empty*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|array of dictionaries|
   +----+-----+---------------------+
   |key |Any  |Key                  |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of_Method-split_by_value_is_not_empty-label:
  .. table:: *Return value of Method split_by_value_is_not_empty*

   +--------------+--------+---------------------------------+
   |Name          |Type    |Description                      |
   +==============+========+=================================+
   |(aod_n, aod_y)|Ty2ToAoD|Tuple of 2 arrays of dictionaries|
   +--------------+--------+---------------------------------+
   
Method: sw_key_value_found
^^^^^^^^^^^^^^^^^^^^^^^^^^
   
Description
"""""""""""

Set the condition to True if:
* the key is contained in a dictionary of the array of dictionaries and
* the key value is not empty"

Parameter
"""""""""

  .. Parameter-of_Method-sw_key_value_found-label:
  .. table:: *Parameter value of Method sw_key_value_found*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |key |Any  |Key                  |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of_Method-sw_key_value_found-label:
  .. table:: *Return value of Method sw_key_value_found*

   +----+------+--------------------------------+
   |Name|Type  |Description                     |
   +====+======+================================+
   |sw  |TyBool|key is contained in a dictionary|
   |    |      |of the array of dictionaries    |
   +----+------+--------------------------------+
   
Method: to_aoa
^^^^^^^^^^^^^^
   
Description
"""""""""""

Create array of arrays from given array of dictionaries (1.argument).

#. If switch sw_keys (2.argument) is True:

   * Create the first element of the array of arrays as the list of dict. keys of the
     first elements of the array of dictionaries.

#. If the switch sw_values (3. argument) is True:

   * Create the other elemens of the array of dictionries as list of dict. values of the
     elements of the array of dictionaries.

Parameter
"""""""""

  .. Parameter-of_Method-to_aoa-label:
  .. table:: *Parameter of Method to_aoa*

   +---------+------+---------------------+
   |Name     |Type  |Description          |
   +=========+======+=====================+
   |aod      |TyAoD |Array of dictionaries|
   +---------+------+---------------------+
   |sw_keys  |TyBool|Keys switch          |
   +---------+------+---------------------+
   |sw_values|TyBool|Values switch        |
   +---------+------+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of_Method-to_aoa-label:
  .. table:: *Return value of Method to_aoa*

   +----+-----+---------------+
   |Name|Type |Description    |
   +====+=====+===============+
   |aoa |TyAoA|array of arrays|
   +----+-----+---------------+
   
Method: to_aoa of_key_values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   
Description
"""""""""""

Convert the given array of dictionary (1.argument) into an array of arrays.
#. Create first element of the new array of arrays as the keys-list of the first dictionary.
#. Create other elements as the values-lists of the dictionaries of the array of dictionaries.

Parameter
"""""""""

  .. Parameter-of_Method-to_aoa of_key_values-label:
  .. table:: *Parameter of Method to_aoa of_key_values*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of_Method-to_aoa of_key_values-label:
  .. table:: *Return value of Method to_aoa of_key_values*

   +----+-----+---------------+
   |Name|Type |Description    |
   +====+=====+===============+
   |aoa |TyAoA|Array of arrays|
   +----+-----+---------------+
   
Method: to_aoa_of_values
^^^^^^^^^^^^^^^^^^^^^^^^
  
Description
"""""""""""

Convert the given array of dictionaries (1.argument) into an array of arrays.
The elements of the new array of arrays are the values-lists of the dictionaries
of the array of dictionaries.

Parameter
"""""""""

  .. Parameter-of-Method-to_aoa_of_values-label:
  .. table:: *Parameter of Method to_aoa_of_values*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of-Method-to_aoa_of_values-label:
  .. table:: *Return value of Method to_aoa_of_values*

   +----+-----+---------------+
   |Name|Type |Description    |
   +====+=====+===============+
   |aoa |TyAoA|Array of arrays|
   +----+-----+---------------+
   
Method: to_arr_of_key_values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   
Description
"""""""""""

Convert the given array of dictionaries (1.argument) to an array. The elements of the new
array are the selected values of each dictionary of the array of dictionaries with the 
given key (2.argument).

Parameter
"""""""""

  .. Parameter-of-Method-to_arr_of_key_values-label:
  .. table:: *Parameter of Method to_arr_of_key_values*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |key |Any  |Key                  |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of-Method-to_arr_of_key_values-label:
  .. table:: *Return value of Method to_arr_of_key_values*

   +----+-----+-------------------------+
   |Name|Type |Description              |
   +====+=====+=========================+
   |arr |TyAoD|New array of dictionaries|
   +----+-----+-------------------------+
   
Method: to_csv_with_dictwriterows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^          

Description
"""""""""""

Write given array of dictionaries (1.argument) to a csv file with the given path
name (2.argument) using the function "dictwriter" of the builtin path module "csv"

Parameter
"""""""""

  .. Parameter-of Method-csv_dictwriterows-label:
  .. table:: *Parameter of Method csv_dictwriterows*

   +----+------+---------------------+
   |Name|Type  |Description          |
   +====+======+=====================+
   |aod |TyAoD |Array of dictionaries|
   +----+------+---------------------+
   |path|TyPath|Path                 |
   +----+------+---------------------+
   
Method: to_csv_with_pd
^^^^^^^^^^^^^^^^^^^^^^^
   
Description
"""""""""""

#. Convert the array of dictionaries to a pandas dataframe.
#. Apply the given function to the pandas dataframe.
#. Write the pandas dataframe to a csv file with the given name.


Parameter
"""""""""

  .. Parameter-of_Method-pd_to_csv-label:
  .. table:: *Parameter of Method pd-to_csv*

   +----+----------+---------------------+
   |Name|Type      |Description          |
   +====+==========+=====================+
   |aod |TyAoD     |Array of dictionaries|
   +----+----------+---------------------+
   |path|TyPath    |Csv file path        |
   +----+----------+---------------------+
   |fnc |TyCallable|Panda function       |
   +----+----------+---------------------+
   
Method: to_csv_with_pl
^^^^^^^^^^^^^^^^^^^^^^
   
Description
"""""""""""

#. Convert the array of dictionaries to a panda dataframe.
#. Convert the panda dataframe to a polars dataframe.
#. Apply the given function to the polars dataframe.
#. Write the polars dataframe to a csv file with the given name.

Parameter
"""""""""

  .. Parameter-of_Method-pl_to_csv-label:
  .. table:: *Parameter of Method pl_to_csv*

   +----+----------+---------------------+
   |Name|Type      |Description          |
   +====+==========+=====================+
   |aod |TyAoD     |Array of dictionaries|
   +----+----------+---------------------+
   |path|TyPath    |Csv file path        |
   +----+----------+---------------------+
   |fnc |TyCallable|Polars function      |
   +----+----------+---------------------+
   
Method: to_doaod_by_key
^^^^^^^^^^^^^^^^^^^^^^^
   
Parameter
"""""""""

  .. Parameter-of-Method-to_doaod_by_key-label:
  .. table:: *Parameter of Method to_doaod_by_key*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |key |Any  |Key                  |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return-value-of-Method-to_doaod_by_key-label:
  .. table:: *Return value of Method to_doaod_by_key*

   +-----+-----+-----------------------------------+
   |Name |Type |Description                        |
   +=====+=====+===================================+
   |doaod|TyAoD|Dictionary of array of dictionaries|
   +-----+-----+-----------------------------------+
   
Method: to_dod_by_key
^^^^^^^^^^^^^^^^^^^^^
   
Parameter
"""""""""

  .. Parameter-of-Method-to_dod_by_key-label:
  .. table:: *Parameter of Method to_dod_by_key*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |key |Any  |                     |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return value-of-Method-to_dod_by_key-label:
  .. table:: *Return value of Method to_dod_by_key*

   +----+-----+-------------+
   |Name|Type |Description  |
   +====+=====+=============+
   |dic |TyDic|             |
   +----+-----+-------------+
   
   
Method: to_doa_by_lc_keys
^^^^^^^^^^^^^^^^^^^^^^^^^
   
Parameter
"""""""""

  .. Parameter-of-Method-to_doa_by_lc_keys-label:
  .. table:: *Parameter of Method to_doa_by_lc_keys*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |key |Any  |                     |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return value-of-Method-to_doa_by_lc_keys-label:
  .. table:: *Return value of Method to_doa_by_lc_keys*

   +----+-----+--------------------+
   |Name|Type |Description         |
   +====+=====+====================+
   |doa |TyDoA|Dictionary of arrays|
   +----+-----+--------------------+
   
Method: to_unique_by_key
^^^^^^^^^^^^^^^^^^^^^^^^
   
Parameter
"""""""""

  .. Parameter-of-Method-to_unique_by_key-label:
  .. table:: *Parameter of Method to_unique_by_key*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   |key |Any  |                     |
   +----+-----+---------------------+
   
Return Value
""""""""""""

  .. Return value-of-Method-to_unique_by_key-label:
  .. table:: *Return value of Method to_unique_by_key*

   +--------+-----+-------------------------+
   |Name    |Type |Description              |
   +========+=====+=========================+
   |_aod_new|TyAoD|New array of dictionaries|
   +--------+-----+-------------------------+
   
Method: write_xlsx_wb
^^^^^^^^^^^^^^^^^^^^^
   
Parameter
"""""""""

  .. Parameter-of-Method-write_xlsx_wb-label:
  .. table:: *Parameter of Method write_xlsx_wb*

   +----+-----+---------------------+
   |Name|Type |Description          |
   +====+=====+=====================+
   |aod |TyAoD|Array of dictionaries|
   +----+-----+---------------------+
   
########
Appendix
########

***************
Python Glossary
***************

.. _python-modules:

Python Modules
==============

Overview
--------

  .. Python-Modules-label:
  .. table:: *Python Modules*

   +--------------+---------------------------------------------------------+
   |Name          |Definition                                               |
   +==============+==========+==============================================+
   |Python modules|Files with suffix ``.py``; they could be empty or contain|
   |              |python code; other modules can be imported into a module.|
   +--------------+---------------------------------------------------------+
   |special Python|Modules like ``__init__.py`` or ``main.py`` with special |
   |modules       |names and functionality.                                 |
   +--------------+---------------------------------------------------------+

.. _python-functions:

Python Function
===============

Overview
--------

  .. Python-Function-label:
  .. table:: *Python Function*

   +---------------+---------------------------------------------------------+
   |Name           |Definition                                               |
   +===============+==========+==============================================+
   |Python function|Files with suffix ``.py``; they could be empty or contain|
   |               |python code; other modules can be imported into a module.|
   +---------------+---------------------------------------------------------+
   |special Python |Modules like ``__init__.py`` or ``main.py`` with special |
   |modules        |names and functionality.                                 |
   +---------------+---------------------------------------------------------+

.. _python-packages:

Python Packages
===============

Overview
--------

  .. Python Packages-Overview-label:
  .. table:: *Python Packages Overview*

   +---------------------+---------------------------------------------+
   |Name                 |Definition                                   |
   +=====================+=============================================+
   |Python package       |Python packages are directories that contains|
   |                     |the special module ``__init__.py`` and other |
   |                     |modules, sub packages, files or directories. |
   +---------------------+---------------------------------------------+
   |Python sub-package   |Python sub-packages are python packages which|
   |                     |are contained in another python package.     |
   +---------------------+---------------------------------------------+
   |Python package       |directory contained in a python package.     |
   |sub-directory        |                                             |
   +---------------------+---------------------------------------------+
   |Python package       |Python package sub-directories with a special|
   |special sub-directory|meaning like data or cfg                     |
   +---------------------+---------------------------------------------+

Special python package sub-directories
--------------------------------------

  .. Special-python-package-sub-directory-Examples-label:
  .. table:: *Special python package sub-directories*

   +-------+------------------------------------------+
   |Name   |Description                               |
   +=======+==========================================+
   |bin    |Directory for package scripts.            |
   +-------+------------------------------------------+
   |cfg    |Directory for package configuration files.|
   +-------+------------------------------------------+
   |data   |Directory for package data files.         |
   +-------+------------------------------------------+
   |service|Directory for systemd service scripts.    |
   +-------+------------------------------------------+

.. _python-files:

Python Files
============

Overview
--------

  .. Python-files-label:
  .. table:: *Python files*

   +--------------+---------------------------------------------------------+
   |Name          |Definition                                               |
   +==============+==========+==============================================+
   |Python modules|Files with suffix ``.py``; they could be empty or contain|
   |              |python code; other modules can be imported into a module.|
   +--------------+---------------------------------------------------------+
   |Python package|Files within a python package.                           |
   |files         |                                                         |
   +--------------+---------------------------------------------------------+
   |Python dunder |Python modules which are named with leading and trailing |
   |modules       |double underscores.                                      |
   +--------------+---------------------------------------------------------+
   |special       |Files which are not modules and used as python marker    |
   |Python files  |files like ``py.typed``.                                 |
   +--------------+---------------------------------------------------------+
   |special Python|Modules like ``__init__.py`` or ``main.py`` with special |
   |modules       |names and functionality.                                 |
   +--------------+---------------------------------------------------------+

.. _python-special-files:

Python Special Files
--------------------

  .. Python-special-files-label:
  .. table:: *Python special files*

   +--------+--------+--------------------------------------------------------------+
   |Name    |Type    |Description                                                   |
   +========+========+==============================================================+
   |py.typed|Type    |The ``py.typed`` file is a marker file used in Python packages|
   |        |checking|to indicate that the package supports type checking. This is a|
   |        |marker  |part of the PEP 561 standard, which provides a standardized   |
   |        |file    |way to package and distribute type information in Python.     |
   +--------+--------+--------------------------------------------------------------+

.. _python-special-modules:

Python Special Modules
----------------------

  .. Python-special-modules-label:
  .. table:: *Python special modules*

   +--------------+-----------+----------------------------------------------------------------+
   |Name          |Type       |Description                                                     |
   +==============+===========+================================================================+
   |__init__.py   |Package    |The dunder (double underscore) module ``__init__.py`` is used to|
   |              |directory  |execute initialisation code or mark the directory it contains   |
   |              |marker     |as a package. The Module enforces explicit imports and thus     |
   |              |file       |clear namespace use and call them with the dot notation.        |
   +--------------+-----------+----------------------------------------------------------------+
   |__main__.py   |entry point|The dunder module ``__main__.py`` serves as package entry point |
   |              |for the    |point. The module is executed when the package is called by the |
   |              |package    |interpreter with the command **python -m <package name>**.      |
   +--------------+-----------+----------------------------------------------------------------+
   |__version__.py|Version    |The dunder module ``__version__.py`` consist of assignment      |
   |              |file       |statements used in Versioning.                                  |
   +--------------+-----------+----------------------------------------------------------------+

Python classes
==============

Overview
--------

  .. Python-classes-overview-label:
  .. table:: *Python classes overview*

   +-------------------+---------------------------------------------------+
   |Name               |Description                                        |
   +===================+===================================================+
   |Python class       |A class is a container to group related methods and|
   |                   |variables together, even if no objects are created.|
   |                   |This helps in organizing code logically.           |
   +-------------------+---------------------------------------------------+
   |Python static class|A class which contains only @staticmethod or       |
   |                   |@classmethod methods and no instance-specific      |
   |                   |attributes or methods.                             |
   +-------------------+---------------------------------------------------+

Python methods
==============

Overview
--------

  .. Python-methods-overview-label:
  .. table:: *Python methods overview*

   +--------------+-------------------------------------------+
   |Name          |Description                                |
   +==============+===========================================+
   |Python method |Python functions defined in python modules.|
   +--------------+-------------------------------------------+
   |Python class  |Python functions defined in python classes.|
   |method        |                                           |
   +--------------+-------------------------------------------+
   |Python special|Python class methods with special names and|
   |class method  |functionalities.                           |
   +--------------+-------------------------------------------+

Python class methods
--------------------

  .. Python-class-methods-label:
  .. table:: *Python class methods*

   +--------------+----------------------------------------------+
   |Name          |Description                                   |
   +==============+==============================================+
   |Python no     |Python function defined in python classes and |
   |instance      |decorated with @classmethod or @staticmethod. |
   |class method  |The first parameter conventionally called cls |
   |              |is a reference to the current class.          |
   +--------------+----------------------------------------------+
   |Python        |Python function defined in python classes; the|
   |instance      |first parameter conventionally called self is |
   |class method  |a reference to the current class object.      |
   +--------------+----------------------------------------------+
   |special Python|Python class functions with special names and |
   |class method  |functionalities.                              |
   +--------------+----------------------------------------------+

Python special class methods
----------------------------

  .. Python-methods-examples-label:
  .. table:: *Python methods examples*

   +--------+-----------+--------------------------------------------------------------+
   |Name    |Type       |Description                                                   |
   +========+===========+==============================================================+
   |__init__|class      |The special method ``__init__`` is called when an instance    |
   |        |object     |(object) of a class is created; instance attributes can be    |
   |        |constructor|defined and initalized in the method. The method us a single  |
   |        |method     |parameter conventionally called ``self`` to access the object.|
   +--------+-----------+--------------------------------------------------------------+

#################
Table of Contents
#################

.. contents:: **Table of Content**
