ut-arr 2.0.0.20260306

Utilities for Arrays

ut-arr

Utilities for Array Management

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

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

Logging

Logging is provided by the classes ut_log.log.Log or ut_log.log.LogEq. See ut_log on PyPI 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):

1. Special files — py.typed

2. Special modules — __init__.py, __version__.py

3. 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.

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

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

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

Methods of Module arr (Class Arr)

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

Methods of Module: ao2a — Class: Ao2A

Methods of Module ao2a (Class Ao2A)

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

Methods of Module: aoa — Class: AoA

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, keys: TyArr	TyAoD	Convert to array of dicts using keys.
to_arr_from_2cols	aoa: TyAoA, a_ix: TyAoI	TyArr	Extract unique values from two columns.
to_doa_from_2cols	aoa: TyAoA, a_ix: TyAoI	TyDoA	Group values by key into dict of arrays.
to_dic_from_2cols	aoa: TyAoA, a_ix: TyAoI	TyDic	Convert two columns to flat dictionary.
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

Methods of Module aod (Class AoD)

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

Methods of Module: aoo — Class: AoO

Methods of Module aoo (Class AoO)

Method	Parameter	Return	Description
to_unique	aoo: TyAoO	TyAoO	Remove duplicates and None values.

Methods of Module: aos

Methods of Module aos (Class Str)

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

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.

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.

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.

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

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.

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

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, PDF	./scripts/build_docs.sh html latexpdf	Build multiple formats.

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.

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.