# ka_uts_com

# Overview

Communication Utilities

# Installation

The package `ka_uts_com` can be installed from PyPI or Anaconda.

To install with `pip`:

    $ python -m pip install ka_uts_com

To install with `conda`:

    $ conda install -c conda-forge ka_uts_com

# Package logging

(c.f.: Appendix: Package Logging)

# Package files

## Classification

The Package `ka_uts_com` consist of the following file types (c.f.: Appendix):

1. Special files: (c.f.: Appendix: Special python package files)
2. Dunder modules: (c.f.: Appendix: Special python package modules)
3. Decorator modules
   1. dec.py
4. Modules
   1. Communication Modules
      1. com.py
      2. timer.py
   2. Base Modules
      1. app.py
      2. cfg.py
      3. exit.py

# Decorator Modules

## Overview

> Decorator Modules
> Name | Decription
> --- | ---
> dec.py | Decorators module

# Package Files

## Communication Modules

### Overview

> Communication Modules
> Name | Decription
> --- | ---
> com.py | Communication handling module
> timer.py | Timer management module

## Communication module com.py

The Communication Module `com.py` contains the single static class `Com`.

### com.py Class: Com

The static Class `Com` contains the subsequent variables and methods.

#### Com: Variables

> Com: Variables
> Name | Type | Default | Description
> --- | --- | --- | ---
> sw_init | TyBool | None | Initialisation switch
> d_com_pacmod | TyDic | {} | Communication package module dictionary
> d_app_pacmod | TyDic | {} | Application package module dictionary
> Timestamp fields
> ts | TnTimeStamp | None | Timestamp
> ts_start | TnDateTime | None | start timestamp in date time format
> ts_end | TnDateTime | None | end timestamp in date time format
> ts_etime | TnDateTime | None | elapse Time
> d_timer | TyDic | False | Timer dictionary
> Links to other Classes
> App | TyAny | False | Application class
> cfg | TyDic | None | Configuration dictionary
> Log | TyLogger | False | Log class
> Exit | TyAny | False | Exit class

#### Com: Methods

> Com Methods
> Name | Description
> --- | ---
> init | Initialise static variables if they are not initialized
> sh_kwargs | Show keyword arguments

#### Com Method: init

##### Parameter

> ..Com-Method-init-Parameter-label: .. table:: Com Method init: Parameter

> > Name | Type | Description
> > --- | --- | ---
> > cls | class | current class
> > **kwargs | TyAny | keyword arguments

#### Com Method: sh_kwargs

##### Parameter

> Com Method sh_kwargs: Parameter
> Name | Type | Description
> --- | --- | ---
> cls | class | current class
> root_cls | class | root lass
> d_parms | TyDic | parameter dictionary
> *args | list | arguments array

## Time management Module timer.py

### timer.py: Classes

The Module `timer.py` contains the following classes

> timer.py classes
> Name | Type | Description
> --- | --- | ---
> Timestamp | static | Timestamp class
> Timer | static | Timer class

### timer.py Class: Timer

#### Timer: Methods

> Timer Methods
> Name | Description
> --- | ---
> sh_task_id | Show task id
> start | Start Timer
> end | End Timer and Log Timer info message

#### Timer Method: sh_task_id

Show task id, which is created by the concatination of the following items if they are defined: #. package, #. module, #. class_name, #. parms The items package and module are get from the package-module directory; The item class_name is the class_id if its a string, otherwise the attribute __qualname__ is used.

##### Parameter

> Timer Method sh_task_id: Parameter
> Name | Type | Description
> --- | --- | ---
> d_pacmod | TyDic | pacmod dictionary
> class_id | TyAny | Class Id
> parms | TnAny | Parameters
> sep | TyStr | Separator

##### Return Value

> Timer Method sh_task_id: Return Value
> Name | Type | Description
> --- | --- | ---
> | TyStr | Task Id

#### Timer Method: start

##### Parameter

> Timer Method start: Parameter
> Name | Type | Description
> --- | --- | ---
> cls | class | current class
> class_id | TyAny | Class Id
> parms | TnAny | Parameter
> sep | TyStr | Separator

#### Timer Method: end

##### Parameter

> Timer Method end: Parameter
> Name | Type | Description
> --- | --- | ---
> cls | class | current class
> class_id | TyAny | Class Id
> parms | TnAny | Parameter
> sep | TyStr | Separator

# Base Modules

## Overview

> Base Modules
> Name | Decription
> --- | ---
> app_.py | Application setup module
> cfg_.py | Configuration setup module
> exit_.py | Exit Manafement setup module

## Base module: app_.py

The Module `app.py` contains a single static class `App_`.

### Class: App_

The static class `App_` contains the subsequent static variables and methods

#### App_: Static Variables

> Appl_ tatic Variables
> Name | Type | Default | Description
> --- | --- | --- | ---
> sw_init | TyBool | False | initialisation switch
> httpmod | TyDic | None | http modus
> sw_replace_keys | TnBool | False | replace keys switch
> keys | TnArr | None | Keys array
> reqs | TyDic | None | Requests dictionary
> app | TyDic | None | Appliction dictionary

#### App_: Methods

> App_ Methods
> Name | Type | Description
> --- | --- | ---
> init | class | initialise static variables of class if they are not allready initialized
> sh | class | show (return) class

#### App_ Method: init

##### Parameter

> App_ Method: init
> Name | Type | Description
> --- | --- | ---
> cls | class | Current class
> **kwargs | TyAny | Keyword arguments

#### App_ Method: sh

> App_ Method: sh
> Name | Type | Description
> --- | --- | ---
> cls | class | Current class
> **kwargs | TyAny | Keyword arguments

##### Return Value

> App_ Method sh: Return Value
> Name | Type | Description
> --- | --- | ---
> log | TyLogger | Logger

## Base module: cfg_.py

The Base module cfg_.py contains a single static class `Cfg_`.

### cfg_.py Class Cfg_

The static class `Cfg_` contains the subsequent static variables and methods

#### Cfg_Static Variables

> Cfg_ Static Variables
> Name | Type | Default | Description
> --- | --- | --- | ---
> cfg | TyDic | None | Configuration object

#### Cfg_ Methods

> Cfg_ Methods
> Name | Type | Description
> --- | --- | ---
> sh | class | read pacmod yaml file into class variable cls.dic and return cls.cfg

#### Cfg_ Method: sh

##### Parameter

> Cfg_ Method sh: Parameter
> Name | Type | Description
> --- | --- | ---
> cls | class | Current class
> log | TyLogger | Logger
> d_pacmod | TyDic | pacmod dictionary

##### Return Value

> Cfg_ Method sh: Return Value
> Name | Type | Description
> --- | --- | ---
> cls.cfg | TyDic |

## Base Modul: exit_.py

The Base module exit_.py contains a single static class `Ext_`.

### exit_.py class: Exit_

The static Class `Exit_` of Module exit_.py contains the subsequent static variables and methods.

#### Exit_: Variables

> Exit_ Variables
> Name | Type | Default | Description
> --- | --- | --- | ---
> sw_init | TyBool | False | initialisation switch
> sw_critical | TyBool | False | critical switch
> sw_stop | TyBool | False | stop switch
> sw_interactive | TyBool | False | interactive switch

#### Exit_: Methods

> Exit_ Methods
> Name | Method | Description
> --- | --- | ---
> init | class | initialise static variables of class if they are not allready initialized
> sh | class | show (return) class

#### Exit_: Method: init

##### Parameter

> Exit_ Method init: Parameter
> Name | Type | Description
> --- | --- | ---
> cls | class | Current class
> **kwargs | TyAny | Keyword arguments

#### Exit_: Method: sh

##### Parameter

> Exit_ Method sh: Parameter
> Name | Type | Description
> --- | --- | ---
> cls | class | Current class
> **kwargs | TyAny | Keyword arguments

##### Return Value

> Exit_ Method sh: Return Value
> Name | Type | Description
> --- | --- | ---
> cls | class | Current class

# Appendix

## Package Logging

### Description

The Standard or user specifig logging is carried out by the log.py module of the logging package ka_uts_log using the configuration files ka_std_log.yml or ka_usr_log.yml in the configuration directory cfg of the logging package ka_uts_log. The Logging configuration of the logging package could be overriden by yaml files with the same names in the configuration directory cfg of the application packages.

### Log message types

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

1. debug
2. info
3. warning
4. error
5. critical

#### Application parameter for logging

> Application parameter used in log naming
> Name | Decription | Values | Example
> --- | --- | --- | ---
> dir_dat | Application data directory |  | /otev/data
> tenant | Application tenant name |  | UMH
> package | Application package name |  | otev_xls_srr
> cmd | Application command |  | evupreg
> pid | Process ID |  | æevupreg
> log_ts_type | Timestamp type used in logging files|ts, dt | ts, dt | ts
> log_sw_single_dir | Enable single log directory or multiple log directories | True, False | True

#### Log type and Log directories

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

> 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

#### Log files naming

##### Naming Conventions

> Naming conventions for logging file paths
> Type | Directory | File
> --- | --- | ---
> debug | /<dir_dat>/<tenant>/RUN/<package>/<cmd>/<Log directory> | <Log type>_<ts>_<pid>.log
> info | /<dir_dat>/<tenant>/RUN/<package>/<cmd>/<Log directory> | <Log type>_<ts>_<pid>.log
> warning | /<dir_dat>/<tenant>/RUN/<package>/<cmd>/<Log directory> | <Log type>_<ts>_<pid>.log
> error | /<dir_dat>/<tenant>/RUN/<package>/<cmd>/<Log directory> | <Log type>_<ts>_<pid>.log
> critical | /<dir_dat>/<tenant>/RUN/<package>/<cmd>/<Log directory> | <Log type>_<ts>_<pid>.log

##### Naming Examples

> Naming examples for logging file paths
> Type | Directory | File
> --- | --- | ---
> debug | /data/otev/umh/RUN/otev_xls_srr/evupreg/logs | debs_1737118199_9470.log
> info | /data/otev/umh/RUN/otev_xls_srr/evupreg/logs | infs_1737118199_9470.log
> warning | /data/otev/umh/RUN/otev_xls_srr/evupreg/logs | wrns_1737118199_9470.log
> error | /data/otev/umh/RUN/otev_xls_srr/evupreg/logs | errs_1737118199_9470.log
> critical | /data/otev/umh/RUN/otev_xls_srr/evupreg/logs | crts_1737118199_9470.log

## Python Terminology

### Python packages

> Python packages
> Name | Definition
> --- | ---
> Python package | Python packages are directories that contains the special module `__init__.py` and other modules, packages files or directories.
> Python sub-package | Python sub-packages are python packages which are contained in another pyhon package.

#### Python package Sub-directories

> Python packages Sub-directories
> Name | Definition
> --- | ---
> Python package sub-directory | Sub-directories are directories contained in python packages.
> Special Python package sub-directory | Python package sub-directories with a special meaning.

##### Special python package Sub-directories

> Special python 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 package files

> Python package files
> Name | Definition
> --- | ---
> Python package files | Files within a python package.
> Special python package files | Package files which are not modules and used as python and used as python marker files like `__init__.py`.
> Python package module | Files with suffix `.py`; they could be empty or contain python code; other modules can be imported into a module.
> Special python package module | Modules like `__init__.py` or `main.py` with special names and functionality.

##### Special python package files

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

##### Special python package modules

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

### Python elements

> Python elements
> Name | Description
> --- | ---
> Python method | Python functions defined in python modules.
> Special python method | Python functions with special names and functionalities.
> Python class | Classes defined in python modules.
> Python class method | Python methods defined in python classes

#### Special python methods

> Special python methods
> Name | Type | Description
> --- | --- | ---
> __init__ | class object constructor method | The special method `__init__` is called when an instance (object) of a class is created; instance attributes can be defined and initalized in the method.

## Table of Contents

Table of Content

- Overview
- Installation
- Package logging
- Package files
  - Classification
- Decorator Modules
  - Overview
- Package Files
  - Communication Modules
    - Overview
  - Communication module com.py
    - com.py Class: Com
      - Com: Variables
      - Com: Methods
      - Com Method: init
        - Parameter
      - Com Method: sh_kwargs
        - Parameter
  - Time management Module timer.py
    - timer.py: Classes
    - timer.py Class: Timer
      - Timer: Methods
      - Timer Method: sh_task_id
        - Parameter
        - Return Value
      - Timer Method: start
        - Parameter
      - Timer Method: end
        - Parameter
- Base Modules
  - Overview
  - Base module: app_.py
    - Class: App_
      - App_: Static Variables
      - App_: Methods
      - App_ Method: init
        - Parameter
      - App_ Method: sh
        - Return Value
  - Base module: cfg_.py
    - cfg_.py Class Cfg_
      - Cfg_Static Variables
      - Cfg_ Methods
      - Cfg_ Method: sh
        - Parameter
        - Return Value
  - Base Modul: exit_.py
    - exit_.py class: Exit_
      - Exit_: Variables
      - Exit_: Methods
      - Exit_: Method: init
        - Parameter
      - Exit_: Method: sh
        - Parameter
        - Return Value
- Appendix
  - Package Logging
    - Description
    - Log message types
      - Application parameter for logging
      - Log type and Log directories
      - Log files naming
        - Naming Conventions
        - Naming Examples
  - Python Terminology
    - Python packages
      - Python package Sub-directories
        - Special python package Sub-directories
      - Python package files
        - Special python package files
        - Special python package modules
    - Python elements
      - Special python methods
  - Table of Contents