# ka_uts_log

# Overview

Log Management

# Installation

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

To install with `pip`:

    $ python -m pip install ka_uts_log

To install with `conda`:

    $ conda install -c conda-forge ka_uts_log

# Package logging

c.f.: Appendix: Package Logging

# Package files

## Classification

The Package `ka_uts_log` 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. Modules
   1. log.py
4. Special Sub-directories: (c.f.: Appendix: Special python package Sub-directories)
   1. cfg
      1. __init__.py
      2. log.std.yml
      3. log.usr.yml

## Special Sub-directory: cfg

### Overview

> Special Sub directory cfg: Files
> Name | Description
> --- | ---
> log.std.yml | Yaml definition file for standard logging
> log.usr.yml | Yaml definition file for user logging

## Modules

The Package `ka_uts_log` contains the following modules.

> ka_uts_log Modules
> Name | Decription
> --- | ---
> log.py | Logging management module

## Module: log.py of Package: ka_uts_log

The Module `log.py` contains the following static classes.

### Classes of Module: log.py

> log.py classes
> Name | Description
> --- | ---
> LogEq | Management of Log Equate message, generated from a key-, value-pair.
> LogDic | Management of Log Equate messages, generated from the key-, value-pairs of a dictionary.
> Log | Management of Log messages

### Class: Log of Modul: log.py

The static Class `Log` contains the subsequent display- and management-methods.

#### Display Methods of Class: Log

> Log Display Methods
> Name | Description
> --- | ---
> debug | Log debug message to debug destination.
> info | Log info message to info destination.
> warning | Log warnning message to warning destination.
> error | Log error message to error destination.
> critcial | Log critical message to critical destination.

#### Management Methods of Class: Log

> Log Management Methods
> Name | Description
> --- | ---
> init | initialise current class.
> sh_calendar_ts | Show timestamp or datetime.
> sh_dir_run | Show run directory.
> sh_d_dir_run | Show dictionary of run directories.
> sh_d_log_cfg | Show log configuration directory.
> sh_path_log_cfg | Show path of log configuration file.
> sh | initialise and show current class.

#### Management Method: init of Class: Log

##### Parameter

> Log method init: Parameter
> Name | Type | Description
> --- | --- | ---
> cls | class | current class
> **kwargs | TyAny | keyword arguments

### Class: LogEq of Modul: Log

The static Class `LogEq` of Module log.py contains the subsequent methods

#### Methods of Class LogEq

> LogEq Methods
> Name | Description
> --- | ---
> debug | Log generated equate message "<key> = <value>" to the debug destination.
> info | Log generated equate message "<key> = <value>" to the info destination.
> warning | Log generated equate message "<key> = <value>" to the warning destination.
> error | Log generated equate message "<key> = <value>" to the error destination.
> critcial | Log generated equate message "<key> = <value>" to the critical destination.

All Methods of Class: LogEq use the following Parameters:

##### Methods Parameter of Class: LogEq

> LogEq Methods parameter
> Name | Type | Description
> --- | --- | ---
> cls | class | current class
> key | TyAny | Key
> value | TyAny | Value

### Class: LogDic of Modul: log.py

The static Class `LogDic` of Module log.py contains the subsequent methods

#### Methods of Class: LogDic

> LogDic Methods
> Name | Description
> --- | ---
> debug | Log generated equate messages for all dictionary entries to the debug destination.
> info | Log generated equate messages for all dictionary entries to the info destination.
> warning | Log generated equate messages for all dictionary entries to the warning destination.
> error | Log generated equate messages for all dictionary entries to the error destination.
> critical | Log generated equate messages for all dictionary entries to the critical destination.

All Methods of Class LogDic use the following Parameters:

##### Method Parameters of Class: LogDic

> LogDic Methods Parameter
> Name | Type | Description
> --- | --- | ---
> cls | class | current class
> dic | TyDic | Dictionary

# 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
> --- | --- | --- | ---
> Value|Type
> dir_dat | Application data directory |  | Path | /otev/data
> tenant | Application tenant name |  | str | UMH
> package | Application package name |  | str | otev_xls_srr
> cmd | Application command |  | str | evupreg
> pid | Process ID |  | str | evupreg
> log_ts_type | Timestamp type used in loggin files | ts | Timestamp | ts
> dt | Datetime |
> log_sw_single_dir | Enable single log directory or multiple log directories | True | Bool | True
> False | Bool
> log_sw_pid | Enable display of pid in log file name | True | Bool | True
> False | Bool

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

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

### Examples (with log_ts_type = 'ts')

The examples use the following parameter values.

1. dir_dat = '/data/otev'
2. tenant = 'UMH'
3. package = 'otev_srr'
4. cmd = 'evupreg'
5. log_sw_single_dir = True
6. log_sw_pid = True
7. log_ts_type = 'ts'

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

## Python Terminology

### Packages

#### Overview

> 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-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 Packages Examples
> Name | Description
> --- | ---
> data | Directory for package data files.
> cfg | Directory for package configuration files.

### Files

#### Overview

> Python Filese
> Name | Definition
> --- | ---
> Python package file | File within a python package.
> Python package special file | Python package file which are not modules and used as python marker files like `__init__.py`.
> Python package module | File with suffix `.py` which could be empty or contain python-code. Other modules can be imported into a module.
> Python package special module | Python package module with special name and functionality like `main.py` or `__init__.py`.

#### Examples

> Python Files Examples
> 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
> Name | Definition
> --- | ---
> Python method | Function defined in a python module.
> Special python method | Python method with special name and functionality like `init`.
> Python class | Python classes are defined in python modules.
> Python class method | Python method defined in a python class.
> Special Python class method | Python class method with special name and functionality like `init`.

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

- Overview
- Installation
- Package logging
- Package files
  - Classification
  - Special Sub-directory: cfg
    - Overview
  - Modules
  - Module: log.py of Package: ka_uts_log
    - Classes of Module: log.py
    - Class: Log of Modul: log.py
      - Display Methods of Class: Log
      - Management Methods of Class: Log
      - Management Method: init of Class: Log
        - Parameter
    - Class: LogEq of Modul: Log
      - Methods of Class LogEq
        - Methods Parameter of Class: LogEq
    - Class: LogDic of Modul: log.py
      - Methods of Class: LogDic
        - Method Parameters of Class: LogDic
- Appendix
  - Package Logging
    - Description
  - Log message types
  - Application parameter for logging
  - Log message type and Log directories
  - Log files naming
    - Conventions
    - Examples (with log_ts_type = 'ts')
  - Python Terminology
    - Packages
      - Overview
      - Examples
    - Files
      - Overview
      - Examples
    - Python Methods
      - Overview
      - Examples
- Table of Contents