mappingtools 0.2.2__tar.gz → 0.3.1__tar.gz

{mappingtools-0.2.2 → mappingtools-0.3.1}/.github/workflows/test-beta.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false
       matrix:
         # https://github.com/actions/python-versions/blob/main/versions-manifest.json
-        python-version: [ "3.14.0-alpha.1" ]
+        python-version: [ "3.14.0-alpha.4" ]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}

{mappingtools-0.2.2 → mappingtools-0.3.1}/.gitignore

@@ -884,3 +884,5 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
+
+.qodo

{mappingtools-0.2.2 → mappingtools-0.3.1}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: mappingtools
-Version: 0.2.2
-Summary: MappingTools. Do stuff with Mappings
+Version: 0.3.1
+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
@@ -43,6 +43,10 @@ Description-Content-Type: text/markdown
 
 # MappingTools
 
+> Do stuff with Mappings and more!!!
+
+## Introdcution
+
 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.
@@ -95,13 +99,79 @@ nested defaultdicts, and unwrapping complex objects.
       <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>
+      <br>
+      <a href="https://www.codefactor.io/repository/github/erivlis/mappingtools/overview/main"><img src="https://www.codefactor.io/repository/github/erivlis/mappingtools/badge/main" alt="CodeFactor" /></a>
+      <br>
+      <a href="https://snyk.io/test/github/erivlis/mappingtools"><img alt="Snyk" src="https://snyk.io/test/github/erivlis/mappingtools/badge.svg"></a>
     </td>
   </tr>
 </table>
 
 ## Usage
 
-### Transformers
+### Collectors
+
+Collectors are classes that collect data items into a Mapping.
+
+#### `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.collectors 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.collectors 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]}
+```
+
+#### `nested_defaultdict`
+
+Creates a nested defaultdict with specified depth and factory.
+
+<!-- name: test_nested_defaultdict -->
+
+```python
+from mappingtools.collectors 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']})})
+```
+
+### Operators
+
+Operators are functions that perform operations on Mappings.
 
 #### `distinct`
 
@@ -110,7 +180,7 @@ Yields distinct values for a specified key across multiple mappings.
 <!-- name: test_distinct -->
 
 ```python
-from mappingtools import distinct
+from mappingtools.operators import distinct
 
 mappings = [
     {'a': 1, 'b': 2},
@@ -129,7 +199,7 @@ Yields subsets of mappings by retaining only the specified keys.
 <!-- name: test_keep -->
 
 ```python
-from mappingtools import keep
+from mappingtools.operators import keep
 
 mappings = [
     {'a': 1, 'b': 2, 'c': 3},
@@ -148,7 +218,7 @@ of mappings with those keys excluded.
 <!-- name: test_remove -->
 
 ```python
-from mappingtools import remove
+from mappingtools.operators import remove
 
 mappings = [
     {'a': 1, 'b': 2, 'c': 3},
@@ -166,7 +236,7 @@ Swaps keys and values in a dictionary.
 <!-- name: test_inverse -->
 
 ```python
-from mappingtools import inverse
+from mappingtools.operators import inverse
 
 original_mapping = {'a': {1, 2}, 'b': {3}}
 inverted_mapping = inverse(original_mapping)
@@ -182,7 +252,7 @@ keys into tuples.
 <!-- name: test_flattened -->
 
 ```python
-from mappingtools import flattened
+from mappingtools.operators import flattened
 
 nested_dict = {
     'a': {'b': 1, 'c': {'d': 2}},
@@ -192,97 +262,6 @@ flat_dict = flattened(nested_dict)
 # Expected output: {('a', 'b'): 1, ('a', 'c', 'd'): 2, ('e',): 3}
 ```
 
-#### `strictify`
-
-Strictify function 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}
-```
-
-#### `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)}
-```
-
-#### `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']}]
-```
-
 #### `stream`
 
 Takes a mapping and an optional item factory function, and generates items from the mapping.
@@ -293,7 +272,7 @@ If the item factory is provided, it applies the factory to each key-value pair b
 ```python
 from collections import namedtuple
 
-from mappingtools import stream
+from mappingtools.operators import stream
 
 
 def custom_factory(key, value):
@@ -341,7 +320,7 @@ customizable key and value names.
 <!-- name: test_stream_dict_records -->
 
 ```python
-from mappingtools import stream_dict_records
+from mappingtools.operators import stream_dict_records
 
 mapping = {'a': 1, 'b': 2}
 records = stream_dict_records(mapping, key_name='letter', value_name='number')
@@ -352,62 +331,121 @@ for record in records:
 # {'letter': 'b', 'number': 2}
 ```
 
-### Collectors
+### Transformers
 
-#### `nested_defaultdict`
+Transformers are functions that reshape an object, while maintaining the consistency of the structure.
 
-Creates a nested defaultdict with specified depth and factory.
+#### `listify`
 
-<!-- name: test_nested_defaultdict -->
+Transforms complex objects into a list of dictionaries with key and value pairs.
+
+<!-- name: test_listify -->
 
 ```python
-from mappingtools import nested_defaultdict
+from mappingtools.transformers import listify
 
-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']})})
+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']}]
 ```
 
-#### `CategoryCounter`
+#### `simplify`
 
-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.
+Converts objects to strictly structured dictionaries.
 
-<!-- name: test_category_counter -->
+<!-- name: test_simplify -->
 
 ```python
-from mappingtools import CategoryCounter
-
-counter = CategoryCounter()
+from collections import Counter
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Mapping
 
-for fruit in ['apple', 'banana', 'apple']:
-    counter.update({fruit: 1}, type='fruit', char_count=len(fruit), unique_char_count=len(set(fruit)))
+from mappingtools.transformers import simplify
 
-print(counter.total)
-# Output: Counter({'apple': 2, 'banana': 1})
+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: 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})})})
+# 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)}
 ```
 
-#### `MappingCollector`
+#### `strictify`
 
-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.
+Applies a strict structural conversion to an object using optional converters for keys and values.
 
-<!-- name: test_mapping_collector -->
+<!-- name: test_strictify -->
 
 ```python
-from mappingtools import MappingCollector, MappingCollectorMode
+from mappingtools.transformers import strictify
 
-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]}
+
+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.transformers 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]"
 ```
 
 ## Development
@@ -416,6 +454,8 @@ print(collector.mapping)
 
 ```shell
 ruff check src
+
+ruff check tests
 ```
 
 ### Test
@@ -430,4 +470,4 @@ python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-re
 
 ```shell
 python -m pytest tests -n auto --cov=src --cov-branch --doctest-modules --cov-report=html
-```
+```