mappingtools 0.3.0__py3-none-any.whl

mappingtools-0.3.0.dist-info/METADATA

@@ -0,0 +1,459 @@
+Metadata-Version: 2.4
+Name: mappingtools
+Version: 0.3.0
+Summary: MappingTools. Do stuff with Mappings and more
+Project-URL: Homepage, https://erivlis.github.io/mappingtools
+Project-URL: Bug Tracker, https://github.com/erivlis/mappingtools/issues
+Project-URL: Source, https://github.com/erivlis/mappingtools
+Author-email: Eran Rivlis <eran@rivlis.info>
+License-File: LICENSE
+Keywords: Mapping,manipulate,mutate,transform
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-gen-files; extra == 'docs'
+Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == 'docs'
+Requires-Dist: mkdocs-glightbox; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocs-section-index; extra == 'docs'
+Requires-Dist: mkdocstrings-python; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-randomly; extra == 'test'
+Requires-Dist: pytest-xdist; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MappingTools
+
+> Do stuff with Mappings and more!!!
+
+This library provides utility functions for manipulating and transforming data structures which have or include
+Mapping-like characteristics. Including inverting dictionaries, converting class like objects to dictionaries, creating
+nested defaultdicts, and unwrapping complex objects.
+
+<table>
+  <tr style="vertical-align: middle;">
+    <td>Package</td>
+    <td>
+      <img alt="PyPI - version" src="https://img.shields.io/pypi/v/mappingtools">
+      <img alt="PyPI - Status" src="https://img.shields.io/pypi/status/mappingtools">
+      <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/mappingtools">
+      <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dd/mappingtools">
+      <br>
+      <img alt="GitHub" src="https://img.shields.io/github/license/erivlis/mappingtools">
+      <img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/erivlis/mappingtools">
+      <img alt="GitHub last commit (by committer)" src="https://img.shields.io/github/last-commit/erivlis/mappingtools">
+      <a href="https://github.com/erivlis/mappingtools/graphs/contributors"><img alt="Contributors" src="https://img.shields.io/github/contributors/erivlis/mappingtools.svg"></a>
+    </td>
+  </tr>
+  <tr>
+    <td>Tools</td>
+    <td>
+      <a href="https://www.jetbrains.com/pycharm/"><img alt="PyCharm" src="https://img.shields.io/badge/PyCharm-FCF84A.svg?logo=PyCharm&logoColor=black&labelColor=21D789&color=FCF84A"></a>
+      <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" style="max-width:100%;"></a>
+      <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv" style="max-width:100%;"></a>
+      <!-- a href="https://squidfunk.github.io/mkdocs-material/"><img src="https://img.shields.io/badge/Material_for_MkDocs-526CFE?&logo=MaterialForMkDocs&logoColor=white&labelColor=grey"></a -->
+    </td>
+  </tr>
+  <tr>
+    <td>CI/CD</td>
+    <td>
+      <a href="https://github.com/erivlis/mappingtools/actions/workflows/test.yml"><img alt="Tests" src="https://github.com/erivlis/mappingtools/actions/workflows/test.yml/badge.svg?branch=main"></a>
+      <a href="https://github.com/erivlis/mappingtools/actions/workflows/publish.yml"><img alt="Publish" src="https://github.com/erivlis/mappingtools/actions/workflows/publish.yml/badge.svg"></a>
+      <!--a href="https://github.com/erivlis/mappingtools/actions/workflows/publish-docs.yaml"><img alt="Publish Docs" src="https://github.com/erivlis/mappingtools/actions/workflows/publish-docs.yaml/badge.svg"></a-->
+    </td>
+  </tr>
+  <tr>
+    <td>Scans</td>
+    <td>
+      <a href="https://codecov.io/gh/erivlis/mappingtools"><img alt="Coverage" src="https://codecov.io/gh/erivlis/mappingtools/graph/badge.svg?token=POODT8M9NV"/></a>
+      <br>
+      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_mappingtools"><img alt="Quality Gate Status" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_mappingtools&metric=alert_status"></a>
+      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_mappingtools"><img alt="Security Rating" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_mappingtools&metric=security_rating"></a>
+      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_mappingtools"><img alt="Maintainability Rating" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_mappingtools&metric=sqale_rating"></a>
+      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_mappingtools"><img alt="Reliability Rating" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_mappingtools&metric=reliability_rating"></a>
+      <br>
+      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_mappingtools"><img alt="Lines of Code" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_mappingtools&metric=ncloc"></a>
+      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_mappingtools"><img alt="Vulnerabilities" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_mappingtools&metric=vulnerabilities"></a>
+      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_mappingtools"><img alt="Bugs" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_mappingtools&metric=bugs"></a>
+      <br>
+      <a href="https://app.codacy.com/gh/erivlis/mappingtools/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img alt="Codacy Quality" src="https://app.codacy.com/project/badge/Grade/8b83a99f939b4883ae2f37d7ec3419d1"></a>
+      <a href="https://app.codacy.com/gh/erivlis/mappingtools/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage"><img alt="Codacy Coverage" src="https://app.codacy.com/project/badge/Coverage/8b83a99f939b4883ae2f37d7ec3419d1"/></a>
+    </td>
+  </tr>
+</table>
+
+## Usage
+
+### Transformers
+
+#### `distinct`
+
+Yields distinct values for a specified key across multiple mappings.
+
+<!-- name: test_distinct -->
+
+```python
+from mappingtools import distinct
+
+mappings = [
+    {'a': 1, 'b': 2},
+    {'a': 2, 'b': 3},
+    {'a': 1, 'b': 4}
+]
+distinct_values = list(distinct('a', *mappings))
+print(distinct_values)
+# Output: [1, 2]
+```
+
+#### `keep`
+
+Yields subsets of mappings by retaining only the specified keys.
+
+<!-- name: test_keep -->
+
+```python
+from mappingtools import keep
+
+mappings = [
+    {'a': 1, 'b': 2, 'c': 3},
+    {'a': 4, 'b': 5, 'd': 6}
+]
+keys_to_keep = ['a', 'b']
+result = list(keep(keys_to_keep, *mappings))
+# result: [{'a': 1, 'b': 2}, {'a': 4, 'b': 5}]
+```
+
+#### `remove`
+
+Yields mappings with specified keys removed. It takes an iterable of keys and multiple mappings, and returns a generator
+of mappings with those keys excluded.
+
+<!-- name: test_remove -->
+
+```python
+from mappingtools import remove
+
+mappings = [
+    {'a': 1, 'b': 2, 'c': 3},
+    {'a': 4, 'b': 5, 'd': 6}
+]
+keys_to_remove = ['a', 'b']
+result = list(remove(keys_to_remove, *mappings))
+# result: [{'c': 3}, {'d': 6}]
+```
+
+#### `inverse`
+
+Swaps keys and values in a dictionary.
+
+<!-- name: test_inverse -->
+
+```python
+from mappingtools import inverse
+
+original_mapping = {'a': {1, 2}, 'b': {3}}
+inverted_mapping = inverse(original_mapping)
+print(inverted_mapping)
+# Output: defaultdict(<class 'set'>, {1: {'a'}, 2: {'a'}, 3: {'b'}})
+```
+
+#### `flattened`
+
+The flattened function takes a nested mapping structure and converts it into a single-level dictionary by flattening the
+keys into tuples.
+
+<!-- name: test_flattened -->
+
+```python
+from mappingtools import flattened
+
+nested_dict = {
+    'a': {'b': 1, 'c': {'d': 2}},
+    'e': 3
+}
+flat_dict = flattened(nested_dict)
+# Expected output: {('a', 'b'): 1, ('a', 'c', 'd'): 2, ('e',): 3}
+```
+
+#### `listify`
+
+Transforms complex objects into a list of dictionaries with key and value pairs.
+
+<!-- name: test_listify -->
+
+```python
+from mappingtools import listify
+
+wrapped_data = {'key1': {'subkey': 'value'}, 'key2': ['item1', 'item2']}
+unwrapped_data = listify(wrapped_data)
+print(unwrapped_data)
+# Output: [{'key': 'key1', 'value': [{'key': 'subkey', 'value': 'value'}]}, {'key': 'key2', 'value': ['item1', 'item2']}]
+```
+
+#### `simplify`
+
+Converts objects to strictly structured dictionaries.
+
+<!-- name: test_simplify -->
+
+```python
+from collections import Counter
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Mapping
+
+from mappingtools import simplify
+
+data = {'key1': 'value1', 'key2': ['item1', 'item2']}
+simplified_data = simplify(data)
+print(simplified_data)
+# Output: {'key1': 'value1', 'key2': ['item1', 'item2']}
+
+counter = Counter({'a': 1, 'b': 2})
+print(counter)
+# Output: Counter({'b': 2, 'a': 1})
+
+simplified_counter = simplify(counter)
+print(simplified_counter)
+
+
+# Output: {'a': 1, 'b': 2}
+
+
+@dataclass
+class SampleDataClass:
+    a: int
+    b: int
+    aa: str
+    bb: str
+    c: list[int]
+    d: Mapping
+    e: datetime
+
+
+sample_datetime = datetime(2024, 7, 22, 21, 42, 17, 314159)
+sample_dataclass = SampleDataClass(1, 2, '11', '22', [1, 2], {'aaa': 111, 'bbb': '222'}, sample_datetime)
+
+print(sample_dataclass)
+# Output: SampleDataClass(a=1, b=2, aa='11', bb='22', c=[1, 2], d={'aaa': 111, 'bbb': '222'}, e=datetime.datetime(2024, 7, 22, 21, 42, 17, 314159))
+
+simplified_sample_dataclass = simplify(sample_dataclass)
+print(simplified_sample_dataclass)
+# Output: {'a': 1, 'aa': '11', 'b': 2, 'bb': '22', 'c': [1, 2], 'd': {'aaa': 111, 'bbb': '222'}, 'e': datetime.datetime(2024, 7, 22, 21, 42, 17, 314159)}
+```
+
+#### `strictify`
+
+Applies a strict structural conversion to an object using optional converters for keys and values.
+
+<!-- name: test_strictify -->
+
+```python
+from mappingtools import strictify
+
+
+def uppercase_key(key):
+    return key.upper()
+
+
+def double_value(value):
+    return value * 2
+
+
+data = {'a': 1, 'b': 2}
+result = strictify(data, key_converter=uppercase_key, value_converter=double_value)
+print(result)
+# Output: {'A': 2, 'B': 4}
+```
+
+#### `stringify`
+
+Converts an object into a string representation by recursively processing it based on its type.
+
+<!-- Name: test_stringify -->
+
+```python
+from mappingtools import stringify
+
+data = {'key1': 'value1', 'key2': 'value2'}
+result = stringify(data)
+
+print(result)
+# Output: "key1=value1, key2=value2"
+
+data = [1, 2, 3]
+result = stringify(data)
+
+print(result)
+# Output: "[1, 2, 3]"
+```
+
+#### `stream`
+
+Takes a mapping and an optional item factory function, and generates items from the mapping.
+If the item factory is provided, it applies the factory to each key-value pair before yielding.
+
+<!-- name: test_stream -->
+
+```python
+from collections import namedtuple
+
+from mappingtools import stream
+
+
+def custom_factory(key, value):
+    return f"{key}: {value}"
+
+
+my_mapping = {'a': 1, 'b': 2, 'c': 3}
+
+for item in stream(my_mapping, custom_factory):
+    print(item)
+# Output:
+# a: 1
+# b: 2
+# c: 3
+
+
+MyTuple = namedtuple('MyTuple', ['key', 'value'])
+data = {'a': 1, 'b': 2}
+
+for item in stream(data, MyTuple):
+    print(item)
+
+
+# Output:
+# MyTuple(key='a', value=1)
+# MyTuple(key='b', value=2)
+
+
+def record(k, v):
+    return {'key': k, 'value': v}
+
+
+for item in stream(data, record):
+    print(item)
+# output:
+# {'key': 'a', 'value': 1}
+# {'key': 'b', 'value': 2}
+```
+
+#### `stream_dict_records`
+
+generates dictionary records from a given mapping, where each record contains a key-value pair from the mapping with
+customizable key and value names.
+
+<!-- name: test_stream_dict_records -->
+
+```python
+from mappingtools import stream_dict_records
+
+mapping = {'a': 1, 'b': 2}
+records = stream_dict_records(mapping, key_name='letter', value_name='number')
+for record in records:
+    print(record)
+# Output:
+# {'letter': 'a', 'number': 1}
+# {'letter': 'b', 'number': 2}
+```
+
+### Collectors
+
+#### `nested_defaultdict`
+
+Creates a nested defaultdict with specified depth and factory.
+
+<!-- name: test_nested_defaultdict -->
+
+```python
+from mappingtools import nested_defaultdict
+
+nested_dd = nested_defaultdict(1, list)
+nested_dd[0][1].append('value')
+print(nested_dd)
+# Output: defaultdict(<function nested_defaultdict.<locals>.factory at ...>, {0: defaultdict(<function nested_defaultdict.<locals>.factory at ...>, {1: ['value']})})
+```
+
+#### `CategoryCounter`
+
+The CategoryCounter class extends a dictionary to count occurrences of data items categorized by multiple categories.
+It maintains a total count of all data items and allows categorization using direct values or functions.
+
+<!-- name: test_category_counter -->
+
+```python
+from mappingtools import CategoryCounter
+
+counter = CategoryCounter()
+
+for fruit in ['apple', 'banana', 'apple']:
+    counter.update({fruit: 1}, type='fruit', char_count=len(fruit), unique_char_count=len(set(fruit)))
+
+print(counter.total)
+# Output: Counter({'apple': 2, 'banana': 1})
+
+print(counter)
+# Output: CategoryCounter({'type': defaultdict(<class 'collections.Counter'>, {'fruit': Counter({'apple': 2, 'banana': 1})}), 'char_count': defaultdict(<class 'collections.Counter'>, {5: Counter({'apple': 2}), 6: Counter({'banana': 1})}), 'unique_char_count': defaultdict(<class 'collections.Counter'>, {4: Counter({'apple': 2}), 3: Counter({'banana': 1})})})
+```
+
+#### `MappingCollector`
+
+A class designed to collect key-value pairs into an internal mapping based on different modes.
+It supports modes like ALL, COUNT, DISTINCT, FIRST, and LAST, each dictating how key-value pairs are
+collected.
+
+<!-- name: test_mapping_collector -->
+
+```python
+from mappingtools import MappingCollector, MappingCollectorMode
+
+collector = MappingCollector(MappingCollectorMode.ALL)
+collector.add('a', 1)
+collector.add('a', 2)
+collector.collect([('b', 3), ('b', 4)])
+print(collector.mapping)
+# Output: {'a': [1, 2], 'b': [3, 4]}
+```
+
+## Development
+
+### Ruff
+
+```shell
+ruff check src
+
+ruff check tests
+```
+
+### Test
+
+#### Standard (cobertura) XML Coverage Report
+
+```shell
+python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-report=xml
+```
+
+#### HTML Coverage Report
+
+```shell
+python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-report=html
+```

mappingtools-0.3.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+mappingtools.py,sha256=e1igUpsD30fOT4ZvCYv4ZeZP59TR8tEVjJgml5RqLr8,19026
+mappingtools-0.3.0.dist-info/METADATA,sha256=A25MAlpiPTEMb_AVxs5yrL4aKJN9iLre3aJ2O9CVu4s,15181
+mappingtools-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mappingtools-0.3.0.dist-info/licenses/LICENSE,sha256=fiCxD4qmBY6VdONaK43ANsvpmf9oxSpFLHaFaij0Jx4,1068
+mappingtools-0.3.0.dist-info/RECORD,,

mappingtools-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mappingtools-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Eran Rivlis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mappingtools.py

@@ -0,0 +1,538 @@
+import dataclasses
+import inspect
+from collections import Counter, defaultdict
+from collections.abc import Callable, Generator, Iterable, Mapping
+from enum import Enum, auto
+from itertools import chain
+from typing import Any, TypeVar
+
+CIRCULAR_REFERENCE = '...'
+
+K = TypeVar('K')
+KT = TypeVar('KT')
+VT = TypeVar('VT')
+VT_co = TypeVar('VT_co')
+
+Category = TypeVar('Category', bound=str | tuple | int | float)
+
+
+class CategoryCounter(dict[str, defaultdict[Category, Counter]]):
+
+    def __init__(self):
+        super().__init__()
+        self.total = Counter()
+
+    def __repr__(self):
+        return f"CategoryCounter({super().__repr__()})"
+
+    def update(self, data, **categories: Category | Callable[[Any], Category]):
+        """
+        Updates a CategoryCounter object with data and corresponding categories.
+
+        Parameters:
+            data: Any - The data to update the counter with (see Counter update method documentation).
+            **categories: Category | Callable[[Any], Category] - categories to associate the data with.
+                The categories can be either a direct value or a function that extracts the category from the data.
+
+        Returns:
+            None
+        """
+        self.total.update(data)
+        for category_name, category_value in categories.items():
+            category_value = category_value(data) if callable(category_value) else category_value
+            if category_name not in self:
+                self[category_name] = defaultdict(Counter)
+            self[category_name][category_value].update(data)
+
+
+class MappingCollectorMode(Enum):
+    """
+    Define an enumeration class for mapping collector modes.
+
+    Attributes:
+        ALL: Collect all values for each key.
+        COUNT: Count the occurrences of each value for each key.
+        DISTINCT: Collect distinct values for each key.
+        FIRST: Collect the first value for each key.
+        LAST: Collect the last value for each key.
+
+
+    """
+    ALL = auto()
+    COUNT = auto()
+    DISTINCT = auto()
+    FIRST = auto()
+    LAST = auto()
+
+
+class MappingCollector:
+
+    def __init__(self, mode: MappingCollectorMode = MappingCollectorMode.ALL, **kwargs):
+        """
+        Initialize the MappingCollector with the specified mode.
+
+        Args:
+            mode (MappingCollectorMode): The mode for collecting mappings.
+            *args: Variable positional arguments used to initialize the internal mapping.
+            **kwargs: Variable keyword arguments used to initialize the internal mapping.
+        """
+        self._mapping: Mapping[KT, VT_co]
+
+        self.mode = mode
+
+        match self.mode:
+            case MappingCollectorMode.ALL:
+                self._mapping = defaultdict(list, **kwargs)
+            case MappingCollectorMode.COUNT:
+                self._mapping = defaultdict(Counter, **kwargs)
+            case MappingCollectorMode.DISTINCT:
+                self._mapping = defaultdict(set, **kwargs)
+            case MappingCollectorMode.FIRST | MappingCollectorMode.LAST:
+                self._mapping = dict(**kwargs)
+            case _:
+                raise ValueError("Invalid mode")
+
+    def __repr__(self):
+        return f'MappingCollector(mode={self.mode}, mapping={self.mapping})'
+
+    @property
+    def mapping(self) -> Mapping[KT, VT_co]:
+        """
+        Return a shallow copy of the internal mapping.
+
+        Returns:
+            Mapping[KT, VT_co]: A shallow copy of the internal mapping.
+        """
+        return dict(self._mapping)
+
+    def add(self, key: KT, value: VT):
+        """
+        Add a key-value pair to the internal mapping based on the specified mode.
+
+        Args:
+            key: The key to be added to the mapping.
+            value: The value corresponding to the key.
+
+        Returns:
+            None
+        """
+        match self.mode:
+            case MappingCollectorMode.ALL:
+                self._mapping[key].append(value)
+            case MappingCollectorMode.COUNT:
+                self._mapping[key].update({value: 1})
+            case MappingCollectorMode.DISTINCT:
+                self._mapping[key].add(value)
+            case MappingCollectorMode.FIRST if key not in self.mapping:
+                self._mapping[key] = value
+            case MappingCollectorMode.LAST:
+                self._mapping[key] = value
+
+    def collect(self, iterable: Iterable[tuple[KT, VT]]):
+        """
+        Collect key-value pairs from the given iterable and add them to the internal mapping
+        based on the specified mode.
+
+        Args:
+            iterable (Iterable[tuple[KT, VT]]): An iterable containing key-value pairs to collect.
+
+        Returns:
+            None
+        """
+        for k, v in iterable:
+            self.add(k, v)
+
+
+def distinct(key: K, *mappings: Mapping[K, Any]) -> Generator[Any, Any, None]:
+    """
+    Yield distinct values for the specified key across multiple mappings.
+
+    Args:
+        key (K): The key to extract distinct values from the mappings.
+        *mappings (Mapping[K, Any]): Variable number of mappings to search for distinct values.
+
+    Yields:
+        Generator[K, Any, None]: A generator of distinct values extracted from the mappings.
+    """
+    distinct_value_type_pairs = set()
+    for mapping in mappings:
+        value = mapping.get(key, )
+        value_type_pair = (value, type(value))
+        if key in mapping and value_type_pair not in distinct_value_type_pairs:
+            distinct_value_type_pairs.add(value_type_pair)
+            yield value
+
+
+def _take(keys: Iterable[K], mapping: Mapping[K, Any], exclude: bool = False) -> dict[K, Any]:
+    """
+    Return a dictionary pertaining to the specified keys and their corresponding values from the mapping.
+
+    Args:
+        keys (Iterable[K]): The keys to include in the resulting dictionary.
+        mapping (Mapping[K, Any]): The mapping to extract key-value pairs from.
+        exclude (bool, optional): If True, exclude the specified keys from the mapping. Defaults to False.
+
+    Returns:
+        dict[K, Any]: A dictionary with the selected keys and their values from the mapping.
+    """
+
+    if not isinstance(mapping, Mapping):
+        raise TypeError(f"Parameter 'mapping' should be of type 'Mapping', but instead is type '{type(mapping)}'")
+
+    mapping_keys = set(mapping.keys())
+    keys = set(keys) & mapping_keys  # intersection with keys to get actual existing keys
+    if exclude:
+        keys = mapping_keys - keys
+
+    return {k: mapping.get(k) for k in keys}
+
+
+def keep(keys: Iterable[K], *mappings: Mapping[K, Any]) -> Generator[Mapping[K, Any], Any, None]:
+    """
+    Yield a subset of mappings by keeping only the specified keys.
+
+    Args:
+        keys (Iterable[K]): The keys to keep in the mappings.
+        *mappings (Mapping[K, Any]): Variable number of mappings to filter.
+
+    Yields:
+        Generator[Mapping[K, Any], Any, None]: A generator of mappings with only the specified keys.
+    """
+    yield from (_take(keys, mapping) for mapping in mappings)
+
+
+def remove(keys: Iterable[K], *mappings: Mapping[K, Any]) -> Generator[Mapping[K, Any], Any, None]:
+    """
+    Yield a subset of mappings by removing the specified keys.
+
+    Args:
+        keys (Iterable[K]): The keys to remove from the mappings.
+        *mappings (Mapping[K, Any]): Variable number of mappings to filter.
+
+    Yields:
+        Generator[Mapping[K, Any], Any, None]: A generator of mappings with specified keys removed.
+    """
+    yield from (_take(keys, mapping, exclude=True) for mapping in mappings)
+
+
+def inverse(mapping: Mapping[Any, set]) -> Mapping[Any, set]:
+    """
+    Return a new dictionary with keys and values swapped from the input mapping.
+
+    Args:
+        mapping (Mapping[Any, set]): The input mapping to invert.
+
+    Returns:
+        Mapping: A new Mapping with values as keys and keys as values.
+    """
+    items = chain.from_iterable(((vi, k) for vi in v) for k, v in mapping.items())
+    dd = defaultdict(set)
+    for k, v in items:
+        dd[k].add(v)
+
+    return dd
+
+
+def nested_defaultdict(nesting_depth: int = 0, default_factory: Callable | None = None, **kwargs) -> defaultdict:
+    """Return a nested defaultdict with the specified nesting depth and default factory.
+    A nested_defaultdict with nesting_depth=0 is equivalent to builtin 'collections.defaultdict'.
+    For each increment in nesting_depth an additional item accessor is added.
+
+    Args:
+        nesting_depth (int): The depth of nesting for the defaultdict (default is 0);
+        default_factory (Callable): The default factory function for the defaultdict (default is None).
+        **kwargs: Additional keyword arguments to initialize the most nested defaultdict.
+
+    Returns:
+        defaultdict: A nested defaultdict based on the specified parameters.
+    """
+
+    if nesting_depth < 0:
+        raise ValueError("'nesting_depth' must be zero or more.")
+
+    if default_factory is not None and not callable(default_factory):
+        raise TypeError("default_factory argument must be Callable or None")
+
+    def factory():
+        if nesting_depth > 0:
+            return nested_defaultdict(nesting_depth=nesting_depth - 1, default_factory=default_factory, **kwargs)
+        else:
+            return default_factory() if default_factory else None
+
+    return defaultdict(factory, **kwargs)
+
+
+def flattened(mapping: Mapping[Any, Any]) -> dict[tuple, Any]:
+    """
+    Flatten a nested mapping structure into a single-level dictionary.
+
+    :param mapping: A nested mapping structure to be flattened.
+    :return: A dictionary representing the flattened structure.
+    """
+
+    def flatten(key: tuple, value: Any):
+        if isinstance(value, Mapping):
+            for k, v in value.items():
+                new_key = tuple([*key, *k] if _is_strict_iterable(k) else [*key, k])
+                yield from flatten(new_key, v)
+        else:
+            yield key, value
+
+    return dict(flatten((), mapping))
+
+
+def _is_strict_iterable(obj: Iterable) -> bool:
+    return isinstance(obj, Iterable) and not isinstance(obj, str | bytes | bytearray)
+
+
+def _is_class_instance(obj) -> bool:
+    return (dataclasses.is_dataclass(obj) and not isinstance(obj, type)) or hasattr(obj, '__dict__')
+
+
+def _class_generator(obj):
+    yield from ((k, v) for k, v in inspect.getmembers(obj) if not k.startswith('_'))
+
+
+class Processor:
+    """
+    A class to process objects recursively based on their type.
+    """
+
+    def __init__(self,
+                 mapping_handler: Callable | None = None,
+                 iterable_handler: Callable | None = None,
+                 class_handler: Callable | None = None,
+                 default_handler: Callable | None = None,
+                 *args,
+                 **kwargs):
+        """
+        Initialize the Processor with optional handlers for different types of objects.
+
+        Args:
+            mapping_handler (Optional[Callable]): Handler for mapping objects.
+            Iterable_handler (Optional[Callable]): Handler for iterable objects.
+            Class_handler (Optional[Callable]): Handler for class instances.
+            Default_handler (Optional[Callable]): Default handler for other objects.
+            *args: Additional positional arguments for handlers.
+            **kwargs: Additional keyword arguments for handlers.
+        """
+
+        self.mapping_handler = mapping_handler
+        self.iterable_handler = iterable_handler
+        self.class_handler = class_handler
+        self.default_handler = default_handler
+        self.args = args
+        self.kwargs = kwargs
+
+        self.objects_counter = Counter()
+        self.objects = {}
+
+    def __call__(self, obj: Any):
+        """
+           Process the given object using the appropriate handler.
+
+           Args:
+               obj (Any): The object to process.
+
+           Returns:
+               Any: The processed object.
+           """
+        obj_id = id(obj)
+        self.objects_counter[obj_id] += 1
+        if self.objects_counter[obj_id] == 1:
+            processed_obj = self._process(obj)
+            self.objects[obj_id] = processed_obj
+            return self.objects[obj_id]
+        elif self.objects_counter[obj_id] == 2:
+            return self.objects.get(obj_id, CIRCULAR_REFERENCE)
+
+    def _process(self, obj: Any):
+        if callable(self.mapping_handler) and isinstance(obj, Mapping):
+            return self.mapping_handler(obj, self, *self.args, **self.kwargs)
+        elif callable(self.iterable_handler) and _is_strict_iterable(obj):
+            return self.iterable_handler(obj, self, *self.args, **self.kwargs)
+        elif callable(self.class_handler) and _is_class_instance(obj):
+            return self.class_handler(obj, self, *self.args, **self.kwargs)
+        elif callable(self.default_handler):
+            self.objects_counter.pop(id(obj))
+            return self.default_handler(obj)
+        else:
+            self.objects_counter.pop(id(obj))
+            return obj
+
+
+def _strictify_mapping(obj, processor, key_converter, value_converter):
+    return {
+        (key_converter(k) if key_converter else k): processor(value_converter(v) if value_converter else v)
+        for k, v in obj.items()}
+
+
+def _strictify_iterable(obj, processor, key_converter, value_converter):
+    return [processor(value_converter(v) if value_converter else v) for v in obj]
+
+
+def _strictify_class(obj, processor, key_converter, value_converter):
+    return {
+        (key_converter(k) if key_converter else k): processor(value_converter(v) if value_converter else v)
+        for k, v in _class_generator(obj)
+    }
+
+
+def strictify(obj: Any,
+              key_converter: Callable[[Any], str] | None = None,
+              value_converter: Callable[[Any], Any] | None = None) -> Any:
+    """Applies strict structural conversion to the given object using optional specific converters for keys and values.
+
+       Args:
+           obj: The object to be converted.
+           key_converter: A function to convert keys (optional).
+           value_converter: A function to convert values (optional).
+
+       Returns:
+           The object content after applying the conversion.
+       """
+
+    processor = Processor(mapping_handler=_strictify_mapping,
+                          iterable_handler=_strictify_iterable,
+                          class_handler=_strictify_class,
+                          key_converter=key_converter,
+                          value_converter=value_converter)
+
+    return processor(obj)
+
+
+def _listify_mapping(obj: Mapping, processor, key_name, value_name) -> list[dict]:
+    return [{key_name: k, value_name: processor(v)} for k, v in obj.items()]
+
+
+def _listify_iterable(obj: Iterable, processor, key_name, value_name) -> list:
+    return [processor(v) for v in obj]
+
+
+def _listify_class(obj, processor, key_name, value_name):
+    return [{key_name: k, value_name: processor(v)} for k, v in inspect.getmembers(obj) if not k.startswith('_')]
+
+
+def listify(obj: Any, key_name: str = 'key', value_name: str = 'value') -> Any:
+    """
+    listify recursively the given object.
+
+    Args:
+        obj (Any): The object to unwrap.
+        key_name(str): The key field name.
+        value_name(str): The value field name.
+
+    Returns:
+        Any: The unwrapped object.
+    """
+
+    processor = Processor(mapping_handler=_listify_mapping,
+                          iterable_handler=_listify_iterable,
+                          class_handler=_listify_class,
+                          key_name=key_name,
+                          value_name=value_name)
+
+    return processor(obj)
+
+
+def simplify(obj: Any) -> Any:
+    """Dictify recursively the given object.
+
+    Args:
+        obj (Any): The object to be simplified.
+
+    Returns:
+        The simplified object.
+    """
+    return strictify(obj, key_converter=str)
+
+
+def _stringify_kv_stream(iterable: Iterable[tuple[Any, Any]],
+                         processor,
+                         kv_delimiter,
+                         item_delimiter,
+                         key_converter,
+                         *args,
+                         **kwargs):
+    items = (f"{key_converter(k)}{kv_delimiter}{processor(v)}" for k, v in iterable)
+    return item_delimiter.join(items)
+
+
+def _stringify_mapping(obj, *args, **kwargs):
+    return _stringify_kv_stream(obj.items(), *args, **kwargs)
+
+
+def _stringify_iterable(obj, processor, kv_delimiter, item_delimiter, *args, **kwargs):
+    return f'[{item_delimiter.join(processor(v) for v in obj)}]'
+
+
+def _stringify_class(obj, processor, kv_delimiter, item_delimiter, *args, **kwargs):
+    return _stringify_kv_stream(_class_generator(obj), processor, kv_delimiter, item_delimiter, *args, **kwargs)
+
+
+def stringify(obj: Any, kv_delimiter: str = '=', item_delimiter: str = ', ') -> str:
+    """Stringify recursively the given object.
+
+    Args:
+        obj (Any): The object to be stringified.
+        kv_delimiter (str): The key-value delimiter. Defaults to '='.
+        item_delimiter (str): The item delimiter. Defaults to ', '.
+
+    Returns:
+        str: The stringified object.
+    """
+
+    processor = Processor(mapping_handler=_stringify_mapping,
+                          iterable_handler=_stringify_iterable,
+                          class_handler=_stringify_class,
+                          default_handler=str,
+                          kv_delimiter=kv_delimiter,
+                          item_delimiter=item_delimiter,
+                          key_converter=str)
+
+    return processor(obj)
+
+
+def stream(mapping: Mapping, item_factory: Callable[[Any, Any], Any] | None = None) -> Generator[Any, Any, None]:
+    """
+    Generate a stream of items from a mapping.
+
+    Args:
+        mapping (Mapping): The mapping object to stream items from.
+        item_factory (Callable[[Any, Any], Any], optional): A function that transforms each key-value pair from
+            the mapping. Defaults to None.
+
+    Yields:
+        The streamed items from the mapping.
+    """
+
+    items = mapping.items() if item_factory is None else iter(item_factory(k, v) for k, v in mapping.items())
+    yield from items
+
+
+def stream_dict_records(mapping: Mapping,
+                        key_name: str = 'key',
+                        value_name: str = 'value') -> Generator[Mapping[str, Any], Any, None]:
+    """
+    Generate dictionary records from a mapping.
+
+    Args:
+        mapping (Mapping): The input mapping to generate records from.
+        key_name (str): The name to use for the key in the generated records. Defaults to 'key'.
+        value_name (str): The name to use for the value in the generated records. Defaults to 'value'.
+
+    Yields:
+        dictionary records based on the input mapping.
+    """
+
+    def record(k, v):
+        return {key_name: k, value_name: v}
+
+    yield from stream(mapping, record)
+
+
+__all__ = (
+    'Category', 'CategoryCounter', 'MappingCollector', 'MappingCollectorMode', 'distinct', 'flattened', 'inverse',
+    'keep', 'listify', 'nested_defaultdict', 'remove', 'simplify', 'stream', 'stream_dict_records', 'strictify',
+    'stringify'
+)