Metadata-Version: 2.4
Name: ut-arr
Version: 2.0.0.20260306
Summary: Utilities for Arrays
Author-email: Bernd Stroehle <bernd.stroehle@gmail.com>
Maintainer-email: Bernd Stroehle <bernd.stroehle@gmail.com>
License-Expression: GPL-3.0-only WITH Classpath-exception-2.0 OR BSD-3-Clause
Project-URL: Source Code, https://github.com/bs29/ut-arr/tree/master
Project-URL: Homepage, https://kosakya.de/
Project-URL: Documentation, https://ut-arr.readthedocs.io/en/latest
Project-URL: GPLv3 License, https://www.gnu.org/licenses/gpl-3.0.en.html
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Natural Language :: English
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: pytest-asyncio; extra == "tests"
Requires-Dist: parameterized; extra == "tests"
Dynamic: license-file

######
ut-arr
######

.. start short_desc

**Utilities for Array Management**

.. end short_desc

********
Overview
********

``ut-arr`` is a lightweight Python library that provides static utility
classes for managing generic arrays (lists), arrays of arrays, arrays of
dictionaries, arrays of objects, and arrays of strings.

All classes are purely static or class-method based and require no
instantiation.

For the full API reference see the Module Reference.

************
Installation
************

.. start installation

The package ``ut-arr`` can be installed from PyPI or Anaconda.

To install with ``pip``::

   python -m pip install ut-arr

To install with ``conda``::

   conda install -c conda-forge ut-arr

.. end installation

*******
Logging
*******

Logging is provided by the classes ``ut_log.log.Log`` or ``ut_log.log.LogEq``.
See `ut_log on PyPI <https://pypi.org/project/ut_log/>`_ for configuration
keys, log levels and examples.

*************
Package files
*************

Classification
==============

The files of package ``ut-arr`` can be classified into the following types
(c.f. the Python glossary):

#. **Special files** — ``py.typed``

#. **Special modules** — ``__init__.py``, ``__version__.py``

#. **Modules** — ``arr.py``, ``ao2a.py``, ``aoa.py``,
   ``aod.py``, ``aoo.py``, ``aos.py``

************
Project Tree
************

The project follows a **PEP 517 src-layout** with the importable package
under ``src/ut_arr/``, the PyPI distribution name is ``ut-arr``.  Build
metadata lives in ``pyproject.toml``, which reads runtime dependencies from
``requirements.txt`` and trove classifiers from ``classifiers.txt`` at build
time.  Documentation is authored in reStructuredText under ``docs/`` and built
with Sphinx.  Five GitHub Actions workflows handle continuous integration,
documentation deployment, PyPI publishing, GitHub releases and CodeQL security
analysis.  Helper scripts in ``scripts/`` automate common development tasks
such as linting, type-checking and documentation builds.  Editor
configurations for VS Code and Claude Code are included.

.. code-block:: text

   ut-arr/
   ├── .flake8                     # Flake8 linter configuration
   ├── .gitignore                  # Git ignore patterns
   ├── .gitlab-ci.yml              # GitLab CI pipeline (lint, test, build, docs)
   ├── .readthedocs.yaml           # Read the Docs build configuration
   ├── LICENSE.txt                 # GPL-3.0 license text
   ├── MANIFEST.in                 # Source distribution file inclusion rules
   ├── README.rst                  # Project documentation (this file)
   ├── classifiers.txt             # PyPI trove classifiers (dynamic)
   ├── pyproject.toml              # Build system and tool configuration
   ├── requirements.txt            # Runtime dependencies (dynamic)
   ├── .claude/                    # Claude Code project configuration
   │   ├── CLAUDE.md               #   Project overview and coding conventions
   │   ├── settings.json           #   Project metadata and permissions
   │   └── commands/               #   Slash commands
   │       ├── build.md            #     /build — build sdist and wheel
   │       ├── docs.md             #     /docs — build Sphinx documentation
   │       ├── lint.md             #     /lint — ruff + mypy
   │       └── test.md             #     /test — pytest with coverage
   ├── .github/                    # GitHub configuration
   │   ├── dependabot.yml          #   Automated dependency updates (weekly)
   │   └── workflows/              #   GitHub Actions workflows
   │       ├── ci.yml              #     Lint, test, build, docs on push/PR
   │       ├── codeql.yml          #     CodeQL security analysis (weekly + push/PR)
   │       ├── docs.yml            #     Build and deploy docs to GitHub Pages
   │       ├── publish.yml         #     Publish to TestPyPI/PyPI on release
   │       └── release.yml         #     Create GitHub Release on version tag
   ├── .vscode/                    # VS Code workspace configuration
   │   ├── extensions.json         #   Recommended extensions
   │   ├── launch.json             #   Debug configurations (pytest, current file)
   │   ├── settings.json           #   Python, ruff, mypy, editor settings
   │   └── tasks.json              #   Build tasks (docs, lint, test, package)
   ├── docs/                       # Sphinx documentation (reStructuredText)
   │   ├── Makefile                #   Sphinx Makefile (Linux/macOS)
   │   ├── api.rst                 #   Auto-generated API reference (automodule)
   │   ├── conf.py                 #   Sphinx configuration (local source priority)
   │   ├── helpers.rst             #   Build instructions, type aliases, dependencies
   │   ├── index.rst               #   Documentation root (toctree)
   │   ├── make.bat                #   Sphinx Makefile (Windows)
   │   ├── modules.rst             #   Module documentation toctree
   │   ├── readme.rst              #   Proxy: includes ../README.rst
   │   ├── reference.rst           #   Quick-reference tables for all classes
   │   └── modules/                #   Per-module documentation pages
   │       ├── ao2a.rst            #     Ao2A — cross-product of two arrays
   │       ├── aoa.rst             #     AoA — array of arrays
   │       ├── aod.rst             #     AoD — array of dictionaries
   │       ├── aoo.rst             #     AoO — array of objects
   │       ├── aos.rst             #     AoS/Str — array of strings
   │       ├── arr.rst             #     Arr — generic array operations
   │       ├── installation.rst    #     Installation instructions (orphan)
   │       ├── overview.rst        #     Package overview (orphan)
   │       ├── package_files.rst   #     Package file descriptions (orphan)
   │       ├── package_logging.rst #     Logging configuration (orphan)
   │       ├── package_modules.rst #     Module listing (orphan)
   │       └── see_also.rst        #     External references (orphan)
   ├── scripts/                    # Shell scripts
   │   ├── build.sh                #   Package build (black, ruff, mypy, twine)
   │   ├── build_docs.bat          #   Documentation build helper (Windows)
   │   ├── build_docs.sh           #   Documentation build helper (Linux/macOS)
   │   ├── git.sh                  #   Git setup notes
   │   └── github.sh               #   GitHub repository setup notes
   └── src/                        # Source root (src layout)
       └── ut_arr/                 #   Python package
           ├── __init__.py         #     Package initializer
           ├── __version__.py      #     Version string
           ├── ao2a.py             #     Ao2A — cross-product of two arrays (1 method)
           ├── aoa.py              #     AoA — array of arrays (9 methods)
           ├── aod.py              #     AoD — array of dictionaries (21 methods)
           ├── aoo.py              #     AoO — array of objects (1 method)
           ├── aos.py              #     AoS/Str — strings and string arrays (7 methods)
           ├── arr.py              #     Arr — generic array operations (24 methods)
           └── py.typed            #     PEP 561 type marker

******************************************
Modules, Classes, Methods and Type Aliases
******************************************

The sections below provide summary tables for every module, class,
method and Type Alias of the package.  Full details including parameter types and
docstrings are available in ``api``.

Modules
=======

.. table:: *Modules of Package ut-arr*

   +--------+------------------------------------------------+
   | Module | Description                                    |
   +========+================================================+
   | arr    | Manage generic arrays                          |
   |        | (see ``modules/arr``).                         |
   +--------+------------------------------------------------+
   | ao2a   | Manage arrays of two arrays                    |
   |        | (see ``modules/ao2a``).                        |
   +--------+------------------------------------------------+
   | aoa    | Manage array of arrays                         |
   |        | (see ``modules/aoa``).                         |
   +--------+------------------------------------------------+
   | aod    | Manage array of dictionaries                   |
   |        | (see ``modules/aod``).                         |
   +--------+------------------------------------------------+
   | aoo    | Manage array of objects                        |
   |        | (see ``modules/aoo``).                         |
   +--------+------------------------------------------------+
   | aos    | Manage array of strings and string conversions |
   |        | (see ``modules/aos``).                         |
   +--------+------------------------------------------------+

Classes
=======

.. table:: *Classes of Package ut-arr Modules*

   +--------+-------+--------+-------------------------------------------------+
   | Module | Class | Type   | Description                                     |
   +========+=======+========+=================================================+
   | arr    | Arr   | static | Manage generic arrays: append, extend, encode,  |
   |        |       |        | intersect, union, dictionary conversion, and    |
   |        |       |        | element access with bounds checking.            |
   +--------+-------+--------+-------------------------------------------------+
   | ao2a   | Ao2A  | static | Manage arrays of two arrays: yield              |
   |        |       |        | cross-product tuples from a pair of arrays.     |
   +--------+-------+--------+-------------------------------------------------+
   | aoa    | AoA   | static | Manage array of arrays: concatenate, convert to |
   |        |       |        | array of dicts, extract columns, union.         |
   +--------+-------+--------+-------------------------------------------------+
   | aod    | AoD   | static | Manage array of dictionaries: merge, split,     |
   |        |       |        | group, deduplicate, convert to AoA or dict.     |
   +--------+-------+--------+-------------------------------------------------+
   | aoo    | AoO   | static | Manage array of objects: remove duplicates and  |
   |        |       |        | None values.                                    |
   +--------+-------+--------+-------------------------------------------------+
   | aos    | Str   | static | Manage string conversions: parse date strings.  |
   +--------+-------+--------+-------------------------------------------------+
   | aos    | AoS   | static | Manage array of strings: NVL, lower-case,       |
   |        |       |        | deduplicate, date conversion.                   |
   +--------+-------+--------+-------------------------------------------------+

Methods
=======

Methods of Module: ``arr`` — Class: ``Arr``
-------------------------------------------

.. table:: *Methods of Module arr (Class Arr)*

   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | Method                  | Parameter                | Return          | Description                              |
   +=========================+==========================+=================+==========================================+
   | append                  | arr: TnArr,              | None            | Append item to the array.                |
   |                         | item: TnAny              |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | append_unique           | arr: TyArr,              | None            | Append item only if not present.         |
   |                         | item: TnAny              |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | apply_function          | arr: TyTupArr,           | TyTupArr        | Apply function to each element.          |
   |                         | function: TyCallable,    |                 |                                          |
   |                         | \*\*kwargs               |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | apply_replace           | arr: TyTupArr,           | TyTupArr        | Replace substring in string elements.    |
   |                         | source: TyStr,           |                 |                                          |
   |                         | target: TyStr            |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | apply_str               | arr: TyTupArr            | TyTupArr        | Stringify every non-None element.        |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | encode                  | arr: TnArr               | TnStr           | Join and percent-encode the array.       |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | extend                  | arr0: TnArr,             | TnArr           | Extend first array with second array.    |
   |                         | arr1: TnArr              |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | get_key_value           | arr: TyArr,              | TnStr           | Get next item if current matches value.  |
   |                         | ix: int,                 |                 |                                          |
   |                         | default: str,            |                 |                                          |
   |                         | value: str               |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | get_text                | arr: TyArr,              | TnStr           | Get stripped text at index.              |
   |                         | ix: int,                 |                 |                                          |
   |                         | default: str             |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | get_text_split          | arr: TyArr,              | TnStr           | Get text split by separator at index.    |
   |                         | ix0: int,                |                 |                                          |
   |                         | default: str,            |                 |                                          |
   |                         | ix1: int,                |                 |                                          |
   |                         | separator: str           |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | get_item                | arr: TnArr,              | TnAny           | Get item at index with bounds checking.  |
   |                         | ix: TnInt,               |                 |                                          |
   |                         | default: TnStr           |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | intersection            | arr0: TyArr,             | TyArr           | Set intersection of two arrays.          |
   |                         | arr1: TyArr              |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | is_empty                | arr: TnArr               | bool            | Check if array is None or empty.         |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | is_not_empty            | arr: TnArr               | bool            | Check if array has elements.             |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | join_not_none           | arr: Iterable[str|None], | TnStr           | Join non-None elements with separator.   |
   |                         | separator: str           |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | length                  | arr: TnArr               | TyNum           | Return array length (0 if empty).        |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | makedirs                | dirs: TnArr,             | None            | Create directories from array of paths.  |
   |                         | \*\*kwargs               |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_dic_from_keys_values | keys: TyArr,             | TyDic           | Create dict by zipping keys and values.  |
   |                         | values: TyArr            |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_dic_zip              | keys: Iterable[Any],     | TyDic           | Create dict by zipping two iterables.    |
   |                         | values: Iterable[Any]    |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_item                 | arr: TnArr,              | TnAny           | Return item at index.                    |
   |                         | ii: int                  |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_item_lower           | arr: TnArr,              | TnAny           | Return lower-cased item at index.        |
   |                         | ii: int                  |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_item_if              | string: TnStr,           | TnAny           | Return item if it contains substring.    |
   |                         | arr: TnArr,              |                 |                                          |
   |                         | ii: int                  |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_item0                | arr: TyArr               | Any             | Return first element.                    |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_item0_if             | string: str,             | Any             | Return first element if contains string. |
   |                         | arr: TyArr               |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_items_str            | arr: TnArr,              | TnStr           | Join slice into space-separated string.  |
   |                         | start: int,              |                 |                                          |
   |                         | end: int                 |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | to_dic                  | arr: TyArr,              | TyDic           | Convert array to dict using parallel     |
   |                         | keys: TyArr              |                 | keys.                                    |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_subarray             | arr: TyArr,              | TyArr           | Return bounded sub-array.                |
   |                         | from\_: int,             |                 |                                          |
   |                         | to\_: int                |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | sh_items_in_dic         | arr: TnArr,              | TyArr           | Collect dict values for keys in array.   |
   |                         | dic: TnDic               |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | union                   | arr1: TnArr,             | TnArr           | Union of two arrays (order-preserving).  |
   |                         | arr2: TnArr              |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+
   | yield_items             | arr: TyArr,              | Iterator[TnTup] | Yield (item, obj) tuples.                |
   |                         | obj: Any                 |                 |                                          |
   +-------------------------+--------------------------+-----------------+------------------------------------------+

Methods of Module: ``ao2a`` — Class: ``Ao2A``
---------------------------------------------

.. table:: *Methods of Module ao2a (Class Ao2A)*

   +-------------+---------------+--------------------+-------------------------------------+
   | Method      | Parameter     | Return             | Description                         |
   +=============+===============+====================+=====================================+
   | yield_items | ao2a: TyAo2A, | Iterator[TnTo3Any] | Yield cross-product tuples from two |
   |             | obj: Any      |                    | arrays.                             |
   +-------------+---------------+--------------------+-------------------------------------+

Methods of Module: ``aoa`` — Class: ``AoA``
-------------------------------------------

.. table:: *Methods of Module aoa (Class AoA)*

   +-------------------+-------------+--------+------------------------------------------+
   | Method            | Parameter   | Return | Description                              |
   +===================+=============+========+==========================================+
   | concatinate       | aoa: TyAoA  | TyArr  | Concatenate all sub-arrays into flat     |
   |                   |             |        | array.                                   |
   +-------------------+-------------+--------+------------------------------------------+
   | nvl               | aoa: TnAoA  | TyAoA  | Return array or [] if None.              |
   +-------------------+-------------+--------+------------------------------------------+
   | to_aod            | aoa: TyAoA, | TyAoD  | Convert to array of dicts using keys.    |
   |                   | keys: TyArr |        |                                          |
   +-------------------+-------------+--------+------------------------------------------+
   | to_arr_from_2cols | aoa: TyAoA, | TyArr  | Extract unique values from two columns.  |
   |                   | a_ix: TyAoI |        |                                          |
   +-------------------+-------------+--------+------------------------------------------+
   | to_doa_from_2cols | aoa: TyAoA, | TyDoA  | Group values by key into dict of arrays. |
   |                   | a_ix: TyAoI |        |                                          |
   +-------------------+-------------+--------+------------------------------------------+
   | to_dic_from_2cols | aoa: TyAoA, | TyDic  | Convert two columns to flat dictionary.  |
   |                   | a_ix: TyAoI |        |                                          |
   +-------------------+-------------+--------+------------------------------------------+
   | union             | aoa: TyAoA  | TyArr  | Union of all sub-arrays (with            |
   |                   |             |        | duplicates).                             |
   +-------------------+-------------+--------+------------------------------------------+
   | union_distinct    | aoa: TyAoA  | TyArr  | Union of all sub-arrays (distinct).      |
   +-------------------+-------------+--------+------------------------------------------+

Methods of Module: ``aod`` — Class: ``AoD``
-------------------------------------------

.. table:: *Methods of Module aod (Class AoD)*

   +--------------------------------+-------------------+---------+---------------------------------------+
   | Method                         | Parameter         | Return  | Description                           |
   +================================+===================+=========+=======================================+
   | add                            | aod: TyAoD,       | None    | Add dict or list to the array.        |
   |                                | obj: Any          |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | add_mapped_dic_value           | aod: TyAoD,       | TyAoD   | Extend with mapped dictionary value.  |
   |                                | dic: TnDic,       |         |                                       |
   |                                | key: TnAny,       |         |                                       |
   |                                | fnc: TyCallable   |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | append_unique                  | aod: TyAoD,       | None    | Append dict if not already present.   |
   |                                | dic: TyDic        |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | apply_function                 | aod: TyAoD,       | TyAoD   | Apply function to every dictionary.   |
   |                                | fnc: TnCallable,  |         |                                       |
   |                                | kwargs: TnDic     |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | merge_aod                      | aod0: TnAoD,      | TyAoD   | Cross-product merge of two arrays.    |
   |                                | aod1: TnAoD       |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | merge_dic                      | aod: TnAoD,       | TnAoD   | Merge every dict with a single dict.  |
   |                                | dic: TnDic        |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | nvl                            | aod: TnAoD        | TyAoD   | Return array or [] if falsy.          |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | sh_doaod_split_by_value_is_not | aod: TyAoD,       | TyDoAoD | Split into dict-of-AoD by empty/      |
   | _empty                         | key: Any,         |         | non-empty.                            |
   |                                | key_n: Any,       |         |                                       |
   |                                | key_y: Any        |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | sh_dod                         | aod: TyAoD,       | TyDoD   | Convert to dict-of-dicts by key.      |
   |                                | key: Any          |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | sh_unique                      | aod: TyAoD        | TyAoD   | Deduplicate array of dictionaries.    |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | split_by_value_is_not_empty    | aod: TyAoD,       | TyToAoD | Split into two arrays by empty/       |
   |                                | key: Any          |         | non-empty.                            |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | sw_empty_value_found           | aod: TyAoD,       | TyBool  | Check if any dict has empty value.    |
   |                                | key: str,         |         |                                       |
   |                                | sw_raise: bool    |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | sw_key_value_found             | aod: TnAoD,       | bool    | Check if any dict matches key-value.  |
   |                                | key: Any,         |         |                                       |
   |                                | value: Any        |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | to_aoa_of_keys_values          | aod: TyAoD        | TyAoA   | Convert to AoA with keys header.      |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | to_aoa_of_values               | aod: TyAoD        | TyAoA   | Convert to AoA (values only).         |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | to_aoa                         | aod: TnAoD,       | TnAoA   | Convert to AoA (configurable          |
   |                                | sw_keys: TyBool,  |         | keys/values).                         |
   |                                | sw_values: TyBool |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | to_arr_of_key_values           | aod: TyAoD,       | TyArr   | Extract all values for a key.         |
   |                                | key: Any          |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | to_dic_by_dic                  | aod: TnAoD,       | TyDic   | Convert to dict via meta-dict.        |
   |                                | d_meta: TnDic     |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | to_dic_by_ix                   | aod: TnAoD        | TyDic   | Convert to dict from first item-pair. |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | to_doaod_by_key                | aod: TnAoD,       | TyDoAoD | Group into dict-of-AoD by key.        |
   |                                | key: TnAny        |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | to_unique_by_key               | aod: TyAoD,       | TyAoD   | Deduplicate by key value.             |
   |                                | key: Any          |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+
   | union_distinct                 | aod0: TnAoD,      | TnAoD   | Union of two arrays (distinct).       |
   |                                | aod1: TnAoD       |         |                                       |
   +--------------------------------+-------------------+---------+---------------------------------------+

Methods of Module: ``aoo`` — Class: ``AoO``
-------------------------------------------

.. table:: *Methods of Module aoo (Class AoO)*

   +-----------+------------+--------+------------------------------------+
   | Method    | Parameter  | Return | Description                        |
   +===========+============+========+====================================+
   | to_unique | aoo: TyAoO | TyAoO  | Remove duplicates and None values. |
   +-----------+------------+--------+------------------------------------+

Methods of Module: ``aos``
--------------------------

.. table:: *Methods of Module aos (Class Str)*

   +---------+--------------+------------+--------------------------------+
   | Method  | Parameter    | Return     | Description                    |
   +=========+==============+============+================================+
   | sh_date | string: str, | TnDatetime | Parse date string to datetime. |
   |         | fmt: TnStr   |            |                                |
   +---------+--------------+------------+--------------------------------+

.. table:: *Methods of Module aos (Class AoS)*

   +---------------------------+------------+----------+-------------------------------------+
   | Method                    | Parameter  | Return   | Description                         |
   +===========================+============+==========+=====================================+
   | nvl                       | aos: TyAoS | TyAoS    | Return array or [] if None.         |
   +---------------------------+------------+----------+-------------------------------------+
   | sh_a_date                 | aos: TyAoS | TnAoDate | Convert string array to date array. |
   +---------------------------+------------+----------+-------------------------------------+
   | to_lower                  | aos: TyAoS | TyAoS    | Lower-case every string.            |
   +---------------------------+------------+----------+-------------------------------------+
   | to_unique                 | aos: TyAoS | TyAoS    | Remove duplicate strings.           |
   +---------------------------+------------+----------+-------------------------------------+
   | to_unique_lower           | aos: TyAoS | TyAoS    | Deduplicate and lower-case.         |
   +---------------------------+------------+----------+-------------------------------------+
   | to_unique_lower_invariant | aos: TyAoS | TyAoS    | Deduplicate case-insensitively.     |
   +---------------------------+------------+----------+-------------------------------------+

Type Aliases
============

Type aliases are defined at module level to keep function signatures
readable.  The naming convention is **Ty** for concrete types and
**Tn** for nullable types (``None | Ty…``).  See ``helpers`` for the
full reference.

.. table:: *Common type aliases*

   +----------------+------------------------+--------------------------+
   | Alias          | Expands to             | Description              |
   +================+========================+==========================+
   | ``TyAny``      | ``Any``                | Unrestricted type.       |
   +----------------+------------------------+--------------------------+
   | ``TyArr``      | ``list[Any]``          | List of arbitrary items. |
   +----------------+------------------------+--------------------------+
   | ``TyDic``      | ``dict[Any, Any]``     | Flat dictionary.         |
   +----------------+------------------------+--------------------------+
   | ``TyStr``      | ``str``                | String type.             |
   +----------------+------------------------+--------------------------+
   | ``TyNum``      | ``int | float``        | Numeric type.            |
   +----------------+------------------------+--------------------------+
   | ``TyBool``     | ``bool``               | Boolean type.            |
   +----------------+------------------------+--------------------------+
   | ``TyCallable`` | ``Callable[..., Any]`` | Any callable.            |
   +----------------+------------------------+--------------------------+

.. table:: *Data structure type aliases*

   +-------------+-------------------------------------+--------+---------------------------------------+
   | Alias       | Expands to                          | Module | Description                           |
   +=============+=====================================+========+=======================================+
   | ``TyAoA``   | ``list[list[Any]]``                 | aoa    | Array of Arrays.                      |
   +-------------+-------------------------------------+--------+---------------------------------------+
   | ``TyAoD``   | ``list[dict[Any, Any]]``            | aod    | Array of Dictionaries.                |
   +-------------+-------------------------------------+--------+---------------------------------------+
   | ``TyAoO``   | ``list[object]``                    | aoo    | Array of Objects.                     |
   +-------------+-------------------------------------+--------+---------------------------------------+
   | ``TyAoS``   | ``list[str]``                       | aos    | Array of Strings.                     |
   +-------------+-------------------------------------+--------+---------------------------------------+
   | ``TyAo2A``  | ``tuple[list[Any], list[Any]]``     | ao2a   | Pair of Arrays.                       |
   +-------------+-------------------------------------+--------+---------------------------------------+
   | ``TyDoA``   | ``dict[Any, list[Any]]``            | aoa    | Dictionary of Arrays.                 |
   +-------------+-------------------------------------+--------+---------------------------------------+
   | ``TyDoD``   | ``dict[Any, dict[Any, Any]]``       | aod    | Dictionary of Dictionaries.           |
   +-------------+-------------------------------------+--------+---------------------------------------+
   | ``TyDoAoD`` | ``dict[Any, list[dict[Any, Any]]]`` | aod    | Dictionary of Arrays of Dictionaries. |
   +-------------+-------------------------------------+--------+---------------------------------------+

.. table:: *Nullable type aliases*

   +----------------+---------------------------------+---------------------------------+
   | Alias          | Expands to                      | Description                     |
   +================+=================================+=================================+
   | ``TnArr``      | ``None | list[Any]``            | Nullable array.                 |
   +----------------+---------------------------------+---------------------------------+
   | ``TnAny``      | ``None | Any``                  | Nullable any.                   |
   +----------------+---------------------------------+---------------------------------+
   | ``TnStr``      | ``None | str``                  | Nullable string.                |
   +----------------+---------------------------------+---------------------------------+
   | ``TnInt``      | ``None | int``                  | Nullable integer.               |
   +----------------+---------------------------------+---------------------------------+
   | ``TnDic``      | ``None | dict[Any, Any]``       | Nullable dictionary.            |
   +----------------+---------------------------------+---------------------------------+
   | ``TnAoD``      | ``None | list[dict[Any, Any]]`` | Nullable array of dictionaries. |
   +----------------+---------------------------------+---------------------------------+
   | ``TnAoA``      | ``None | list[list[Any]]``      | Nullable array of arrays.       |
   +----------------+---------------------------------+---------------------------------+
   | ``TnCallable`` | ``None | Callable[..., Any]``   | Nullable callable.              |
   +----------------+---------------------------------+---------------------------------+
   | ``TnDatetime`` | ``None | datetime``             | Nullable datetime.              |
   +----------------+---------------------------------+---------------------------------+

########
Appendix
########

.. table:: *Documents*

   +-------------+-------------------------------------------------+
   | Document    | Description                                     |
   +=============+=================================================+
   | `glossary`_ | Python glossary (files, classes, methods).      |
   +-------------+-------------------------------------------------+
   | `logging`_  | Logging configuration and examples.             |
   +-------------+-------------------------------------------------+
   | ``api``     | Auto-generated API reference from docstrings.   |
   +-------------+-------------------------------------------------+
   | ``helpers`` | Build instructions, type aliases, dependencies. |
   +-------------+-------------------------------------------------+
   | ``modules`` | Detailed module and class documentation.        |
   +-------------+-------------------------------------------------+

.. _glossary: https://pypi.org/project/ut-log/#glossary
.. _logging: https://pypi.org/project/ut-log/#logging

*****************************
Installation of Documentation
*****************************

Prerequisites
=============

Install all dependencies automatically::

   ./scripts/build_docs.sh install-deps

This installs system packages (python3, pandoc, make, texlive) and Python
packages (sphinx, sphinx-rtd-theme) on RHEL 9/10 via ``dnf`` or ``yum``.

Using scripts/build_docs.sh or scripts\\build_docs.bat
======================================================

A convenience script ``scripts/build_docs.sh`` (Linux) or ``scripts\build_docs.bat``
(Windows) is provided in the project root.
It builds Sphinx documentation in multiple formats: HTML, PDF, EPUB, DOCX,
and man pages.

On Linux, make the script executable and run it::

   chmod +x scripts/build_docs.sh

On Windows::

   scripts\build_docs.bat

.. table:: *scripts/build_docs.sh format targets*

   +--------+-------------------------------------------+----------------------------------------+
   | Format | Command                                   | Description                            |
   +========+===========================================+========================================+
   | all    | ``./scripts/build_docs.sh``               | Build all formats (default).           |
   +--------+-------------------------------------------+----------------------------------------+
   | HTML   | ``./scripts/build_docs.sh html``          | Build HTML documentation.              |
   +--------+-------------------------------------------+----------------------------------------+
   | PDF    | ``./scripts/build_docs.sh latexpdf``      | Build PDF via LaTeX.                   |
   +--------+-------------------------------------------+----------------------------------------+
   | EPUB   | ``./scripts/build_docs.sh epub``          | Build EPUB e-book.                     |
   +--------+-------------------------------------------+----------------------------------------+
   | DOCX   | ``./scripts/build_docs.sh docx``          | Build Word document (requires pandoc). |
   +--------+-------------------------------------------+----------------------------------------+
   | Man    | ``./scripts/build_docs.sh man``           | Build man pages.                       |
   +--------+-------------------------------------------+----------------------------------------+
   | HTML,  | ``./scripts/build_docs.sh html latexpdf`` | Build multiple formats.                |
   | PDF    |                                           |                                        |
   +--------+-------------------------------------------+----------------------------------------+

.. table:: *scripts/build_docs.sh utility targets*

   +------------------------------------------+----------------------------------------+
   | Command                                  | Description                            |
   +==========================================+========================================+
   | ``./scripts/build_docs.sh clean``        | Remove build artifacts.                |
   +------------------------------------------+----------------------------------------+
   | ``./scripts/build_docs.sh install-deps`` | Install system and Python dependencies |
   |                                          | (RHEL 9/10).                           |
   +------------------------------------------+----------------------------------------+
   | ``./scripts/build_docs.sh --help``       | Show help.                             |
   +------------------------------------------+----------------------------------------+

.. note::

   On Windows, replace ``./scripts/build_docs.sh`` with ``scripts\build_docs.bat``.

Using make
==========

Alternatively, use the Sphinx ``Makefile`` or ``make.bat`` in the ``docs/``
directory directly.

.. table:: *Documentation build output locations*

   +--------+------------------------------+------------------------------------+
   | Format | Command                      | Output                             |
   +========+==============================+====================================+
   |        | ``cd docs && make help``     | | List all available targets.      |
   +--------+------------------------------+------------------------------------+
   | HTML   | ``cd docs && make html``     | | ``docs/_build/html/index.html``  |
   +--------+------------------------------+------------------------------------+
   | PDF    | ``cd docs && make latexpdf`` | | ``docs/_build/latex/ut-arr.pdf`` |
   +--------+------------------------------+------------------------------------+
   | EPUB   | ``cd docs && make epub``     | | ``docs/_build/epub/ut-arr.epub`` |
   +--------+------------------------------+------------------------------------+
   |        | ``cd docs && make clean``    | | Remove build artifacts.          |
   +--------+------------------------------+------------------------------------+

On Windows, use ``make.bat`` instead of ``make``.

*******
License
*******

``GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause``

Copyright 2025 Bernd Stroehle.
