README.rst

# ka_uts_uts

## Overview

IO Control and Package Management Utilities

## Installation

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

To install with `pip`:

    $ python -m pip install ka_uts_uts

To install with `conda`:

    $ conda install -c conda-forge ka_uts_uts

## Package logging

(c.f.: Appendix: Package Logging)

## Package files

### Classification

The Package `ka_uts_uts` 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. Sub-packages

   1. ioc: (I/O Control)

      1. Special files: (c.f.: Appendix: Special python package files)

      2. Dunder modules: (c.f.: Appendix: Special python package modules)

      3. Modules

         > 1. jinja2_.py
         > 2. yaml_.py

   2. utils: (Utilities)

      1. Special files: (c.f.: Appendix: Special python package files)
      2. Dunder modules: (c.f.: Appendix: Special python package modules)
      3. Modules
         1. fnc.py
         2. pacmod.py
         3. pac.py
         4. srv.py

## Sub-package: ioc (I/O Control)

### Modules

The Sub-package `ioc` contains the following modules.

> Modules of Sub-package ioc
> Name | Decription
> --- | ---
> jinja_.py | I/O Control methods for jinja2 files.
> yaml_.py | I/O Control methods for yaml files.

#### Module: jinja2_.py

The Module `jinja2_.py` contains the static class `Jinja2`

##### jinja2_.py Class: Jinja2

The static Class `Jinja2` provides I/O Control methods for Jinja2 files; it contains the subsequent methods.

###### Jinja2 Methods

> Jinja2 Methods
> Name | Description
> --- | ---
> read | Read log file path with jinja
> read_template | Read log file path with jinja2

###### Jinja2 Method: read

###### Parameter

> Jinja2 Method read: Parameter
> Name | Type | Description
> --- | --- | ---
> pacmod | TnDic |
> filename | str |

###### Jinja2 Method: read_template

###### Parameter

> Jinja2 Method read_template: Parameter
> Name | Type | Description
> --- | --- | ---
> path | TyPath | Path string

###### Return Value

> Jinja2 Method read_template: Return Value
> Name | Type | Description
> --- | --- | ---
> | TyJinja2Template | Jinja2 Template

#### Module: yaml_.py

The Module `yaml_.py` contains the static class `Yaml`.

##### yamml_.py Class: Yaml

The static Class `Yaml` provides I/O Control functions for Yaml files; it contains the subsequent methods

###### Yaml Methods

> Yaml Methods
> Name | Description
> --- | ---
> load | Load yaml string into any object using yaml loader; default loader is yaml.safeloader
> read | Read yaml file path into any object using yaml loder; default loader is yaml.safeloader

###### Yaml Method: read_with_safeloader

###### Parameter

> Yaml Method read_with_safeloader: Parameter
> Name | Type | Description
> --- | --- | ---
> path | TyPath | Path string

###### Yaml Method: write

###### Parameter

> Yaml Method write: Parameter
> Name | Type | Description
> --- | --- | ---
> path | TyPath | Path string
> obj | TyAny | Object

## Sub package: utils

### utils Modules

The Sub-package `utils` contains the following modules.

> utils Modules
> Name | Functionality
> --- | ---
> pacmod.py | Manage Packages and Modules
> pac.py | Manage Packages

#### utils Module: pacmod.py

The Module `pacmod.py` contains the static class `PacMod`.

##### pacmod.py Class: PacMod

The static Class `PacMod` is used to get the Package- and Module-name. it contains the subsequent methods

###### PacMod Methods

> PacMod Methods
> Name | Description
> --- | ---
> sh_d_pacmod | Show (Get) package module dictionary for class.
> sh_path_module_yaml | show package module yaml file path.
> sh_path_keys_yml | show keys.yaml file path.
> sh_path_cfg_yml | show cfg.yaml file path.
> sh_dir_type | show type specific file directory.
> sh_path_pattern | show pattern file path.

###### PacMod Method: sh_d_pacmod

###### Parameter

> PacMode Method sh_d_pacmod: Parameter
> Name | Type | Description
> --- | --- | ---
> path | TyPath | Path string

# 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 standard- or user-configuration files in the logging package configuration directory:

- <logging package directory>/cfg/ka_std_log.yml,
- <logging package directory>/cfg/ka_usr_log.yml.

The Logging configuration of the logging package could be overriden by yaml files with the same names in the application package- or application data-configuration directories:

- <application package directory>/cfg
- <application data directory>/cfg.

### 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

#### Log types 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

#### 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 |  | 681025
> 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 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

#### Overview

> Python Packages Overview
> 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-directory | directory contained in a python package.
> Python package special sub-directory | Python package sub-directories with a special meaning like data or cfg

#### Examples

> Python Package sub-directory-Examples
> 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

#### Overview

> Python package overview 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.

#### Examples

> Python package examples 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.
> __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 methods

#### Overview

> Python methods overview
> 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

#### Examples

> Python methods examples
> 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

- ka_uts_uts
  - Overview
  - Installation
  - Package logging
  - Package files
    - Classification
  - Sub-package: ioc (I/O Control)
    - Modules
      - Module: jinja2_.py
        - jinja2_.py Class: Jinja2
          - Jinja2 Methods
          - Jinja2 Method: read
            - Parameter
          - Jinja2 Method: read_template
            - Parameter
            - Return Value
      - Module: yaml_.py
        - yamml_.py Class: Yaml
          - Yaml Methods
          - Yaml Method: read_with_safeloader
            - Parameter
          - Yaml Method: write
            - Parameter
  - Sub package: utils
    - utils Modules
      - utils Module: pacmod.py
        - pacmod.py Class: PacMod
          - PacMod Methods
          - PacMod Method: sh_d_pacmod
            - Parameter
- Appendix
  - Package Logging
    - Description
    - Log message types
      - Log types and Log directories
      - Application parameter for logging
      - Log files naming
        - Naming Conventions
        - Naming Examples
  - Python Terminology
    - Python Packages
      - Overview
      - Examples
    - Python package files
      - Overview
      - Examples
    - Python methods
      - Overview
      - Examples
- Table of Contents