ut-cli 2.0.0.20251020
Utilities for Communication
Requires Python: >=3.10

######
ut_cli
######

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

.. start short_desc

**Command Level Interface Utilities**

.. end short_desc

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

.. start installation

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

To install with ``pip``:

.. code-block:: shell

	$ python -m pip install ut_cli

.. end installation

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

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

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

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

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

#. **Special files:**

   a. *py.typed*

#. **Special modules:**

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

#. **Modules**

   #. **aoeq.py** *Array of Equates Module*
   #  **doeq.py** *Dictionary of Equates Module*
   #. **kwargs.py** *Kewword Arguments Module*
   #. **task.py** *Task Module*

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

Overview
========

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

   +---------+------------------------------+
   |Name     |Decription                    |
   +=========+==============================+
   |aoeq.py  |Array of Equates module.      |
   +---------+------------------------------+
   |doeq.py  |Dictionary of Equates module. |
   +---------+------------------------------+
   |kwargs.py|Keword arguments module.      |
   +---------+------------------------------+
   |task.py  |Command Line Interface module.|
   +---------+------------------------------+

Module: aoeq.py
===============

The Array of Equates  Module ``aoeq.py`` contains the single static class ``AoEq``.

Class: AoEq
-----------

The static Class ``AoEq`` is used to manage arrays of equates; it contains
no variables and only static- or class-methods.
Equates are strings of the form <key>=<value> which consist of a
<key>, <value> string pair separated by the equate character '='.

Methods
^^^^^^^

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

   +-------+-----------------------------------------------+
   |Name   |Description                                    |
   +=======+===============================================+
   |sh_d_eq|Show dictionary of equates                     |
   +-------+-----------------------------------------------+

Method: sh_d_eq
^^^^^^^^^^^^^^^
        
The show method ``sh_d_eq`` returns a dictionary of equates: the keys
are the equate keys; the values are the equate values.
For the key ``'cmd`` the value is an array which represents the command
and his nested sub-commands created by splitting the value.

Parameter
"""""""""

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

   +----+-----+-----------------------+
   |Name|Type |Description            |
   +====+=====+=======================+
   |cls |class|Current class.         |
   +----+-----+-----------------------+
   |a_eq|TyArr|Array of Equate strings|
   +----+-----+-----------------------+

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

  .. Return-Value-of-Method-sh_d_eq-label:
  .. table:: *Return Value of Method sh_d_eq*

   +----+-----+--------------------------------------------+
   |Name|Type |Description                                 |
   +====+=====+============================================+
   |a_eq|TyArr|Array of left and right substring of equate.|
   +----+-----+--------------------------------------------+

Module: doeq.py
===============

The Dictionary of Equates  module ``doeq.py`` contains the single static class ``DoEq``.

Class: DoEq
-----------

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

Methods
^^^^^^^

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

   +----------------+----------------------------------------------+
   |Name            |Description                                   |
   +================+==============================================+
   |verify_key_value|Verify the "key" and "value" with the         | 
   |                |dictionary of parameters: "d_parms".          |
   +----------------+----------------------------------------------+
   |verify_value    |Verify and convert the "value" according the  |
   |                |rules defined by the value type: "value_type".|
   +----------------+----------------------------------------------+
   |verify          |Verify the dictionary of equates: "d_eq" with |
   |                |the dictionary of parameter: "d_parms".       |
   +----------------+----------------------------------------------+

Method: verify_key_value
^^^^^^^^^^^^^^^^^^^^^^^^
        
The Method ``verify_key_value`` performs the following steps:

#. get the ``value_type`` from the dictionary of parameters ``d_parms`` by the
   key ``key``.

#. raise the exception ``wrong parameter`` if the key is not in the dictionary.

#. convert the value according to the ``value_type`` by using a string function
   of the object module ``ut_obj``.

#. return the pair ``key, converted value``.
        
Parameter
"""""""""

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

   +-------+-----+------------------------+
   |Name   |Type |Description             |
   +=======+=====+========================+
   |cls    |class|current class           |
   +-------+-----+------------------------+
   |key    |TyStr|Equate key              |
   +-------+-----+------------------------+
   |value  |TyStr|Equate value            |
   +-------+-----+------------------------+
   |d_parms|TyDic|Dictionary of parameters|
   +-------+-----+------------------------+

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

  .. Return-Value-of-Method-verify_key_value-label:
  .. table:: *Return Value of Method verify_key_value*

   +------+-----+------------------------------------------------+
   |Name  |Type |Description                                     |
   +======+=====+================================================+
   |key,  |TyTup|Original key and formated value according to the|
   |_value|     |type defined by the dictionary of parameters.   |
   +------+-----+------------------------------------------------+

Method: verify_value
^^^^^^^^^^^^^^^^^^^^
        
The Method ``verify_value`` performs the following steps:

#. Convert the ``value_type`` into a range of type ``array`` or ``dictionary``.

#. Raise the execption: ``value is not contained in the range`` if the ``value`` is not
   contained in the range. 
        
Parameter
"""""""""

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

   +----------+-----+-------------+
   |Name      |Type |Description  |
   +==========+=====+=============+
   |cls       |class|current class|
   +----------+-----+-------------+
   |value     |TyStr|Equate value |
   +----------+-----+-------------+
   |value_type|TyStr|Type of value|
   +----------+-----+-------------+


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

The Method ``verify_value`` does not return any value.

Method: verify
^^^^^^^^^^^^^^
        
The Method ``verify`` performs the following steps:

#. Return the dictionary of equates ``d_eq`` if the dictionary of parameters ``d_parms``
   is undefined or empty.

#. Get the command ``_cmd`` from the dictionary of equates by using the key 'cmd'.

#. Locate the dictionary of command parameters ``_d_parms_cmd`` in the dictionary of
   parameters by the key ``_cmd`` of type array (if the key is not found an exception is raised).

#. Verify the items ``k``, ``v`` of the dictionary of equates ``d_eq`` and create a new
   dictionary ``_d_eq_new`` of the verified items.

#. Return the new dictionary ``_d_eq_new`` of verified items.
        
Parameter
"""""""""

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

   +-------+-----+------------------------+
   |Name   |Type |Description             |
   +=======+=====+========================+
   |cls    |class|current class           |
   +-------+-----+------------------------+
   |d_eq   |TyDic|Dictionary of Equates   |
   +-------+-----+------------------------+
   |d_parms|TnDic|Dictionary of parameters|
   +-------+-----+------------------------+

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

  .. Return-Value-of-Method-verify-label:
  .. table:: *Return Value of Method verify*

   +---------+------+---------------------+
   |Name     |Type  |Description          |
   +=========+======+=====================+
   |_d_eq_new|TyDoEq|Dictionary of Equates|
   +---------+------+---------------------+

Module: kwargs.py
=================

The Keyword arguments  Module ``kwargs.py`` contains the single static class ``Kwargs``.

Class: Kwargs
-------------

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

Methods
^^^^^^^

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

   +---------------+----------------------------------------+
   |Name           |Description                             |
   +===============+========================================+
   |sh_t_parms_task|Show tuple of parameter- and task-class.| 
   +---------------+----------------------------------------+
   |sh             |Show dictionary of keyword arguments.   |
   +---------------+----------------------------------------+

Method: sh_t_parms_task
^^^^^^^^^^^^^^^^^^^^^^^
        
The Method ``sh_t_parms_task`` performs the following steps:
#. Locate the current package path
#. Get the file-paths of the modules ``parms``, ``task``.
#. Import the modules ``parms``, ``task`` using the file-paths.
#. Return the tuple of classes ``Parms``, ``Task``.
        
Parameter
"""""""""

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

   +-------+-----+------------------------+
   |Name   |Type |Description             |
   +=======+=====+========================+
   |cls    |class|current class           |
   +-------+-----+------------------------+
   |key    |TyStr|Equate key              |
   +-------+-----+------------------------+
   |value  |TyStr|Equate value            |
   +-------+-----+------------------------+
   |d_parms|TyDic|Dictionary of parameters|
   +-------+-----+------------------------+

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

  .. Return-Value-of-Method-sh_t_parms_task-label:
  .. table:: *Return Value of Method sh_t_parms_task*

   +------+-----+------------------------------------------------+
   |Name  |Type |Description                                     |
   +======+=====+================================================+
   |key,  |TyTup|Original key and formated value according to the|
   |_value|     |type defined by the dictionary of parameters.   |
   +------+-----+------------------------------------------------+

Method: sh
^^^^^^^^^^
        
The Method ``sh`` performs the following steps:

#. Get the array of arguments as subarray of the array of system arguments starting at
   the second element.

#. Show the dictionary of equates ``_d_eq`` with the function ``sh_d_eq`` of class ``AoEq``
   using the array of arguments ``_args`` as parameter.

#. Show the tuple of classes ``_cls_parms, _cls_task`` with the function ``sh_t_parms_task``
   of the current class.

#. Show the dictionary of keyword arguments ``kwargs`` with the verify function ``verify``
   function of class ``DoEq``.
        
Parameter
"""""""""

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

   +--------+-----+--------------------------------+
   |Name    |Type |Description                     |
   +========+=====+================================+
   |cls_com |class|Com class                       |
   +--------+-----+--------------------------------+
   |cls_app |class|App class                       |
   +--------+-----+--------------------------------+
   |sys_argv|TyArr|Array of system argument values.|
   +--------+-----+--------------------------------+

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

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

   +---------+-----+---------------------+
   |Name     |Type |Description          |
   +=========+=====+=====================+
   |_d_eq_new|TyDic|Dictionary of Equates|
   +---------+-----+---------------------+

Module: task.py
===============

The Keyword arguments  Module ``task.py`` contains the single static class ``Task``.

Class: Task
-----------

The static Class ``Task`` is used run the do method of the task class localised in the
dictionary of keyword arguments ``kwargs`` with the key ``cls_task``;
it contains no variables and only static- or class-methods.

Methods
^^^^^^^

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

   +----+------------------------------------+
   |Name|Description                         |
   +====+====================================+
   |do  |Run the do method of the task class.| 
   +----+------------------------------------+

Method: do
^^^^^^^^^^
        
The Method ``do`` performs the following steps:
#. Locate the current task class in the dictionary of keyword arguments with the key 'cls_task'.
#. Run the ``do`` method of the current task class ``_cls_task`` with the parameter ``kwargs``.
        
Parameter
"""""""""

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

   +-------+-----+--------------------------------+
   |Name   |Type |Description                     |
   +=======+=====+================================+
   |cls    |class|current class.                  |
   +-------+-----+--------------------------------+
   |kwargs |TyDic|Dictionary of kewaord arguments.|
   +-------+-----+--------------------------------+

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

The Method ``do`` does not return any value.

########
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
                                              run of command <cmd>
                                              with pid <pid> at <ts>

Naming Examples (table format)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

   +--------+--------------------------------------------+--------------------------+
   |Type    |Directory                                   |File                      |
   +========+============================================+==========================+
   |debug   |/appl/eviq/UMH/RUN/ui_eviq_srr/evdomap/debs/|debs_1750096540_354710.log|
   +--------+--------------------------------------------+--------------------------+
   |critical|/appl/eviq/UMH/RUN/ui_eviq_srr/evdomap/logs/|crts_1749971151_240257.log|
   +--------+                                            +--------------------------+
   |error   |                                            |errs_1749971151_240257.log|
   +--------+                                            +--------------------------+
   |info    |                                            |infs_1750096540_354710.log|
   +--------+                                            +--------------------------+
   |warning |                                            |wrns_1749971151_240257.log|
   +--------+--------------------------------------------+--------------------------+

Naming Examples (tree format)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

  /data/eviq/UMH/RUN/ui_eviq_srr/evdomap  Run folder of
  │                                       of function evdomap
  │                                       of package ui_eviq_srr
  │                                       for teanant UMH
  │                                       of application eviq
  │
  ├── debs  debug folder of Application function: evdomap
  │   │
  │   └── debs_1748609414_314062.log  debug messages for run 
  │                                   of function evdomap     
  │                                   using pid: 314062 at: 1748609414
  │
  └── logs  log folder of Application function: evdomap
      │
      ├── errs_1748609414_314062.log  error messages for run
      │                               of function evdomap     
      │                               with pid: 314062 at: 1748609414
      ├── infs_1748609414_314062.log  info messages for run
      │                               of function evdomap     
      │                               with pid: 314062 at: 1748609414
      └── wrns_1748609414_314062.log  warning messages for run
                                      of function evdomap     
                                      with pid: 314062 at: 1748609414

Configuration files
===================

log.std.yml (jinja2 yml file)
-----------------------------

Content
^^^^^^^

.. log.std.yml-label:
.. code-block:: jinja

 version: 1

 disable_existing_loggers: False

 loggers:

     # standard logger
     std:
         # level: NOTSET
         level: DEBUG
         handlers:
             - std_debug_console
             - std_debug_file
             - std_info_file
             - std_warning_file
             - std_error_file
             - std_critical_file

 handlers:
 
     std_debug_console:
         class: 'logging.StreamHandler'
         level: DEBUG
         formatter: std_debug
         stream: 'ext://sys.stderr'

     std_debug_file:
         class: 'logging.FileHandler'
         level: DEBUG
         formatter: std_debug
         filename: '{{dir_run_debs}}/debs_{{ts}}_{{pid}}.log'
         mode: 'a'
         delay: true

     std_info_file:
         class: 'logging.FileHandler'
         level: INFO
         formatter: std_info
         filename: '{{dir_run_infs}}/infs_{{ts}}_{{pid}}.log'
         mode: 'a'
         delay: true

     std_warning_file:
         class: 'logging.FileHandler'
         level: WARNING
         formatter: std_warning
         filename: '{{dir_run_wrns}}/wrns_{{ts}}_{{pid}}.log'
         mode: 'a'
         delay: true

     std_error_file:
         class: 'logging.FileHandler'
         level: ERROR
         formatter: std_error
         filename: '{{dir_run_errs}}/errs_{{ts}}_{{pid}}.log'
         mode: 'a'
         delay: true
 
     std_critical_file:
         class: 'logging.FileHandler'
         level: CRITICAL
         formatter: std_critical
         filename: '{{dir_run_crts}}/crts_{{ts}}_{{pid}}.log'
         mode: 'a'
         delay: true

     std_critical_mail:
         class: 'logging.handlers.SMTPHandler'
         level: CRITICAL
         formatter: std_critical_mail
         mailhost : localhost
         fromaddr: 'monitoring@domain.com'
         toaddrs:
             - 'dev@domain.com'
             - 'qa@domain.com'
         subject: 'Critical error with application name'
 
 formatters:

     std_debug:
         format: '%(asctime)-15s %(levelname)s-%(name)s-%(process)d::%(module)s.%(funcName)s|%(lineno)s:: %(message)s'
         datefmt: '%Y-%m-%d %H:%M:%S'
     std_info:
         format: '%(asctime)-15s %(levelname)s-%(name)s-%(process)d::%(module)s.%(funcName)s|%(lineno)s:: %(message)s'
         datefmt: '%Y-%m-%d %H:%M:%S'
     std_warning:
         format: '%(asctime)-15s %(levelname)s-%(name)s-%(process)d::%(module)s.%(funcName)s|%(lineno)s:: %(message)s'
         datefmt: '%Y-%m-%d %H:%M:%S'
     std_error:
         format: '%(asctime)-15s %(levelname)s-%(name)s-%(process)d::%(module)s.%(funcName)s|%(lineno)s:: %(message)s'
         datefmt: '%Y-%m-%d %H:%M:%S'
     std_critical:
         format: '%(asctime)-15s %(levelname)s-%(name)s-%(process)d::%(module)s.%(funcName)s|%(lineno)s:: %(message)s'
         datefmt: '%Y-%m-%d %H:%M:%S'
     std_critical_mail:
         format: '%(asctime)-15s %(levelname)s-%(name)s-%(process)d::%(module)s.%(funcName)s|%(lineno)s:: %(message)s'
         datefmt: '%Y-%m-%d %H:%M:%S'

Jinja2-variables
^^^^^^^^^^^^^^^^

.. log.std.yml-Jinja2-variables-label:
.. table:: *log.std.yml Jinja2 variables*

   +------------+-----------------------------+-------------------------------------------+
   |Name        |Definition                   |Example                                    |
   +============+=============================+===========================================+
   |dir_run_debs|debug run directory          |/data/eviq/UMH/RUN/ui_eviq_srr/evupreg/debs|
   +------------+-----------------------------+-------------------------------------------+
   |dir_run_infs|info run directory           |/data/eviq/UMH/RUN/ui_eviq_srr/evupreg/logs|
   +------------+-----------------------------+                                           |
   |dir_run_wrns|warning run directory        |                                           |
   +------------+-----------------------------+                                           |
   |dir_run_errs|error run directory          |                                           |
   +------------+-----------------------------+                                           |
   |dir_run_crts|critical error run directory |                                           |
   +------------+-----------------------------+-------------------------------------------+
   |ts          |Timestamp since 1970 in [sec]|1749483509                                 |
   |            |if log_ts_type == 'ts'       |                                           |
   |            +-----------------------------+-------------------------------------------+
   |            |Datetime in timezone Europe/ |20250609 17:38:29 GMT+0200                 |
   |            |Berlin if log_ts_type == 'dt'|                                           |
   +------------+-----------------------------+-------------------------------------------+
   |pid         |Process ID                   |79133                                      |
   +------------+-----------------------------+-------------------------------------------+

***************
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 Modules
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        |                                           |
   +--------