# ka_uts_path

# Overview

Path Utilities

# Installation

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

To install with `pip`:

    $ python -m pip install ka_uts_path

To install with `conda`:

    $ conda install -c conda-forge ka_uts_path

# Package logging

(c.f.: Appendix: Package Logging)

# Package files

## Classification

The Package `ka_uts_path` 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. Modules for Management of Array of Paths
      1. aododopath.py
      2. aopath.py
   2. Modules for Management of Dictionary of Paths
      1. dodopath.py
      2. dopath.py
   3. Modules for Management of Paths
      1. file.py
      2. path.py
   4. Modules for Management of Path names
      1. pathnm.py

# Modules for Management of Array of Paths**

The Module Type `Modules for Management of Array of Paths` contains the following Modules:

> Array of Paths Management Rodules
> Name | Description
> --- | ---
> aododopath.py | Management of Array of Dictionaries of Dictionaries of Paths.
> aopath.py | Management of Array of Paths.

## Module: aopath.py

The Module `aopath.py` contains the static Classes `AoPath`.

### Class: AoPath

The static Class `AoPath` is used to manage `Array of Paths`; it contains the subsequent methods.

#### Methods

> AoPath Methods
> Name | Description
> --- | ---
> join | Join array of paths using the os separator
> mkdirs | Make directories
> show functions
> sh_a_path | Show array of paths for path template.
> sh_a_path_by_tpl | Convert array of path template keys and kwargs Rto array of paths.
> sh_aopath_by_gl-ob |
> sh_aopath_by_pac |
> sh_aopath_mtime_gt |
> sh_path_by_tpl_first_exist |
> yield functions
> yield_path_kwargs_over_path |
> yield_path_kwargs_over_dir_path |
> yield_path_item_kwargs_over_path_arr |

#### AoPath Method: join

1. Convert array of paths (1.argument) by striping the leading or trailing os separator.
2. join the converted array of paths.

##### Parameter

> Parameter of: AoPath Method: join
> Name | Type | Default | Description
> --- | --- | --- | ---
> aopath | TyAoPath |  | array of paths

##### Return Value

> Return Value of: AoPath Method: join
> Name | Type | Description
> --- | --- | ---
> path | TyPath | Path

#### AoPath Method: sh_a_path

Convert path template to array of paths using glob function of module glob.py.

##### Parameter

> Parameter of: AoPath Method: sh_a_path
> Name | Type | Default | Description
> --- | --- | --- | ---
> path | TyPath |  | Path

##### Return Value

> Return Value of: AoPath Method: sh_a_path
> Name | Type | Description
> --- | --- | ---
> a_path | TyAoPath | Array of paths

#### AoPath Method: sh_a_path_by_tmpl

1. Select array of path templates from keyword arguments (1.arguments) using the parameter
   - array of path template keys (1.argument);
2. join the array of path templates with the os separator
3. convert the created final path template to an array of paths.

##### Parameter

> Parameter of: AoPath Method: sh_a_path_by_tmpl
> Name | Type | Default | Description
> --- | --- | --- | ---
> a_path_tmpl_key | TyAoPath |  | array of path template keys
> kwargs | TyDic |  | keyword arguments

##### Return Value

> Return Value of: AoPath Method: sh_a_path_by_tmpl
> Name | Type | Default | Description
> --- | --- | --- | ---
> a_path | TyAoPath |  | Path

#### AoPath Method: yield_path_kwargs

1. Create array of paths by executing the function sh_a_path_by_tmpl with the parameter:
   - array of path template keys (2.argument).
2. Loop over array of paths to yield:
   1. yield path, kwargs (3. argument)

##### Parameter

> Parameter of: AoPath Method: yield_path_kwargs
> Name | Type | Default | Description
> --- | --- | --- | ---
> cls | Tyclass |  | current class
> a_path_tmpl_key | TyAoPath |  | array of path template keys
> kwargs | TyDic |  | keyword arguments

##### Return Value

> Return Value of: AoPath Method: yield_path_kwargs
> Name | Type | Description
> --- | --- | ---
> (path, kwargs) | TyAoPath | Path

#### AoPath Method: yield_path_kwargs_new

##### Synopsis

sh_a_path_by_tmpl(a_path_tmpl_key, kwargs)

##### Description

1. Create array of directories by executing the function sh_a_path_by_tmpl with the arguments:
   - array of directory template keys (2.argument).
2. Loop over array of directories to:
   1. create kwargs_new by executing ths given function sh_kwargs_new (4. argument) with the arguments:
      - directory, given kwargs (5. argument)
   2. create array of paths by executing the function sh_a_oath_by_tmpl with the arguments:
      - given array of path template keys (3. argument), kwargs_new
3. Loop over array of paths within the outer loop to:
   1. yield path, kwargs_new

##### Parameter

> Parameter of: AoPath Method: yield_path_kwargs_new
> Name | Type | Default | Description
> --- | --- | --- | ---
> cls | Tyclass |  | Current class
> a_dir_tmpl_key | TyAoPath |  | Array of path template keys
> a_path_tmpl_key | TyAoPath |  | Array of path template keys
> sh_kwargs_new | TyAoPath |  | Show new keyword arguments function
> kwargs | TyDic |  | Keyword arguments

##### Return Value

> Return Value of: AoPath Method: yield_path_kwargs_new
> Name | Type | Description
> --- | --- | ---
> (path, kwargs_new) | TyAoPath | Path, new keyword arguments

#### AoPath Method: yield_path_item_kwargs

1. Create array of paths by executing the function sh_a_path_by_tmpl with the arguments:
   - array of path template keys (2.argument).
2. Create array of items by selecting the value in the directory kwargs (4. argument) for the kwargs key (3. argument)
3. Loop over array of path and array of items to:
   1. yield path, item, kwargs (4. argument)

##### Parameter

> Parameter of: AoPath Method: yield_path_item_kwargs
> Name | Type | Default | Description
> --- | --- | --- | ---
> cls | Tyclass |  | current class
> a_path_tmpl_key | TyAoPath |  | array of path template keys
> a_arr_key | TyAoPath |  | array of path template keys
> kwargs | TyDic |  | keyword arguments

##### Return Value

> Return Value of: AoPath Method: yield_path_item_kwargs
> Name | Type | Description
> --- | --- | ---
> (path, item, kwargs) | TyAoPath | Path, Item, keyword arguments

#### Method: AoPath.yield_path_item_kwargs_new

1. Create array of directories by executing the function sh_a_path_by_tmpl with the parameter:
   - a_dir_tmpl_key (2.argument).
2. Create array of items by selecting the value in the directory kwargs (4. argument) for the key arr_key (3. argument)
3. Loop over the array of directories to:
   1. create kwargs_new by executing ths function sh_kwargs_new (4. argument) with the arguments:
      - directory, given kwargs (5. argument)
   2. create array of paths by executing the function sh_a_oath_by_tmpl with the arguments:
      - given array of path template keys (3. argument), kwargs_new
   3. Loop over array of path and array of items within the outer loop to:
      1. yield path, item, kwargs_new

##### Parameter

> Parameter of: AoPath Method: yield_path_item_kwargs_new
> Name | Type | Default | Description
> --- | --- | --- | ---
> cls | Tyclass |  | current class
> a_dir_tmpl_key | TyAoPath |  | array of path template keys
> a_path_tmpl_key | TyAoPath |  | array of path template keys
> sh_kwargs_new | TyAoPath |  | show new keyword arguments function
> kwargs | TyDic |  | keyword arguments

##### Return Value

> Return Value of: AoPath Method: yield_path_item_kwargs_new
> Name | Type | Description
> --- | --- | ---
> (path, item, kwargs_new) | TyAoPath | Path, Item, new keyword arguments

# Modules for Management of Dictionary of Paths

The Module Type `Modules for Management of Dictionary of Paths` contains the following Modules:

> Dictionaries of Paths Management Modules
> Name | Description
> --- | ---
> dodopath.py | Management of Dictionary of Dictionaries of Paths.
> dopath.py | Management of Dictionary of Paths.

## Module: dodopath.py

The Module `dodoath.py` contains the static Classes `DoDoPath`.

### Class: DoDoPath

The static Class `DoDoPath` is used to manage `Dictionary of Dictionaries of Paths`; it contains the subsequent methods.

#### Methods

> DoDoPath Methods
> Name | Description
> --- | ---
> sh_path | Show Path.

Module: dopath.py ==========-======

The Module `doath.py` contains the static Classes `DoPath`.

### Class: DoDoPath

The static Class `DoPath` is used to manage `Dictionary of Paths`; it contains the subsequent methods.

#### Methods

> DoDoPath Methods
> Name | Description
> --- | ---
> sh_path | Show Path.

# 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
- Modules for Management of Array of Paths**
  - Module: aopath.py
    - Class: AoPath
      - Methods
      - AoPath Method: join
        - Parameter
        - Return Value
      - AoPath Method: sh_a_path
        - Parameter
        - Return Value
      - AoPath Method: sh_a_path_by_tmpl
        - Parameter
        - Return Value
      - AoPath Method: yield_path_kwargs
        - Parameter
        - Return Value
      - AoPath Method: yield_path_kwargs_new
        - Synopsis
        - Description
        - Parameter
        - Return Value
      - AoPath Method: yield_path_item_kwargs
        - Parameter
        - Return Value
      - Method: AoPath.yield_path_item_kwargs_new
        - Parameter
        - Return Value
- Modules for Management of Dictionary of Paths
  - Module: dodopath.py
    - Class: DoDoPath
      - Methods
    - Class: DoDoPath
      - Methods
- 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