ut-dic 2.0.0.20251020
Utilities for Dictionaries
Requires Python: >=3.10

######
ut_dic
######

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

.. start short_desc

**Utilities for Management of Dictionaries**

.. end short_desc

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

.. start installation

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

To install with ``pip``:

.. code-block:: shell

	$ python -m pip install ut_dic

.. end installation

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

(c.f.: **Appendix**: `Package Logging`)

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

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

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

#. **Special files:**

   a. *py.typed*

#. **Modules**

   #. **Special modules:**

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

   #. **Module for Dictionary**

      a. *dic.py* `Management of Dictionary`

   #. **Modules for Dictionary of basic types**

      a. *doc.py*    **Module for Dictionary of callables**
      #. *doo.py*    **Module for Dictionary of objects**
      #. *douri.py*  **Module for Dictionary of uri's** 

   #. **Modules for Dictionary of dataframe types**
   
      a. *dopddf.py* **Module for Dictionary of pandas dataframes**
      #. *dopldf.py* **Module for Dictionary of polars dataframes**

   #. **Modules for Dictionary of dictionaries**
   
      a. *dodoa.py*  **Module for Dictionary of dictionaries of arrays**
      #. *dodod.py*  **Module for Dictionary of dictionaries of dictionaries**
      #. *dodows.py* **Module for Dictionary of dictionaries of Excel worksheets**
      #. *dod.py*    **Module for Dictionary of dictionaries**

*********************
Module for Dictionary
*********************

Module: dic.py
==============

The Module ``dic.py`` contains the single static class ``Dic`` for the Management of Dictionaries.

Class: Dic
----------

The static class ``Dic`` of Module ``dic.py`` is used to manage dictionaries of different types.
It contains class variables that act as messages,
as well as class or static methods, but no instance methods.
The methods of the Dic class can be classified into the following types:

#. *Miscellenous Methods*
#. *Get Methods*
#. *Locate Methods*
#. *New Methods*
#. *Show Methods*
#. *Set Methods*
#. *Split Methods*
#. *Yield Methods*

Miscellenous Methods
^^^^^^^^^^^^^^^^^^^^

  .. Miscellenous-Methods-of-class-Dic-label:
  .. table:: *Miscellenous Methods of class Dic*

   +------------------------+----------------------------------------------------------+
   |Name                    |Description                                               |
   +========================+==========================================================+
   |add_counter_to_values   |Apply the function "add_counter_with key" to the last key |
   |                        |of the key list and the Dictionary localized by that key. |
   +------------------------+----------------------------------------------------------+
   |add_counter_to_value    |Initialize the unintialized counter with 1 and add it to  |
   |                        |the Dictionary value of the key.                          |
   +------------------------+----------------------------------------------------------+
   |append_to_values        |Apply the function "append with key" to the last key of   |
   |                        |the key list amd the Dictionary localized by that key.    |
   +------------------------+----------------------------------------------------------+
   |append_to_value         |Initialize the unintialized counter with 1 and add it to  |
   |                        |the Dictionary value of the key.                          |
   +------------------------+----------------------------------------------------------+
   |change_keys_by_keyfilter|Change the keys of the Dictionary by the values of the    |
   |                        |keyfilter Dictionary with the same keys.                  |
   +------------------------+----------------------------------------------------------+
   |copy                    |Copy the value for keys from source to target dictionary. |
   +------------------------+----------------------------------------------------------+
   |extend_values           |Appply the function "extend_by_key" to the last key of the|
   |                        |key list and the dictionary localized by that key.        |
   +------------------------+----------------------------------------------------------+
   |extend_value            |Add the item with the key as element to the dictionary if |
   |                        |the key is undefined in the dictionary. Extend the element|
   |                        |value with the value if both supports the extend function.|
   +------------------------+----------------------------------------------------------+
   |increment_values        |Appply the function "increment_by_key" to the last key of |
   |                        |the key list and the Dictionary localized by that key.    |
   +------------------------+----------------------------------------------------------+
   |increment_value         |Increment the value of the key if it is defined in the    |
   |                        |Dictionary, otherwise assign the item to the key          |
   +------------------------+----------------------------------------------------------+
   |is_not                  |Return False if the key is defined in the Dictionary and  |
   |                        |the key value if not empty, othewise returm True.         |
   +------------------------+----------------------------------------------------------+
   |lstrip_keys             |Remove the first string found in the Dictionary keys.     |
   +------------------------+----------------------------------------------------------+
   |merge                   |Merge two Dictionaries.                                   |
   +------------------------+----------------------------------------------------------+
   |new                     |create a new dictionary from keys and values.             |
   +------------------------+----------------------------------------------------------+
   |normalize_value         |Replace every Dictionary value by the first list element  |
   |                        |of the value if it is a list with only one element.       |
   +------------------------+----------------------------------------------------------+
   |nvl                     |Return the Dictionary if it is not None otherwise return  |
   |                        |the empty Dictionary "{}".                                |
   +------------------------+----------------------------------------------------------+
   |rename_key_using_kwargs |Rename old Dictionary key with new one get from kwargs.   |
   +------------------------+----------------------------------------------------------+
   |replace_string_in_keys  |Replace old string contained in keys with new one.        |
   +------------------------+----------------------------------------------------------+
   |rename_key              |Rename old Dictionary key with new one.                   |
   +------------------------+----------------------------------------------------------+
   |round_values            |Round values selected by keys,                            |
   +------------------------+----------------------------------------------------------+
   |to_aod                  |Convert dictionary to array of dictionaries.              |
   +------------------------+----------------------------------------------------------+

Get Methods
^^^^^^^^^^^

  .. Get-Methods-of-class-Dic-label:
  .. table:: *Get Methods of class Dic*

   +------------+--------------------------------------------------------------+
   |Name        |Description                                                   |
   +============+==============================================================+
   |get_by_keys |Return the value of the keys located in the nested dictionary.|
   +------------+--------------------------------------------------------------+
   |get_value_yn|Return the value value_y if the key is contained in the       |
   |            |dictionary otherwise return the value value_n.                |
   +------------+--------------------------------------------------------------+
   |get         |Loop thru the nested dictionary with the keys from the key    |
   |            |list until the key is found. If the last key of the key list  |      
   |            |is found return the value of the key, otherwise return None.  |
   +------------+--------------------------------------------------------------+

Locate Methods
^^^^^^^^^^^^^^

  .. Locate-Methods-of-class-Dic-label:
  .. table:: *Locate Methods of class Dic*

   +-----------------+-------------------------------------------------------------+
   |Name             |Description                                                  |
   +=================+=============================================================+
   |locate           |Return the value of the key reached by looping thru the      |
   |                 |nested Dictionary with the keys from the key list until      |
   |                 |the value is None or the last key of the key list is reached.|
   +-----------------+-------------------------------------------------------------+
   |locate_secondlast|Apply the locate function to the dictionary and the new key  |
   |                 |list which contains all key list items without the last one. |
   +-----------------+-------------------------------------------------------------+

New Methods
^^^^^^^^^^^

  .. New-Methods-of-class-Dic-label:
  .. table:: *New Methods of class Dic*

   +----------------------+----------------------------------------------------------+
   |Name                  |Description                                               |
   +======================+==========================================================+
   |new_by_fset_split_keys|Create new dictionary from old by creating the new keys   |
   |                      |as frozenset of the comma separator split of the old keys.|
   +----------------------+----------------------------------------------------------+
   |new_by_split_keys     |Create new nested dictionary from old by creating the new |
   |                      |keys as the comma separator split of the old keys.        |
   +----------------------+----------------------------------------------------------+
   |new_d_filter          |Create filter dictionary with key, value and method pairs.|
   +----------------------+----------------------------------------------------------+
   |new_d_index_d_values  |Create index and value dictionary from dictionary and     |
   |                      |pivot dictionary.                                         |
   +----------------------+----------------------------------------------------------+
   |new_prefix_keys       |Create new dictionary from old by using prefixed old keys |
   |                      |as new keys and old values as new values.                 |
   +----------------------+----------------------------------------------------------+
   |new_make_values2keys  |Convert the dictionary to a new dictionary by using the   |
   |                      |values as new keys and all keys mapped to the same value  |
   |                      |as new value.                                             |
   +----------------------+----------------------------------------------------------+

Set Methods
^^^^^^^^^^^

  .. Set-Methods-of_class-Dic-label:
  .. table:: *Set Methods of class Dic*

   +-----------------------------------------+-----------------------------------------------------------------+
   |Name                                     |Description                                                      |
   +=========================================+=================================================================+
   |set_kv_not_none                          |Set the given Dictionary key to the given value if both are not  |
   |                                         |are not None.                                                    |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_by_keys                              |Locate the values in a nested dictionary for the suceeding keys  |
   |                                         |of a key array and replace the last value with the given value   |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_by_key_pair                          |Replace value of source key by value of target key.              |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_if_none                              |Locate the values in a nested dictionary for the suceeding keys  |
   |                                         |of a key array and assign the given value to the last key if that|
   |                                         |key does not exist in the dictionary.                            |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_by_div                               |Replace the source key value by the division of the values of    |
   |                                         |two target keys if the they are of type float and the divisor    |
   |                                         |is not o, otherwise assign None.                                 |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_first_tgt_with_src_using_d_src2tgt   |Replace value of first dictionary target key found in the source |
   |                                         |to target dictionary by the source value found in the dictionary.|
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_first_tgt_with_src_using_d_tgt2src   |Replace value of first dictionary target key found in the target |
   |                                         |to source dictionary by the source value found in the dictionary.|
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_format_value                         |Replace the dictionary values by the formatted values using the  |
   |                                         |format string.                                                   |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_multiply_with_factor                 |Replace the dictionary values by the original value multiplied   |
   |                                         |with the factor.                                                 |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_tgt_with_src                         |Replace source dictionary values by target dictionary values.    |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_tgt_with_src_using_doaod_tgt2src     |Loop through the target to source dictionaries of the values of  |
   |                                         |the dictionary of the arrays of target to source dictionaries    |
   |                                         |until the return value of the function                           |
   |                                         |"set_nonempty_tgt_with_src_using_d_tgt2src" is defined.          |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_nonempty_tgt_with_src_using_d_tgt2src|Exceute the function "set_tgt_with_src_using_d_tgt2src" if all   |
   |                                         |dictionary values for the keys provided by the values of the     |
   |                                         |target to source dictionary are defined.                         |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_first_tgt_with_src_using_d_tgt2src   |Replace value of first dictionary target key found in the target |
   |                                         |to source dictionary by the source value found in the dictionary.|
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_tgt_with_src_using_d_src2tgt         |                                                                 |
   +-----------------------------------------+-----------------------------------------------------------------+
   |set_tgt_with_src_using_d_tgt2src         |                                                                 |
   +-----------------------------------------+-----------------------------------------------------------------+

Show Methods
^^^^^^^^^^^^

  .. Show-Methods-of-class-Dic-label:
  .. table:: *Show Methods of class Dic*

   +-----------------+-----------------------------------------------------+
   |Name             |Description                                          |
   +=================+=====================================================+
   |sh_keys          |Show array of keys of key list found in dictionary.  |
   +-----------------+-----------------------------------------------------+
   |show_sorted_keys |Show sorted array of keys of dictionary.             |
   +-----------------+-----------------------------------------------------+
   |sh_value_by_keys |Show value of dictionary element selected by keys    |
   +-----------------+-----------------------------------------------------+
   |sh_values_by_keys|Convert the dictionary into an array by using a key  |
   |                 |filter. The array elements are the values of all     |
   |                 |dictionary elements where the key is the given single|
   |                 |key or where the key is contained in the key list.   |
   +-----------------+-----------------------------------------------------+

Split Methods
^^^^^^^^^^^^^

  .. Split-Methods-of class-Dic-label:
  .. table:: *Split Methods of class Dic*

   +----------------------+-----------------------------------------------------------------+
   |Name                  |Description                                                      |
   +======================+=================================================================+
   |split_by_value_endwith|Split the dictionary into a tuple of dictionaries using the      |
   |                      |condition "the dictionary value ends with the given value".      |
   |                      |The first tuple element is the dictionary of all dictionary      |
   |                      |elements whose value ends with the given value; the second       |
   |                      |one is the dictionary of the other elements.                     |
   +----------------------+-----------------------------------------------------------------+
   |split_by_value        |Split the dictionary into a tuple of dictionaries using the      |
   |                      |condition "the dictionary value is equal to the given value". The|
   |                      |value. The first tuple element is the dictionary of all elements |
   |                      |whose value is equal to the given value; the second one is the   | 
   |                      |dictionary of the other elements.                                |
   +----------------------+-----------------------------------------------------------------+
   |split_by_value_is_int |Split the dictionary into a tuple of dictionaries using the      |
   |                      |condition "the element value is of type integer". The first tuple|
   |                      |element is the dictionary of all elements whose value is of type |
   |                      |integer; the second one is the dictionary of the other elements. |
   +----------------------+-----------------------------------------------------------------+

Yield Methods
^^^^^^^^^^^^^

  .. Yield-Methods-of-class-Dic-label:
  .. table:: *Yield Methods of class Dic*

   +---------------------------+----------------------------------------------------------------------------+
   |Name                       |Description                                                                 |
   +===========================+============================================================================+
   |yield_values_with_keyfilter|Yield the values of all elements which are selected by the given key filter.|
   +---------------------------+----------------------------------------------------------------------------+

*************************************
Modules for Dictionary of basic types
*************************************

Module: doc.py
==============

The Module ``doc.py`` is used to manage dictionary of callables; It contains the static class ``DoC``.

Class DoC
---------

The static Class ``DoC`` contains the subsequent methods; it contains only class- or static-methods
for the execution of callables referenced by commands.

Methods
^^^^^^^

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

   +------+------+--------------------------------------------------+
   |Name  |Type  |Description                                       |
   +======+======+==================================================+
   |ex_cmd|class |Get the command cmd from the arguments and keyword|
   |      |      |arguments list args_kwargs and call the ex        |
   |      |      |function with the given cmd.                      |
   +------+------+--------------------------------------------------+
   |ex    |class |Show and execute the function located as the value|
   |      |      |of the given cmd in the function dictionary.      |
   +------+------+--------------------------------------------------+
   |sh    |static|Show(get) the function located as the value of the|       
   |      |      |given key in the function dictionary              |       
   +------+------+--------------------------------------------------+

Method: ex_cmd
^^^^^^^^^^^^^^

Parameter
"""""""""

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

   +------+-----+-----------------------+
   |Name  |Type |Description            |
   +======+=====+=======================+
   |cls   |class|current class          |
   +------+-----+-----------------------+
   |doc   |TnDoC|Dictionary of Callables|
   +------+-----+-----------------------+
   |kwargs|TyDic|Keyword arguments      |                           
   +------+-----+-----------------------+

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

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

   +----+----+-------------------------------+
   |Name|Type|Description                    |
   +====+====+===============================+
   |    |Any |Result of the command execution|
   +----+----+-------------------------------+

Method: ex
^^^^^^^^^^

Parameter
"""""""""

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

   +-----------+--------+------------------------------+
   |Name       |Type    |Description                   |
   +===========+========+==============================+
   |cls        |class   |current class                 |
   +-----------+--------+------------------------------+
   |doc        |TnDoC   |Dictionary of Callables       |
   +-----------+--------+------------------------------+
   |key        |TnDoc   |key                           |
   +-----------+--------+------------------------------+
   |args_kwargs|TnArrDoc|arguments or keyword arguments|
   +-----------+--------+------------------------------+

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

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

   +----+----+-------------------------------+
   |Name|Type|Description                    |
   +====+====+===============================+
   |    |Any |Result of the command execution|
   +----+----+-------------------------------+

Method: sh
^^^^^^^^^^

Parameter
"""""""""

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

   +----+-----+------------------------------+
   |Name|Type |Description                   |
   +====+=====+==============================+
   |cls |class|current class                 |
   +----+-----+------------------------------+
   |doc |TnDoC|Dictionary of Callables       |
   +----+-----+------------------------------+
   |key |TnDoc|key                           |
   +----+-----+------------------------------+

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

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

   +----+----------+-----------+
   |Name|Type      |Description|
   +====+==========+===========+
   |fnc |TyCallable|Function   |
   +----+----------+-----------+

**************************************
Modules for Dictionary of dictionaries
**************************************

  .. Modules-for-Dictionary-of-dictionaries-label:
  .. table:: *Modules for Dictionary of dictionaries*

   +---------+---------------------------------------------------------+
   |Name     |Description                                              |
   +=========+=========================================================+
   |dodoa.py |Management of Dictionary of dictionaries of arrays.      |
   +---------+---------------------------------------------------------+
   |dodod.py |Management of Dictionary of dictionaries of dictionaries.|
   +---------+---------------------------------------------------------+
   |dodows.py|Management of Dictionary of dictionaries of worksheets.  |
   +---------+---------------------------------------------------------+
   |dod.py   |Management of Dictionary of dictionaries.                |
   +---------+---------------------------------------------------------+

Module: dodoa.py
================

The Module ``dodoa.py`` contains the static class ``DoDoA``:

Class: DoDoA
------------

The static Class ``DoDoA`` is used to manage Dictionary of Dictionaries of Arrays;
it contains the subsequent methods.

Methods
^^^^^^^

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

   +-------------+------------------------------------------------------+
   |Name         |Description                                           |
   +=============+======================================================+
   |append       |                                                      |
   +-------------+------------------------------------------------------+
   |sh_union     |                                                      |
   +-------------+------------------------------------------------------+

Module: dodod.py
================

Classes
-------

The Module ``dodod.py`` contains the static Class ``DoDoD``:

Class: DoDoD
------------

The static Class ``DoDoD`` is used to manage Dictionary of Dictionaries of Dictionaries;
it contains the subsequent methods.

Methods
^^^^^^^

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

   +------------+------------------------------------------------------+
   |Name        |Description                                           |
   +============+======================================================+
   |set         |                                                      |
   +------------+------------------------------------------------------+
   |yield_values|                                                      |
   +------------+------------------------------------------------------+

Module: dod.py
==============

Classes
-------

The Module ``dod.py`` contains the static Class ``DoD``:


Class: DoD
----------

The static Class ``DoD`` is used to manage ``Dictionary of Dictionaries``;
it contains the subsequent methods.

Methods
^^^^^^^

  .. Methods-of_class-DoD-label:
  .. table:: *DoD Methods*

   +---------------+-------------------------------------------------------+
   |Name           |Description                                            |
   +===============+=======================================================+
   |nvl            |Return the Dictionary of Dictionaries if it is not None|
   |               |otherwise return the empty Dictionary "{}".            |
   +---------------+-------------------------------------------------------+
   |replace_keys   |Recurse through the Dictionary while building a new one|
   |               |with new keys and old values; the old keys are         |
   |               |translated to new ones by the keys Dictionary.         |
   +---------------+-------------------------------------------------------+
   |yield_values   |                                                       |
   +---------------+-------------------------------------------------------+

Module: dodows.py
=================

Classes
-------

The Module ``dodows.py`` contains the static Class ``DoDoWs``:

Class: DoDoWs
-------------

The static Class ``DoDoWs`` is used to manage ``Dictionary of Dictionaries of Worksheets``;
it contains the subsequent methods.

Methods
^^^^^^^

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

   +--------------+------------------------------------------------------------------+
   |Name          |Description                                                       |
   +==============+==================================================================+
   |write_workbook|Write a workbook using a Dictionary of Dictionaries of worksheets.|
   +--------------+------------------------------------------------------------------+

********************************
Module for Dictionary of Objects
********************************

The Module Type ``Dictionary of Objects`` contains the following Modules:

  .. Dictionaries-of-Ojects-Module-label:
  .. table:: *Dictionaries of Ojects Module*

   +------+------------------------------------+
   |Name  |Description                         |
   +======+====================================+
   |doo.py|Management of Dictionary of Objects.|
   +------+------------------------------------+

Module: doo.py
==============

The Module ``doo.py`` contains the static Classes ``DoO``.

Class: DoO
----------

The static Class ``DoO`` is used to manage ``Dictionary of Objects``; it contains the subsequent methods.

Methods
^^^^^^^

  .. DoO-Methods-label:
  .. table:: *DoO Methods*

   +------------+---------------------------------------------------------------+
   |Name        |Description                                                    |
   +============+===============================================================+
   |replace_keys|Replace the keys of the given Dictionary by the values found in|
   |            |the given keys Dictionary if the values are not Dictionaries;  |
   |            |otherwise the function is called with these values.            |
   +------------+---------------------------------------------------------------+

************************************
Modules for Dictionary of Dataframes
************************************

Modules
=======

The Module Type ``Dictionary of Dataframes`` contains the following Modules:

  .. Dictionary-of-Dataframes-Modules-label:
  .. table:: *Dictionary of Dataframes Modules*

   +---------+----------------------------------------------+
   |Name     |Description                                   |
   +=========+==============================================+
   |dopddf.py|Management of Dictionary of Panda Dataframes. |
   +---------+----------------------------------------------+
   |dopldf.py|Management of Dictionary of Polars Dataframes.|
   +---------+----------------------------------------------+

Module: dopddf.py
=================

The Module ``dopddf.py`` contains only the static Class ``DoPdDf``.


Class: DoPdDf
-------------

The static Class ``DoPdDf`` is used to manage ``Dictionaries of Panda Dataframes``;
it contains the subsequent methods.

Methods
^^^^^^^

  .. Methods-of-class-DoPdDf-label:
  .. table:: *Methodsc of class DoPdDf*

   +----------------------+-----------------------------------------------------+
   |Name                  |Description                                          |
   +======================+=====================================================+
   |set_ix_drop_key_filter|Apply Function set_ix_drop_col_filter to all Panda   |
   |                      |Dataframe values of given Dictionary.                |
   +----------------------+-----------------------------------------------------+
   |to_doaod              |Replace NaN values of Panda Dataframe values of given|
   |                      |Dictionary and convert them to Array of Dictionaries.|
   +----------------------+-----------------------------------------------------+

Module: dopldf.py
==================

The Module ``dopldf.py`` contains only the static Class ``DoPlDf``:


Class: DoPlDf
-------------

The static Class ``DoPlDf`` is used to manage ``Dictionary of Polars Dataframes``;
it contains the subsequent Methods.

Methods
^^^^^^^

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

   +--------+------------------------------------------------------+
   |Name    |Description                                           |
   +========+======================================================+
   |to_doaod|Replace NaN values of Polars Dataframe values of given|
   |        |Dictionary and convert them to Array of Dictionaries. |
   +--------+------------------------------------------------------+

########
Appendix
########

***************
Package Logging
***************

Description
===========

Logging use the module **log.py** of the logging package **ut_log**.
The module supports two Logging types:

#. **Standard Logging** (std) or 
#. **User Logging** (usr).

The Logging type can be defined by one of the values 'std' or 'usr' of the parameter log_type; 'std' is the default.
The different Logging types are configured by one of the following configuration files:

#. **log.std.yml** or 
#. **log.usr.yml** 
  
The configuration files can be stored in different configuration directories (ordered by increased priority):

#. <package directory of the log package **ut_log**>/**cfg**,
#. <package directory of the application package **ui_eviq_srr**>/**cfg**,
#. <application directory of the application **eviq**>/**cfg**,

The active configuration file is the configuration file in the directory with the highest priority.

Examples
========
  
Site-packages-path = **/appl/eviq/.pyenv/versions/3.11.12/lib/python3.11/site-packages**
Log-package = **ut_log**
Application-package = **ui_eviq_srr**
Application-home-path = **/appl/eviq**
  
.. Examples-of-log-configuration-files-label:
.. table:: **Examples of log configuration-files**

   +-----------------------------------------------------------------------------------+
   |Log Configuration                                                                  |
   +----+-------------------+----------------------------------------------+-----------+
   |Type|Directory Type     |Directory                                     |File       |
   +====+===================+==============================================+===========+
   |std |Log package        |<Site-packages-path>/<Log-package>/cfg        |log.std.yml|
   |    +-------------------+----------------------------------------------+           |
   |    |Application package|<Site-packages-path>/<application-package>/cfg|           |
   |    +-------------------+----------------------------------------------+           |
   |    |Application        |<application-home-path>/cfg                   |           |
   +----+-------------------+----------------------------------------------+-----------+
   |usr |Log package        |<site-packages-path>/ut_log/cfg               |log.usr.yml|
   |    +-------------------+----------------------------------------------+           |
   |    |Application package|<site-packages-path>/ui_eviq_srr/cfg          |           |
   |    +-------------------+----------------------------------------------+           |
   |    |Application        |<application-path>/cfg                        |           |
   +----+-------------------+----------------------------------------------+-----------+

Log message types
=================

Logging defines log file path names for the following log message types: .

#. *debug*
#. *info*
#. *warning*
#. *error*
#. *critical*

Log types and Log directories
-----------------------------

Single or multiple Application log directories can be used for each message type:

.. Log-types-and-Log-directories-label:
.. table:: *Log types and directoriesg*

   +--------------+---------------+
   |Log type      |Log directory  |
   +--------+-----+--------+------+
   |long    |short|multiple|single|
   +========+=====+========+======+
   |debug   |dbqs |dbqs    |logs  |
   +--------+-----+--------+------+
   |info    |infs |infs    |logs  |
   +--------+-----+--------+------+
   |warning |wrns |wrns    |logs  |
   +--------+-----+--------+------+
   |error   |errs |errs    |logs  |
   +--------+-----+--------+------+
   |critical|crts |crts    |logs  |
   +--------+-----+--------+------+

Application parameter for logging
---------------------------------

.. Application-parameter-used-in-log-naming-label:
.. table:: *Application parameter used in log naming*

   +-----------------+--------------+-----+------------------+-------+-----------+
   |Name             |Decription    |Value|Description       |Default|Example    |
   +=================+==============+=====+==================+=======+===========+
   |appl_data        |data directory|     |                  |       |/data/eviq |
   +-----------------+--------------+-----+------------------+-------+-----------+
   |tenant           |tenant name   |UMH  |                  |       |UMH        |
   +-----------------+--------------+-----+------------------+-------+-----------+
   |package          |package name  |     |                  |       |ui_eviq_srr|
   +-----------------+--------------+-----+------------------+-------+-----------+
   |cmd              |command       |     |                  |       |evupreg    |
   +-----------------+--------------+-----+------------------+-------+-----------+
   |log_type         |Logging Type  |std: |Standard logging  |std    |std        |
   |                 |              +-----+------------------+       |           |
   |                 |              |usr: |User Logging      |       |           |
   +-----------------+--------------+-----+------------------+-------+-----------+
   |log_ts_type      |Logging       |ts:  |Sec since 1.1.1970|ts     |ts         |
   |                 |timestamp     +-----+------------------+       |           |
   |                 |type          |dt:  |Datetime          |       |           |
   +-----------------+--------------+-----+------------------+-------+-----------+
   |log_sw_single_dir|Use single log|True |use single dir.   |True   |True       |
   |                 |directory     +-----+------------------+       |           |
   |                 |              |False|use muliple dir.  |       |           |
   +-----------------+--------------+-----+------------------+-------+-----------+

Log files naming
----------------

Naming Conventions (table format)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. Naming-conventions-for-logging-file-paths-label:
.. table:: *Naming conventions for