ut-aod 2.0.0.20251020

Utilities for Arrays of Dictionaries

ut_aod

Overview

Utilities for Arrays of Dictionaries

Installation

Package ut_aod can be installed from PyPI.

To install with pip:

$ python -m pip install ut_aod

Package logging

(c.f.: https://pypi.org/project/ut-log/)

Package files

Classification

The Package ut_aod consist of the following file types (c.f.: Appendix: Python Glossary):

1. Special files:

   1. py.typed

2. Special modules:

   1. __init__.py

   2. __version__.py

3. Modules

   1. aod.py

Modules

Module: aod.py

The Array of Dictionaries module aod.py contains the static classes AoD and IoD and the dictionary of callables doc.

Class: AoD

The static Class AoD is used to manage arrays of dictionaries; it contains no variables and only static- or class-methods.

Methods

Methods of class AoD

Name	Short description
add	Append the object to the Array of dictionaries if the object is a dictionary or extend it with the objects the the object is a list.
add_mapped_dic_value	Add the dictionary element mapped by the function to the array of dictionaries.
append_unique	Append dictionary to array of dictionaries if it does not exist in the dictionary.
apply_function	Apply the function to the array of dictionaries.
dic_found_with_empty_value	Return True or raise an exception if the array of dictionaries contains a dictionary with empty value and the execption switch is True.
merge_aod	Merge two array of dictionaries.
merge_dic	Merge array of dictionaries with dictionary.
nvl	Replace empty array of dictionaries.
put	Write transformed array of dictionaries to a csv file file with a selected I/O function.
sh_doaod_split_by_value_is_not_empty	Converted array of dictionaries to dictionary of array of dictionaries by using conditional split.
sh_dod	Convert array of dictionaries to dictionaries of dictionaries.
sh_key_value_found	Show True if an element exists in the array of dictionaries which contains the key, value pair.
sh_unique	Deduplicate array of dictionaries.
split_by_value_is_not_empty	Split array of dictionaries by the condition “the given key value is not empty”.
to_aoa of_keys_values	Convert array of dictionaries to array of arrays using keys of any dictionary and values of all dictionaries.
to_aoa of_values	Convert array of dictionaries to array of arrays using values of all dictionaries.
to_aoa	Convert array of dictionaries to array of arrays controlled by key- and value-switch.
to_arr of_key_values	Convert array of dictionaries to array of arrays using keys of any dictionary and values of all dictionaries.
to_csv_with_dictwriterows	Write array of dictionaries to csv file with pandas.
to_csv_with_pd	Write array of dictionaries to csv file with pandas.
to_csv_with_pl	Write array of dictionaries to csv file with polars.
to_dic_by_dic	Convert array of dictionaries to dictionary by using the key
to_dic_by_ix	Convert array of dictionaries to dictionary by using lowercase keys.
to_doaod_by_key	Convert array of dictionaries to dictionary of arrays of dictionaries by using the key.
to_unique_by_key	Convert array of dictionaries to unique array of dictionaries by selecting dictionaries with key.
union_distinct	Make the array of dictionaries unique.

Method: add

Description

Add an object to an array of dictionaries.

1. If the objects is a dictionary:

   • the object is appended to the array of dictionaries

2. If the objects is an array of dictionaries:

   • the object extends the array of dictionaries

Parameter

Parameter of Method add

Name	Type	Description
aod	TyAoD	Array of dictionaries
obj	TyAny	Object

Return Value

Return value of Method add

Name	Type	Description
_aod_new	TyAoD	New array of dictionaries.

Method: add_mapped_dic_value

Description

Add the mapped dictionary value of the given key to the array of dictionaries.

Parameter

Parameter of Method add_mapped_dic_value

Name	Type	Description
cls	class	Current class
aod	TyAoD	Array of dictionaries
dic	TnDic	Dictionary
key	TnAny	Key of dictionary
fnc	TyCallable	Function

Return Value

Return value of Method add

Name	Type	Description
_aod_new	TyAoD	New array of dictionaries.

Method: add_mapped_dic_value

Description

1. Apply the given function to the value of the given dictionary for the key.

2. The result is used to extend the given array of dictionaries.

Parameter

Parameter of Method extend_if_not_empty

Name	Type	Description
aod	TyAoD	Array of dictionaries
dic	TyDic	Dictionary
key	TnAny	Dictionary key
function	TyCallable	Function

Return Value

Return value of Method extend_if_not_empty

Name	Type	Description
_aod_new	TyAoD	New array of dictionaries

Method: append_unique

Description

Append the dictionary to the array of dictionaries if it does not exist in the array.

Parameter

Parameter of Method append_unique

Name	Type	Description
aod	TyAoD	Array of dictionaries
dic	TyDic	Dictionary

Method: apply_function

Description

Create a new array of dictionaries by applying the function to each element of the array of dictionaries.

Parameter

Parameter of Method apply_function

Name	Type	Description
aod	TyAoD	Array of dictionaries
fnc	TnCallable	Function
kwargs	TnDic	Dictionary of keyword arguments

Return value

Return value of Method apply_function

Name	Type	Description
aod_new	TyAoD	new array of dictionaries

Method: dic_found_with_empty_value

Description

The Method dic_found_with_empty_value performs the following steps: #. Loop thru the array of dictionaries;

If the dictionary value for the key is empty and

if the switch “sw_raise” is True then

raise an Exception

else

return True.

1. return False

Parameter

Parameter of Method dic_found_with_empty_value

Name	Type	Default	Description
aod	TyAoD		Array of dictionaries
key	TyStr		Dictionary key
sw_raise	TyBool	False	Raise switch

Return Value

Return value of Method dic_found_with_empty_value

Name	Type	Description
	TyBool	key is found in a dictionary

Method: merge_aod

Description

Merge two arrays of dictionaries. Every dictionary of the first array of dictionaries is merged with all dictionaries of the second array of dictionaries.

Parameter

Parameter of Method join_aod

Name	Type	Description
aod0	TyAoD	First array of dictionaries
aod1	TyAoD	Second array of dictionaries

Return Value

Return value of Method join_aod

Name	Type	Description
_aod_new	TyAoD	New array of dictionaries

Method: merge_dic

Description

Merge array of dictionaries with a dictionary. Every dictionary of the array of dictionaries is merged with the dictionary.

Parameter

Name	Type	Description
aod	TyAoD	Array of dictionaries
dic	TyDic	Dictionary

Return Value

Return value of Method merge_dic

Name	Type	Description
_aod_new	TyAoD	New array of dictionaries

Method: nvl

Description

If the array of dictionaries is undefined then return the empty array otherwise return the array of dictionaries.

Parameter

Parameter of Method nvl

Name	Type	Description
aod	TnAoD	Array of dictionaries

Return Value

Return value of Method nvl

Name	Type	Description
aod_new	TyArr	New array of dictionaries

Method: put

Description

1. Transform array of dictionaries (1.argument) with a transformer function (3.argument)

2. If the I/O function is defined for the given dataframe type (4.argument). #. write result to a csv file with the given path name (2.argument).

Parameter

Parameter of Method put

Name	Type	Description
aod	TyAoD	Array of dictionaries
path	TyPath	Csv file path
fnc_aod	TyAoD	AoD function
df_type	TyStr	Dataframe type

Method: sh_doaod_split_by_value_is_not_empty

Description

1. Create 2-dimensional dict. of array of dictionaries from given array of dictionaries and key to split the array of dictionaries into 2 array of dictionaries by the two conditions

   • The key is contained in the dictionary and the value empty.

   • The key is contained in the dictionary and the value is not empty.

2. The first array of dictionaries is created by the condition and is assigned to the new dictionary of array of dictionaries using the given key.

3. The second array of dictionaries is created by the negation of the condition and is assigned to the new dictionary of array of dictionaries using the given key.

Parameter

Parameter of Method sh_doaod_split_by_value_is_not_empty

Name	Type	Description
aod	TyAoD	Array of dictionaries
key	Any	Dictionary key
key_n	Any	key of the array of dictionaries wich satisfies the condition.
key_y	Any	key of the array of dictionaries which does not satisfies the condition.

Return value

Return value of Method sh_doaod_split_by_value_is_not_empty

Name	Type	Description
doaod	TyDoAoD	Dictionary of array of dictionaries

Method: sh_dod

Description

Create dictionary of dictionaries from the array of dictionaries and the key.

Parameter

Parameter of Method sh_dod

Name	Type	Description
aod	TyAoD	Array of dictionaries
key	Any	Key

Return Value

Return value of Method sh_dod

Name	Type	Description
dod	TyDoD	Dictionary of dictionaries

Method: sh_unique

Description

Deduplicate array of dictionaries (1.argument).

Parameter

Parameter of Method sh_unique

Name	Type	Description
aod	TyAoD	Array of dictionaries
key	Any	Key

Return Value

Return value of Method sh_unique

Name	Type	Description
aod_new	TyAoD	New array of dictionaties

Method: split_by_value_is_not_empty

Description

Split the given array of dictionary into 2 arrays of dictionary by the condition “the key is contained in the dictionary and the value is not empty”

Parameter

Parameter of Method split_by_value_is_not_empty

Name	Type	Description
aod	TyAoD	array of dictionaries
key	Any	Key

Return Value

Return value of Method split_by_value_is_not_empty

Name	Type	Description
(aod_n, aod_y)	Ty2ToAoD	Tuple of 2 arrays of dictionaries

Method: sw_key_value_found

Description

Set the condition to True if: * the key is contained in a dictionary of the array of dictionaries and * the key value is not empty”

Parameter

Parameter value of Method sw_key_value_found

Name	Type	Description
aod	TyAoD	Array of dictionaries
key	Any	Key

Return Value

Return value of Method sw_key_value_found

Name	Type	Description
sw	TyBool	key is contained in a dictionary of the array of dictionaries

Method: to_aoa

Description

Create array of arrays from given array of dictionaries (1.argument).

1. If switch sw_keys (2.argument) is True:

   • Create the first element of the array of arrays as the list of dict. keys of the first elements of the array of dictionaries.

2. If the switch sw_values (3. argument) is True:

   • Create the other elemens of the array of dictionries as list of dict. values of the elements of the array of dictionaries.

Parameter

Parameter of Method to_aoa

Name	Type	Description
aod	TyAoD	Array of dictionaries
sw_keys	TyBool	Keys switch
sw_values	TyBool	Values switch

Return Value

Return value of Method to_aoa

Name	Type	Description
aoa	TyAoA	array of arrays

Method: to_aoa of_key_values

Description

Convert the given array of dictionary (1.argument) into an array of arrays. #. Create first element of the new array of arrays as the keys-list of the first dictionary. #. Create other elements as the values-lists of the dictionaries of the array of dictionaries.

Parameter

Parameter of Method to_aoa of_key_values

Name	Type	Description
aod	TyAoD	Array of dictionaries

Return Value

Return value of Method to_aoa of_key_values

Name	Type	Description
aoa	TyAoA	Array of arrays

Method: to_aoa_of_values

Description

Convert the given array of dictionaries (1.argument) into an array of arrays. The elements of the new array of arrays are the values-lists of the dictionaries of the array of dictionaries.

Parameter

Parameter of Method to_aoa_of_values

Name	Type	Description
aod	TyAoD	Array of dictionaries

Return Value

Return value of Method to_aoa_of_values

Name	Type	Description
aoa	TyAoA	Array of arrays

Method: to_arr_of_key_values

Description

Convert the given array of dictionaries (1.argument) to an array. The elements of the new array are the selected values of each dictionary of the array of dictionaries with the given key (2.argument).

Parameter

Parameter of Method to_arr_of_key_values

Name	Type	Description
aod	TyAoD	Array of dictionaries
key	Any	Key

Return Value

Return value of Method to_arr_of_key_values

Name	Type	Description
arr	TyAoD	New array of dictionaries

Method: to_csv_with_dictwriterows

Description

Write given array of dictionaries (1.argument) to a csv file with the given path name (2.argument) using the function “dictwriter” of the builtin path module “csv”

Parameter

Parameter of Method csv_dictwriterows

Name	Type	Description
aod	TyAoD	Array of dictionaries
path	TyPath	Path

Method: to_csv_with_pd

Description

1. Convert the array of dictionaries to a pandas dataframe.

2. Apply the given function to the pandas dataframe.

3. Write the pandas dataframe to a csv file with the given name.

Parameter

Parameter of Method pd-to_csv

Name	Type	Description
aod	TyAoD	Array of dictionaries
path	TyPath	Csv file path
fnc	TyCallable	Panda function

Method: to_csv_with_pl

Description

1. Convert the array of dictionaries to a panda dataframe.

2. Convert the panda dataframe to a polars dataframe.

3. Apply the given function to the polars dataframe.

4. Write the polars dataframe to a csv file with the given name.

Parameter

Parameter of Method pl_to_csv

Name	Type	Description
aod	TyAoD	Array of dictionaries
path	TyPath	Csv file path
fnc	TyCallable	Polars function

Method: to_doaod_by_key

Parameter

Parameter of Method to_doaod_by_key

Name	Type	Description
aod	TyAoD	Array of dictionaries
key	Any	Key

Return Value

Return value of Method to_doaod_by_key

Name	Type	Description
doaod	TyAoD	Dictionary of array of dictionaries

Method: to_dod_by_key

Parameter

Parameter of Method to_dod_by_key

Name	Type	Description
aod	TyAoD	Array of dictionaries
key	Any

Return Value

Return value of Method to_dod_by_key

Name	Type	Description
dic	TyDic

Method: to_doa_by_lc_keys

Parameter

Parameter of Method to_doa_by_lc_keys

Name	Type	Description
aod	TyAoD	Array of dictionaries
key	Any

Return Value

Return value of Method to_doa_by_lc_keys

Name	Type	Description
doa	TyDoA	Dictionary of arrays

Method: to_unique_by_key

Parameter

Parameter of Method to_unique_by_key

Name	Type	Description
aod	TyAoD	Array of dictionaries
key	Any

Return Value

Return value of Method to_unique_by_key

Name	Type	Description
_aod_new	TyAoD	New array of dictionaries

Method: write_xlsx_wb

Parameter

Parameter of Method write_xlsx_wb

Name	Type	Description
aod	TyAoD	Array of dictionaries

Appendix

Python Glossary

Python Modules

Overview

Python Modules

Name	Definition
Python modules	Files with suffix .py; they could be empty or contain python code; other modules can be imported into a module.
special Python modules	Modules like __init__.py or main.py with special names and functionality.

Python Function

Overview

Python Function

Name	Definition
Python function	Files with suffix .py; they could be empty or contain python code; other modules can be imported into a module.
special Python modules	Modules like __init__.py or main.py with special names and functionality.

Python Packages

Overview

Python Packages Overview

Name	Definition
Python package	Python packages are directories that contains the special module __init__.py and other modules, sub packages, files or directories.
Python sub-package	Python sub-packages are python packages which are contained in another python 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

Special python package sub-directories

Special python package 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 Files

Overview

Python files

Name	Definition
Python modules	Files with suffix .py; they could be empty or contain python code; other modules can be imported into a module.
Python package files	Files within a python package.
Python dunder modules	Python modules which are named with leading and trailing double underscores.
special Python files	Files which are not modules and used as python marker files like py.typed.
special Python modules	Modules like __init__.py or main.py with special names and functionality.

Python Special Files

Python special 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.

Python Special Modules

Python special 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 package entry point point. 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 classes

Overview

Python classes overview

Name	Description
Python class	A class is a container to group related methods and variables together, even if no objects are created. This helps in organizing code logically.
Python static class	A class which contains only @staticmethod or @classmethod methods and no instance-specific attributes or methods.

Python methods

Overview

Python methods overview

Name	Description
Python method	Python functions defined in python modules.
Python class method	Python functions defined in python classes.
Python special class method	Python class methods with special names and functionalities.

Python class methods

Python class methods

Name	Description
Python no instance class method	Python function defined in python classes and decorated with @classmethod or @staticmethod. The first parameter conventionally called cls is a reference to the current class.
Python instance class method	Python function defined in python classes; the first parameter conventionally called self is a reference to the current class object.
special Python class method	Python class functions with special names and functionalities.

Python special class methods

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. The method us a single parameter conventionally called self to access the object.

Table of Contents

Table of Content

• ut_aod

  • Overview

  • Installation

  • Package logging

  • Package files

  • Modules

    • Class: AoD

      • Methods

      • Method: add

        • Description

        • Parameter

        • Return Value

      • Method: add_mapped_dic_value

        • Description

        • Parameter

        • Return Value

      • Method: add_mapped_dic_value

        • Description

        • Parameter

        • Return Value

      • Method: append_unique

        • Description

        • Parameter

      • Method: apply_function

        • Description

        • Parameter

        • Return value

      • Method: dic_found_with_empty_value

        • Description

        • Parameter

        • Return Value

      • Method: merge_aod

        • Description

        • Parameter

        • Return Value

      • Method: merge_dic

        • Description

        • Parameter

        • Return Value

      • Method: nvl

        • Description

        • Parameter

        • Return Value

      • Method: put

        • Description

        • Parameter

      • Method: sh_doaod_split_by_value_is_not_empty

        • Description

        • Parameter

        • Return value

      • Method: sh_dod

        • Description

        • Parameter

        • Return Value

      • Method: sh_unique

        • Description

        • Parameter

        • Return Value

      • Method: split_by_value_is_not_empty

        • Description

        • Parameter

        • Return Value

      • Method: sw_key_value_found

        • Description

        • Parameter

        • Return Value

      • Method: to_aoa

        • Description

        • Parameter

        • Return Value

      • Method: to_aoa of_key_values

        • Description

        • Parameter

        • Return Value

      • Method: to_aoa_of_values

        • Description

        • Parameter

        • Return Value

      • Method: to_arr_of_key_values

        • Description

        • Parameter

        • Return Value

      • Method: to_csv_with_dictwriterows

        • Description

        • Parameter

      • Method: to_csv_with_pd

        • Description

        • Parameter

      • Method: to_csv_with_pl

        • Description

        • Parameter

      • Method: to_doaod_by_key

        • Parameter

        • Return Value

      • Method: to_dod_by_key

        • Parameter

        • Return Value

      • Method: to_doa_by_lc_keys

        • Parameter

        • Return Value

      • Method: to_unique_by_key

        • Parameter

        • Return Value

      • Method: write_xlsx_wb

• Appendix

  • Python Modules

  • Python Function

  • Python Packages

    • Overview

    • Special python package sub-directories

  • Python Files

    • Overview

    • Python Special Files

    • Python Special Modules

  • Python classes

  • Python methods

    • Overview

    • Python class methods

    • Python special class methods

• Table of Contents