README.rst

# ka_uts_obj

## Overview

Object 'Utilities'

## Installation

Package `ka_uts_obj` can be installed from PyPI or Anaconda.

To install with `pip`:

    $ python -m pip install ka_uts_obj

To install with `conda`:

    $ conda install -c conda-forge ka_uts_obj

This requires that the `readme` extra is installed:

    $ python -m pip install ka_uts_obj[readme]

## Package files

### Classification

The Files of Package `ka_uts_obj` could be classified into the follwing file types:

1. Special files
2. Dunder modules
3. Package modules

### Package Modules

The Modules of Package `ka_uts_obj` could be classified in the following module types:

1. Base objects Modules
2. Complex objects Modules
3. File Modules
4. Path Modules

## Base objects Modules

The Base objects Modules of Package `ka_uts_obj` are used for the management of base objects like byte-objects, , num-obj́ects or objects. The Base objects modules type contains the following modules.

> Base objects Modules
> Name | Type | Description
> --- | --- | ---
> byte.py | TyByte | Byte Manipulation
> num.py | TyNum | Number Management
> obj.py | TyObj | Object Management

### byte.py (Base objects Module)

#### Classes

The Base object Module `byte.py` contains the single static class `Byte`;

#### byte.py Class: Byte

The static Class `Byte` contains the subsequent methods

##### Methods

> Methods of static class Byte
> Name | Description
> --- | ---
> replace_by_dic | replace dictionary-keys found in byte string with corresponding values

###### Byte Method: replace_by_dic

> Parameter of Byte method replace_by_dic
> Name | Type | Description
> --- | --- | ---
> byte_string | TyBytes | Byte string
> dic_replace | TyDic | Dictionary with replacement keys and values

## Complex objects modules

The Complex objects module type of Package `ka_uts_obj` consist of the single module `poa.py`.

### poa.py

The Module `poa.py` is used to manage Pairs of arrays;

#### Classes

The Module `oia.py` contains contains the single static class `PoA`.

#### poa.py Class: PoA

The static Class `PoA` contains the subsequent methods

##### PoA Methods

###### Overview

> Methods of static class PoA
> Name | Description
> --- | ---
> yield_items | yield items for the given pair of objects and the object. Every item consist of the following elements:
> element of the first given array element of the second given array the given object

###### PoA Method: yield_items

> Parameter of PoA method yield_items
> Name|Type | Description
> --- | ---
> poa | TyPoA | Pair of Arrays
> obj | TyAny | Object

## File modules

The `File modules` type of Package `ka_uts_obj` consist of the single module `file.py`.

### file.py

The File module `file.py` is used for the management of file objects; it contains the single class `File`.

#### file.py Class: File

The static Class `File` contains the subsequent methods

##### File Methods

###### Overview

> Methods of static class File
> Name | Description
> --- | ---
> count | count number of paths that match path_pattern.
> ex_get_aod_using_fnc | execute get array of dictionaries using the function.
> ex_get_aod | execute get array of dictionaries.
> ex_get_dod_using_fnc | execute get dictionary of dictionaries using the function.
> ex_get_dod | execute get dictionary of dictionaries.
> get_aod | get array of dictionaries.
> get_dic | get array of dictionaries and return the first element.
> get_dod | get dictionary of dictionaries.
> get_paths | yield paths which match given path pattern.
> get_latest | get latest file path that match given path pattern.
> io | apply io function to given path and object.

###### File Method: count

###### Parameter

> Parameter of File method put_aod
> Name | Type | Description
> --- | --- | ---
> path_pattern | TyPath | path_pattern

###### Return Value

> Return value of File method count
> Name | Type | Description
> --- | --- | ---
> | TyInt | Number pf paths

###### File Method: ex_get_aod_using_fnc

###### Parameter

> Parameter of File method ex_get_aod_using_fnc
> Name | Type | Description
> --- | --- | ---
> path | TyPath | Path
> fnc | TyCallable | Object function
> kwargs | TyDic | keyword arguments

###### Return Value

> Return value of File method ex_get_aod_using_fnc
> Name | Type | Description
> --- | --- | ---
> | TyAoD | Array of Dictionariesy

###### File Method: ex_get_aod

###### Parameter

> Parameter of File method ex_get_aod
> Name | Type | Description
> --- | --- | ---
> path | TyPath | Path
> kwargs | TyDic | keyword arguments

###### Return Value

> Return value of IocWbPe method get
> Name | Type | Description
> --- | --- | ---
> | TyAoD | Array of Dictionaries

###### File Method: ex_get_dod_using_fnc

###### Parameter

> Parameter of File method ex_get_dod_using_fnc
> Name | Type | Description
> --- | --- | ---
> path | TyPath | Path
> fnc | TyCallable | Object function
> key | TyAny | Keyword
> kwargs | TyDic | Keyword arguments

###### Return Value

> Return value of File method ex_get_dod_using_fnc
> Name | Type | Description
> --- | --- | ---
> | TyDoD | Dictionary of dictionaries

###### File Method: ex_get_dod

###### Parameter

> Parameter of File method ex_get_dod
> Name | Type | Description
> --- | --- | ---
> path | TyPath | Path
> key | TyAny | Keyword
> kwargs | TyDic | Keyword arguments

###### Return Values

> Return value of File method ex_get_dod
> Name | Type | Description
> --- | --- | ---
> | TyDoD | Dictionary of dictionaries

###### File Method: get_aod

###### Parameter

> Parameter of File method get_aod
> Name | Type | Description
> --- | --- | ---
> cls | class | current class
> path | TyPath | Path
> fnc | TyCallable | Object function
> kwargs | TyDic | keyword arguments

###### Return Value

> Return value of File method get_aod
> Name | Type | Description
> --- | --- | ---
> | TyDic | Array of Dictionaries

###### File Method: get_dic

###### Parameter

> Parameter of File method get_dic
> Name | Type | Description
> --- | --- | ---
> cls | class | current class
> path | TyPath | Path
> fnc | TnCallable | Object function
> key | TyStr | Keyword
> kwargs | TyDic | keyword arguments

###### Return Value

> Return value of File method get_dic
> Name | Type | Description
> --- | --- | ---
> | TyDoD | Dictionary of Dictionaries

###### File Method: get_dod

###### Parameter

> Parameter of Byte method get_dod
> Name | Type | Description
> --- | --- | ---
> obj | TyAny | Object
> path | TyPath | Path
> fnc | TnCallable | Object function
> key | TyStr | IO function
> kwargs | TyDic | keyword arguments

###### Return Value

> Return value of File method get_dod
> Name | Type | Description
> --- | --- | ---
> | TyDoD | Dictionary of Dictionaries

###### File Method: get_latest

###### Parameter

> Parameter of File method get_latest
> Name | Type | Description
> --- | --- | ---
> path_pattern | TyStr | Path pattern

###### Return Value

> Return value of File method get_latest
> Name | Type | Description
> --- | --- | ---
> | TyPath | Path

###### File Method: get_paths

###### Parameter

> Parameter of File method get_paths
> Name | Type | Default | Description
> --- | --- | --- | ---
> path_pattern | TyPath |  | Path pattern
> sw_recursive | TyBool | None | Recursive switch

###### Return Value

> Parameter of File method get_paths
> Name | Type | Description
> --- | --- | ---
> | TyIoS | yield path

###### File Method: io

###### Parameter

> Parameter of File method io
> Name | Type | Description
> --- | --- | ---
> obj | TyObj | Object
> path | TnPath | Path
> fnc | TnCallable | Object function

## Path modules

The `Path modules` type of Package `ka_uts_obj` consist of the following modules.

> Path Modules
> Name | Type | Description
> --- | --- | ---
> path.py | TyPath | Path management

### path.py

The module `path.py` is used for the management of path objects.

#### path.py Classes

The module `path.py` contains the single class `Path`.

#### path.py Class: Path

The static Class `Path` contains the subsequent methods

##### Path Methods

###### Overview

> Methods of static class Path
> Name | Description
> --- | ---
> verify | Verify path
> edit_path | put array of _keys found in
> mkdir | make directory of directory path
> mkdir_from_path | make directory of the path, if it's a directory
> sh_basename | show basename of the path
> sh_components | split the path into components and show the joined components between start- and end-index
> sh_component_using_field_name | split the given path into components and show the component identified by an index; the index is get from the given dictionary with the given field name
> sh_fnc_name_using_pathlib | extract function name from path with pathlib
> sh_fnc_name_using_os_path | extract function name from path with os.path
> sh_last_component | show last component of path
> sh_path_using_pathnm | show basename of the path
> sh_path_using_d_path | replace keys in path by dictionary values
> sh_path_using_d_datetype | show path using path function selected by the given date type dictionary
> sh_path | show path
> sh_path_first | show first component of the given path
> sh_path_last | show last component of the given path
> sh_path_now | replace now variable in the path by the now date
> split_to_array | split normalized path to array

# 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_obj
  - Overview
  - Installation
  - Package files
    - Classification
    - Package Modules
  - Base objects Modules
    - byte.py (Base objects Module)
      - Classes
      - byte.py Class: Byte
        - Methods
          - Byte Method: replace_by_dic
  - Complex objects modules
    - poa.py
      - Classes
      - poa.py Class: PoA
        - PoA Methods
          - Overview
          - PoA Method: yield_items
  - File modules
    - file.py
      - file.py Class: File
        - File Methods
          - Overview
          - File Method: count
            - Parameter
            - Return Value
          - File Method: ex_get_aod_using_fnc
            - Parameter
            - Return Value
          - File Method: ex_get_aod
            - Parameter
            - Return Value
          - File Method: ex_get_dod_using_fnc
            - Parameter
            - Return Value
          - File Method: ex_get_dod
            - Parameter
            - Return Values
          - File Method: get_aod
            - Parameter
            - Return Value
          - File Method: get_dic
            - Parameter
            - Return Value
          - File Method: get_dod
            - Parameter
            - Return Value
          - File Method: get_latest
            - Parameter
            - Return Value
          - File Method: get_paths
            - Parameter
            - Return Value
          - File Method: io
            - Parameter
  - Path modules
    - path.py
      - path.py Classes
      - path.py Class: Path
        - Path Methods
          - Overview
- 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