mappingtools 0.0.1__py3-none-any.whl

mappingtools-0.0.1.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.3
+Name: mappingtools
+Version: 0.0.1
+Summary: mappingtools. Do stuff with Mappings
+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 :: 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
+
+> 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 Badge" src="https://app.codacy.com/project/badge/Grade/8b83a99f939b4883ae2f37d7ec3419d1"></a>
+    </td>
+  </tr>
+</table>
+
+## Usage
+
+### `dictify`
+
+Converts objects to dictionaries using handlers for mappings, iterables, and classes.
+
+```python
+from mappingtools import dictify
+
+data = {'key1': 'value1', 'key2': ['item1', 'item2']}
+dictified_data = dictify(data)
+print(dictified_data)
+# Output: {'key1': 'value1', 'key2': ['item1', 'item2']}
+```
+
+### `distinct`
+
+Yields distinct values for a specified key across multiple mappings.
+
+```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.
+
+```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}]
+```
+
+### `inverse`
+
+Swaps keys and values in a dictionary.
+
+```python
+from mappingtools import inverse
+
+original_mapping = {'a': {1, 2}, 'b': {3}}
+inverted_mapping = inverse(original_mapping)
+print(inverted_mapping)
+# Output: {1: 'a', 2: 'a', 3: 'b'}
+```
+
+### `nested_defaultdict`
+
+Creates a nested defaultdict with specified depth and factory.
+
+```python
+from mappingtools import nested_defaultdict
+
+nested_dd = nested_defaultdict(2, 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']})})
+```
+
+### `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.
+
+```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}]
+
+```
+
+### `unwrap`
+
+Transforms complex objects into a list of dictionaries with key and value pairs.
+
+```python
+from mappingtools import unwrap
+
+wrapped_data = {'key1': {'subkey': 'value'}, 'key2': ['item1', 'item2']}
+unwrapped_data = unwrap(wrapped_data)
+print(unwrapped_data)
+# Output: [{'key': 'key1', 'value': [{'key': 'subkey', 'value': 'value'}]}, {'key': 'key2', 'value': ['item1', 'item2']}]
+```
+
+## Development
+
+### Ruff
+
+```shell
+ruff check src
+```
+
+### Test
+
+#### Standard (cobertura) XML Coverage Report
+
+```shell
+ python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-report=xml --junitxml=test_results.xml
+```
+
+#### HTML Coverage Report
+
+```shell
+python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-report=html --junitxml=test_results.xml
+```

mappingtools-0.0.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+mappingtools.py,sha256=I7O2lKPXVW3D7spmfPJRH5rw0Bh21Al4HScaeX0TlCE,6973
+mappingtools-0.0.1.dist-info/METADATA,sha256=mNuu4Re_ncNPgnnwt5Nw52R0lGhpce5IPqTxirbHDkM,9418
+mappingtools-0.0.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+mappingtools-0.0.1.dist-info/licenses/LICENSE,sha256=fiCxD4qmBY6VdONaK43ANsvpmf9oxSpFLHaFaij0Jx4,1068
+mappingtools-0.0.1.dist-info/RECORD,,

mappingtools-0.0.1.dist-info/WHEEL

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

mappingtools-0.0.1.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,197 @@
+import dataclasses
+import inspect
+from collections import defaultdict
+from collections.abc import Callable, Generator, Iterable, Mapping
+from itertools import chain
+from typing import Any, TypeVar
+
+K = TypeVar("K")
+
+
+def _take(keys: Iterable[K], mapping: Mapping[K, Any], exclude: bool = False) -> dict[K, Any]:
+    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 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 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 _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 _process_obj(obj: Any,
+                 mapping_handler: Callable | None = None,
+                 iterable_handler: Callable | None = None,
+                 class_handler: Callable | None = None,
+                 *args,
+                 **kwargs):
+    if callable(mapping_handler) and isinstance(obj, Mapping):
+        return mapping_handler(obj, *args, **kwargs)
+    elif callable(iterable_handler) and _is_strict_iterable(obj):
+        return iterable_handler(obj, *args, **kwargs)
+    elif callable(class_handler) and _is_class_instance(obj):
+        return class_handler(obj, *args, **kwargs)
+    else:
+        return obj
+
+
+def dictify(obj, key_converter: Callable[[Any], str] | None = None):
+    """Dictify an object using a specified key converter.
+
+    Args:
+        obj (Any): The object to be dictified.
+        key_converter (Optional[Callable[[Any], str]], optional): A function to convert keys. Defaults to None.
+
+    Returns:
+        The dictified object.
+    """
+    return _process_obj(obj, _dictify_mapping, _dictify_iterable, _dictify_class, key_converter=key_converter)
+
+
+def _dictify_mapping(obj, key_converter: Callable[[Any], str] | None = None) -> dict:
+    return {(key_converter(k) if key_converter else k): dictify(v, key_converter) for k, v in obj.items()}
+
+
+def _dictify_iterable(obj, key_converter: Callable[[Any], str] | None = None) -> list:
+    return [dictify(v, key_converter) for v in obj]
+
+
+def _dictify_class(obj, key_converter: Callable[[Any], str] | None = None) -> dict | str:
+    return {
+        (key_converter(k) if key_converter else k): dictify(v, key_converter)
+        for k, v in inspect.getmembers(obj)
+        if not k.startswith('_')
+    }
+
+
+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'.
+    Each nesting_depth increment effectively adds an additional item accessor.
+
+    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:
+            print(1)
+            return nested_defaultdict(nesting_depth=nesting_depth - 1, default_factory=default_factory, **kwargs)
+        else:
+            print(2)
+            return default_factory() if default_factory else None
+
+    return defaultdict(factory, **kwargs)
+
+
+def unwrap(obj: Any):
+    """
+    Unwraps the given object.
+
+    Args:
+        obj (Any): The object to unwrap.
+
+    Returns:
+        Any: The unwrapped object.
+    """
+    return _process_obj(obj, _unwrap_mapping, _unwrap_iterable, _unwrap_class)
+
+
+def _unwrap_mapping(obj: Mapping) -> list[dict]:
+    return [{'key': k, 'value': unwrap(v)} for k, v in obj.items()]
+
+
+def _unwrap_iterable(obj: Iterable) -> list:
+    return [unwrap(v) for v in obj]
+
+
+def _unwrap_class(obj):
+    return [{'key': k, 'value': unwrap(v)} for k, v in inspect.getmembers(obj) if not k.startswith('_')]
+
+
+__all__ = ('dictify', 'distinct', 'keep', 'inverse', 'nested_defaultdict', 'remove', 'unwrap')