ut-xls 2.0.0.20251021
Utilities for Excel files.
Requires Python: >=3.10

######
ut_xls
######

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

.. start short_desc

**Excel 'Utilities'**

.. end short_desc

.. start long_desc

**The package ut_xls ís a collection of interface modules to the following 'Python Excel Utilities'**

.. end long_desc

#. *openpyxl*
#. *pyexcelerate*
#. *pandas dataframe excel functions*
#. *polars dataframe excel functions*

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

.. start installation

The package ``ut_xls`` can be installed from PyPI.

To install with ``pip``:

.. code-block:: shell

	$ python -m pip install ut_xls

.. end installation

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

lassification
==============

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

#. **Special files:**

   a. *py.typed*

#. **Special modules:**

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

#. **Sub-packages**

   #. **op** **Modules for Excel files using Openpyxl**

      #. **Modules for Excel I/O control**

         #. *iocwb.py* **I/O Control Module for Excel Workbooks**

         #. **Modules for Excel Input control accessed by path key**

            #. *pathkioiwb.py* **Input Module for Excel workbooks using path key**
            #. *pathkioowb.py* **Output Module for Excel workbooks using path key**

         #. **Modules for Excel Input control accessed by path**

            #. *pathioiwb.py*  **Input Module for Excel workbooks using path**
            #. *pathioowb.py*  **Output Module for Excel workbooks using path**
            #. *pathiouwb.py*  **Update Module for Excel workbooks using path**
            #. *pathioiws.py*  **Input Module for Excel worksheets using path**

      #. *wb.py* **Module for Excel workbook processing**
      #. *ws.py* **Module for Excel worksheet processing**
      #. *rw.py* **Module for Excel worksheet row processing**

   #. **pd** **Modules for Excel files using pandas**

      #. **Excel I/O module**

         #. *pathkioiwb.py*
         #. *pathioiwb.py*
         #. *pathioowb.py*

   #. **pe** **Modules for Excel files using pyexcelerate**

      #. **Excel modules for dictionary of arrays**

         #. *doaos.py*
         #. *doaod.py*

      #. **Excel I/O modules**

         #. *iocwb.py*
         #. *pathkioowb.py*
         #. *pathioowb.py*

   #. **pl** **Modules for Excel files using pyexcelerate**

      #. *pathioiwb.py*

**************************************
I/O Control Module for Excel Workbooks
**************************************

Module: iocwb.py
================

The Module iocwb.py is used to control I/O for Excel Worksheets using the Openpyxl package;
it contains the following static classes:

  .. Static-classes-of-module-iocwb.py-label:
  .. table:: *Static classes of module iocwb.py*

   +-----------+-----------------------------+
   |Name       |Description                  |
   +===========+=============================+
   |SheetNms   |Manage Excel worksheet Names.|
   +-----------+-----------------------------+
   |Ws         |Manage Excel worksheets.     |
   +-----------+-----------------------------+

Class SheetNms
---------------

Methods
^^^^^^^

  .. Methods-of-static-class-SheetNms-label:
  .. table:: *Methods of static class SheetNms*

   +-----------+--------------------------+
   |Name       |Description               |
   +===========+==========================+
   |sh_sheetnms|Show Excel workheet names.|
   +-----------+--------------------------+
   |sh_sheetnm |Show Excel workheet name. |
   +-----------+--------------------------+

Method: sh_sheetnms
^^^^^^^^^^^^^^^^^^^

  .. Parameter-of-method-sh_sheetnms-label:
  .. table:: *Parameter of method sh_sheetnms*

   +--------+----------+----------------------------+
   |Name    |Type      |Description                 |
   +========+==========+============================+
   |cls     |class     |current class.              |
   +--------+----------+----------------------------+
   |sheetnms|TySheetnms|Excel sheet names.          |
   +--------+----------+----------------------------+
   |sheet   |TyAoSheet |Excel array of Excel sheets.|
   +--------+----------+----------------------------+

  .. Return-values-of-method-sh_sheetnms-label:
  .. table:: *Return value of method sh_sheetnms*

   +--------+----------+------------------+
   |Name    |Type      |Description       |
   +========+==========+==================+
   |sheetnms|TySheetnms|Excel sheet names.|
   +--------+----------+------------------+

Class Ws
--------

The class ``Ws`` contains:

#. the static subclass ``Headers``,
#. static- or class-methods.

Subclass: Headers
^^^^^^^^^^^^^^^^^                     

  .. Methods-of-static-subclass-Headers-label:
  .. table:: *Methods of static class Headers*

   +-----------+-------------------------------+
   |Name       |Description                    |
   +===========+===============================+
   |iter_column|Iterate over Worksheet columns.|
   +-----------+-------------------------------+

Methods
^^^^^^^

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

   +----------------------------------+----------------------------------------------+
   |Name                              |Description                                   |
   +==================================+==============================================+
   |append_rows                       |Ierate over workbook sheet names.             |
   +----------------------------------+----------------------------------------------+
   |filter_rows                       |Iterate over workbook sheets.                 |
   +----------------------------------+----------------------------------------------+
   |iter_sheet_lst                    |                                              |
   +----------------------------------+----------------------------------------------+
   |sh_headers                        |                                              |
   +----------------------------------+----------------------------------------------+
   |sh_aoa                            |                                              |
   +----------------------------------+----------------------------------------------+
   |sh_id                             |                                              |
   +----------------------------------+----------------------------------------------+
   |sh_chartsheet                     |                                              |
   +----------------------------------+----------------------------------------------+
   |sh_worksheet                      |                                              |
   +----------------------------------+----------------------------------------------+
   |to_aod_apply_fnc_to_value         |                                              |
   +----------------------------------+----------------------------------------------+
   |to_aod_apply_str_to_value         |                                              |
   +----------------------------------+----------------------------------------------+
   |to_rows                           |                                              |
   +----------------------------------+----------------------------------------------+
   |to_row_values                     |                                              |
   +----------------------------------+----------------------------------------------+
   |to_dic                            |                                              |
   +----------------------------------+----------------------------------------------+
   |update_ws_cell_from_df_with_d_body|                                              |
   +----------------------------------+----------------------------------------------+
   |update_ws_cell_with_d_head        |                                              |
   +----------------------------------+----------------------------------------------+

*********************************************************
Input module for Excel workbooks accessed with path names
*********************************************************

Module: pathkioiwb.py
======================

The Module ``pathkioiwb.py`` is used to control Input processing for Excel Worksheets 
refered by patn-names using the Openpyxl package;
it contains the following static class ``IoiPathnmWb``:

Methods
-------

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

   +-----------------------+----------------------------------------------+
   |Name                   |Description                                   |
   +=======================+==============================================+
   |load                   |Ierate over workbook sheet names.             |
   +-----------------------+----------------------------------------------+
   |read_wb_to_aod         |Iterate over workbook sheets.                 |
   +-----------------------+----------------------------------------------+
   |read_wb_to_doaod       |Iterate over workbook sheets.                 |
   +-----------------------+----------------------------------------------+
   |read_wb_to_aod_or_doaod|Iterate over workbook sheets.                 |
   +-----------------------+----------------------------------------------+
   |read_wb_to_aoa         |Iterate over workbook sheets.                 |
   +-----------------------+----------------------------------------------+
   |sh_wb_adm              |Iterate over workbook sheets.                 |
   +-----------------------+----------------------------------------------+
   |sh_wb_del              |Iterate over workbook sheets.                 |
   +-----------------------+----------------------------------------------+
   |sh_wb_reg              |Iterate over workbook sheets.                 |
   +-----------------------+----------------------------------------------+

***************************************************
Input module for Excel workbooks accessed with path
***************************************************

Module: pathioiwb.py
====================

The Module ``pathioiwb.py`` is used to control Input processing for Excel Worksheets 
refered by patn-names using the Openpyxl package;
it contains the following static class ``IoiPathWb``:

Methods
-------

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

   +-----------------------+----------------------------------------------------+
   |Name                   |Description                                         |
   +=======================+====================================================+
   |load                   |Load Excel workbook accessed by path                |
   +-----------------------+----------------------------------------------------+
   |read_wb_to_aod         |Read Excel workbook accessed by path into array of  |
   |                       |dictionaries.                                       |
   +-----------------------+----------------------------------------------------+
   |read_wb_to_doaod       |Read Excel workbook accessed by path into           |
   |                       |dictionary of array of dictionaries.                |
   +-----------------------+----------------------------------------------------+
   |read_wb_to_aod_or_doaod|Read Excel workbook accessed by path into array of  |
   |                       |dictionaries or dictionary of array of dictionaries.|
   +-----------------------+----------------------------------------------------+
   |read_wb_to_aoa         |Read Excel workbook accessed by path into array of  |
   |                       |arrays.                     .                       |
   +-----------------------+----------------------------------------------------+
   |sh_wb_adm              |Show Excel workbook with admin sheet.               |
   +-----------------------+----------------------------------------------------+
   |sh_wb_del              |Show Excel workbook with delete sheet.              |
   +-----------------------+----------------------------------------------------+
   |sh_wb_reg              |Show Excel workbook with regular (admin or delete)  |
   |                       |sheets.                                             |
   +-----------------------+----------------------------------------------------+

*********************************************************
Input module for Excel workbooks accessed with path names
*********************************************************

Module: pathioiws.py
====================

The Module ``pathioiws.py`` is used to control Input processing for Excel Worksheets 
refered by patn-names using the Openpyxl package;
it contains the following static class ``IoiPathWs``:

Methods
-------

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

   +-------------------+-----------------------------------------------------+
   |Name               |Description                                          |
   +===================+=====================================================+
   |read_ws_to_dic     |Read Excel workbook accessed by path into dictionary.|
   +-------------------+-----------------------------------------------------+
   |read_ws_to_aod     |Read Excel workbook accessed by path into array of   |
   |                   |dictionaries.                                        |
   +-------------------+-----------------------------------------------------+
   |read_ws_filter_rows|Read Excel workbook accessed by path into array of   |
   |                   |dictionaries.                                        |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_aoa     |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_sheetnames    |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_doaoa   |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_dowsop  |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+

**********************************************************
Output module for Excel workbooks accessed with path names
**********************************************************

Module: pathkioowb.py
======================

The Module ``pathkioowb.py`` is used to control Output processing for Excel Worksheets 
refered by patn-names using the Openpyxl package;
it contains the following static class ``IooPathNmWb``:

Methods
-------

  .. Methods-of-class-IooPathNmWb-label:
  .. table:: *Methods of class IooPathNmbs*

   +-------------------+-----------------------------------------------------+
   |Name               |Description                                          |
   +===================+=====================================================+
   |read_ws_to_dic     |Read Excel workbook accessed by path into dictionary.|
   +-------------------+-----------------------------------------------------+
   |read_ws_to_aod     |Read Excel workbook accessed by path into array of   |
   |                   |dictionaries.                                        |
   +-------------------+-----------------------------------------------------+
   |read_ws_filter_rows|Read Excel workbook accessed by path into array of   |
   |                   |dictionaries.                                        |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_aoa     |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_sheetnames    |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_doaoa   |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_dowsop  |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+

****************************************************
Output Module for Excel workbooks accessed with path
****************************************************

Module: pathioowb.py
======================

The Module ``pathioowb.py`` is used to control Output processing for Excel Worksheets 
refered by patn-names using the Openpyxl package;
it contains the following static class ``IooPathWb``:

Methods
-------

  .. Methods-of-class-IooPathNmWb-label:
  .. table:: *Methods of class IooPathNmbs*

   +-------------------+-----------------------------------------------------+
   |Name               |Description                                          |
   +===================+=====================================================+
   |read_ws_to_dic     |Read Excel workbook accessed by path into dictionary.|
   +-------------------+-----------------------------------------------------+
   |read_ws_to_aod     |Read Excel workbook accessed by path into array of   |
   |                   |dictionaries.                                        |
   +-------------------+-----------------------------------------------------+
   |read_ws_filter_rows|Read Excel workbook accessed by path into array of   |
   |                   |dictionaries.                                        |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_aoa     |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_sheetnames    |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_doaoa   |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_dowsop  |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+

****************************************************
Update Module for Excel workbooks accessed with path
****************************************************

Module: pathioowb.py
======================

The Module ``pathioowb.py`` is used to control Output processing for Excel Worksheets 
refered by patn-names using the Openpyxl package;
it contains the following static class ``IooPathWb``:

Methods
-------

  .. Methods-of-class-IooPathNmWb-label:
  .. table:: *Methods of class IooPathNmbs*

   +-------------------+-----------------------------------------------------+
   |Name               |Description                                          |
   +===================+=====================================================+
   |read_ws_to_dic     |Read Excel workbook accessed by path into dictionary.|
   +-------------------+-----------------------------------------------------+
   |read_ws_to_aod     |Read Excel workbook accessed by path into array of   |
   |                   |dictionaries.                                        |
   +-------------------+-----------------------------------------------------+
   |read_ws_filter_rows|Read Excel workbook accessed by path into array of   |
   |                   |dictionaries.                                        |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_aoa     |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_sheetnames    |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_doaoa   |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+
   |read_ws_to_dowsop  |Read Excel workbook accessed by path int oarray of   |
   |                   |arrays.                                              |
   +-------------------+-----------------------------------------------------+

******************************************
Modules for Excel worksheet row processing
******************************************

Module: rw.py
=============

The Module rw.py is used to manage Excel Worksheet rows using the Openpyxl package;
it contains the following static class:

  .. Static-classes-of-module-rw.py-label:
  .. table:: *Static classes of module rw.py*

   +----+---------------------------+
   |Name|Description                |
   +====+===========================+
   |Rw  |Manage Excel worksheet rows|
   +----+---------------------------+

Class Rw
--------

Methods
^^^^^^^

  .. Methods-of-static-class-Rw-label:
  .. table:: *Methods of static class Rw*

   +---------------+------------------------------------------------+
   |Name           |Description                                     |
   +===============+================================================+
   |iter_cell_value|Iterate over cell values of Excel worksheet rows|
   +---------------+------------------------------------------------+

Method: iter_cell_value
^^^^^^^^^^^^^^^^^^^^^^^

  .. Parameter-of-method-iter_cell_value-label:
  .. table:: *Parameter of method iter_cell_value*

   +---------+-----------+--------------------+
   |Name     |Type       |Description         |
   +=========+===========+====================+
   |cls      |class      |current class       |
   +---------+-----------+--------------------+
   |row      |TyTupleCell|Excel Worksheet rows|
   +---------+-----------+--------------------+
   |\**kwargs|TyAny      |Keyword arguments   |
   +---------+-----------+--------------------+

  .. Yield-value-of-method-iter_cell_value-label:
  .. table:: *Yield value of method iter_cell_value*

   +----------+-----+------------------------------+
   |Name      |Type |Description                   |
   +==========+=====+==============================+
   |cell.value|TyAny|Excel Worksheet row cell value|
   +----------+-----+------------------------------+

*************************************
Modules for Excel workbook processing
*************************************

Module: wb.py
=============

The Module wb.py is used to manage Excel Workbooks using the Openpyxl package;
it contains the following static classes:

  .. Static-classes-of-Input-I/O-module-ioipath.py-label:
  .. table:: *Static Classes of Input I/O Module ioipath.py*

   +-----+---------------------------------------------------+
   |Name |Description                                        |
   +=====+===================================================+
   |DoAoA|Manage workbooks from Dictionaries of Arrays.      |
   +-----+---------------------------------------------------+
   |DoAoA|Manage workbooks from Dictionaries of dictionaries.|
   +-----+---------------------------------------------------+
   |Wb   |Manage workbooks.                                  |
   +-----+---------------------------------------------------+

Class DoAoA
-----------

Methods
^^^^^^^

  .. Methods-of-static-class-DoAoA-label:
  .. table:: *Methods of static class DoAoA*

   +---------+----------------------------------------------+
   |Name     |Description                                   |
   +=========+==============================================+
   |create_wb|Create Excel Workbook from Dictionary of array|
   |         |of arrays using the openpyxel package.        |
   +---------+----------------------------------------------+

Method: create_wb
^^^^^^^^^^^^^^^^^

  .. Parameter-of-method-create_wb-label:
  .. table:: *Parameter of method create_wb*

   +-----+-------+-----------------------------------+
   |Name |Type   |Description                        |
   +=====+=======+===================================+
   |doaoa|TyDoAoA|Dictionary of array of dictionaries|
   +-----+-------+-----------------------------------+

  .. Return-values-of-method-create_wb-label:
  .. table:: *Return value of method create_wb*

   +----+----+----------------------------------+
   |Name|Type|Description                       |
   +====+====+==================================+
   |wb  |TyWb|Excel Workbook of Openpyxl package|
   +----+----+----------------------------------+

Class DoAoD
-----------

Methods
^^^^^^^

  .. Methods-of-static-class-DoAoD-label:
  .. table:: *Methods of static class DoAoD*

   +---------+----------------------------------------------+
   |Name     |Description                                   |
   +=========+==============================================+
   |create_wb|Create Excel Workbook from Dictionary of array|
   |         |of dictionaries using the openpyxxel package. |
   +---------+----------------------------------------------+

Method: create_wb
^^^^^^^^^^^^^^^^^

  .. Parameter-of-method-create_wb-label:
  .. table:: *Parameter of method create_wb*

   +-----+-------+-----------------------------------+
   |Name |Type   |Description                        |
   +=====+=======+===================================+
   |doaoa|TyDoAoA|Dictionary of array of dictionaries|
   +-----+-------+-----------------------------------+

  .. Return-values-of-method-create_wb-label:
  .. table:: *Return value of method create_wb*

   +----+----+----------------------------------+
   |Name|Type|Description                       |
   +====+====+==================================+
   |wb  |TyWb|Excel Workbook of Openpyxl package|
   +----+----+----------------------------------+

Class Wb
--------

Methods
^^^^^^^

  .. Methods-of-static-class-Wb-label:
  .. table:: *Methods of static class Wb*

   +--------------------------+----------------------------------------------+
   |Name                      |Description                                   |
   +==========================+==============================================+
   |iter_sheet_names          |Ierate over workbook sheet names.             |
   +--------------------------+----------------------------------------------+
   |iter_sheet                |Iterate over workbook sheets.                 |
   +--------------------------+----------------------------------------------+
   |sh_sheetnm                |                                              |
   +--------------------------+----------------------------------------------+
   |sh_sheetnms               |                                              |
   +--------------------------+----------------------------------------------+
   |sh_sheet_by_sheetnm       |                                              |
   +--------------------------+----------------------------------------------+
   |sh_sheet                  |                                              |
   +--------------------------+----------------------------------------------+
   |sh_chartsheet_by_sheetnm  |                                              |
   +--------------------------+----------------------------------------------+
   |sh_chartsheet             |                                              |
   +--------------------------+----------------------------------------------+
   |sh_worksheet_by_sheetnm   |                                              |
   +--------------------------+----------------------------------------------+
   |sh_worksheet              |                                              |
   +--------------------------+----------------------------------------------+
   |to_aod                    |                                              |
   +--------------------------+----------------------------------------------+
   |to_doaod                  |                                              |
   +--------------------------+----------------------------------------------+
   |to_aod_or_doaod           |                                              |
   +--------------------------+----------------------------------------------+
   |createupdate_wb_with_doaoa|                                              |
   +--------------------------+----------------------------------------------+
   |update_wb_with_aoa        |                                              |
   +--------------------------+----------------------------------------------+
   |update_wb_with_aod        |                                              |
   +--------------------------+----------------------------------------------+
   |update_wb_with_doaoa      |                                              |
   +--------------------------+----------------------------------------------+
   |update_wb_with_dodf       |                                              |
   +--------------------------+----------------------------------------------+

**************************************
Modules for Excel worksheet processing
**************************************

Module: ws.py
=============

The Module ws.py is used to manage Excel Worksheets using the Openpyxl package;
it contains the following static classes:

  .. Static-classes-of-module-ws.py-label:
  .. table:: *Static classes of module ws.py*

   +-----+---------------------------------------------------+
   |Name |Description                                        |
   +=====+===================================================+
   |DoAoA|Manage workbooks from Dictionaries of Arrays       |
   +-----+---------------------------------------------------+
   |DoAoA|Manage workbooks from Dictionaries of dictionaries.|
   +-----+---------------------------------------------------+
   |Wb   |Manage workbooks.                                  |
   +-----+---------------------------------------------------+

########
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 logging file paths*

   +--------+----------------------------------------------+-------------------+
   |Type    |Directory                                     |File               |
   +========+==============================================+===================+
   |debug   |/<appl_data>/<tenant>/RUN/<package>/<cmd>/debs|debs_<ts>_<pid>.log|
   +--------+----------------------------------------------+-------------------+
   |critical|/<appl_data>/<tenant>/RUN/<package>/<cmd>/logs|crts_<ts>_<pid>.log|
   +--------+----------------------------------------------+-------------------+
   |error   |/<appl_data>/<tenant>/RUN/<package>/<cmd>/logs|errs_<ts>_<pid>.log|
   +--------+----------------------------------------------+-------------------+
   |info    |/<appl_data>/<tenant>/RUN/<package>/<cmd>/logs|infs_<ts>_<pid>.log|
   +--------+----------------------------------------------+-------------------+
   |warning |/<appl_data>/<tenant>/RUN/<package>/<cmd>/logs|rnsg_<ts>_<pid>.log|
   +--------+----------------------------------------------+-------------------+

Naming Conventions (tree format)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

 <appl_data>   Application data folder
 │
 └── <tenant>  Application tenant folder
     │
     └── RUN  Applications RUN folder for Application log files
         │
         └── <package>  RUN folder of Application package: <package>
             │
             └── <cmd>  RUN folder of Application command <cmd>
                 │
                 ├── debs  Application command debug messages folder
                 │   │
                 │   └── debs_<ts>_<pid>.log  debug messages for
                 │                            run of command <cmd>
                 │                            with pid <pid> at <ts>
                 │
                 └── logs  Application command log messages folder
                     │
                     ├── crts_<ts>_<pid>.log  critical messages for
                     │                        run of command <cmd>
                     │                        with pid <pid> at <ts>
                     ├── errs_<ts>_<pid>.log  error messages for
                     │                        run of command <cmd>
                     │                        with pid <pid> at <ts>
                     ├── infs_<ts>_<pid>.log  info messages for
                     │                        run of command <cmd>
                     │                        with pid <pid> at <ts>
                     └── wrns_<ts>_<pid>.log  warning messages for