Metadata-Version: 2.4
Name: mappingtools
Version: 0.8.0
Summary: MappingTools. Do stuff with Mappings and more
Project-URL: Homepage, https://erivlis.github.io/mappingtools
Project-URL: Documentation, https://erivlis.github.io/mappingtools/README.md
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 :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: deprecated>=1.3.1; python_version < '3.13'
Description-Content-Type: text/markdown

# MappingTools

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 7.650000095367432 588.7000122070312 52.619998931884766" data-asc="0.99" width="588.7000122070312" height="52.619998931884766"><defs/><g fill="#8000ff"><g transform="translate(0, 0)"><path d="M17.20 7.65L17.20 11.77Q15.50 11.77 14.16 12.10Q12.83 12.42 12.11 13.23Q11.40 14.02 11.55 15.45L12.47 24.63Q12.72 26.97 12.09 28.49Q11.45 30 10.05 30.82Q8.65 31.65 6.63 32Q8.72 32.35 10.13 33.14Q11.53 33.92 12.13 35.42Q12.72 36.92 12.47 39.38L11.55 48.55Q11.40 49.98 12.11 50.79Q12.83 51.60 14.16 51.91Q15.50 52.23 17.20 52.23L17.20 56.35Q14.60 56.35 12.49 55.94Q10.38 55.52 8.91 54.58Q7.45 53.63 6.79 52.01Q6.13 50.40 6.38 48.02L7.30 39.40Q7.47 37.63 6.84 36.49Q6.20 35.35 4.55 34.80Q2.90 34.25 0 34.25L0 29.75Q2.88 29.75 4.54 29.21Q6.20 28.67 6.84 27.54Q7.47 26.40 7.30 24.63L6.38 16Q6.13 13.60 6.79 11.98Q7.45 10.35 8.91 9.41Q10.38 8.47 12.49 8.06Q14.60 7.65 17.20 7.65ZM37.13 25.88L36.30 12.50L42.40 12.50L41.55 25.88L37.13 25.88ZM77 22.40Q78.50 22.40 79.70 23.05Q80.90 23.70 81.59 25.32Q82.28 26.95 82.28 29.88L82.28 49.50L77.30 49.50L77.30 30.65Q77.30 28.57 77.01 27.67Q76.72 26.77 75.53 26.77Q74.58 26.77 73.60 27.36Q72.63 27.95 71.63 29.38L71.63 49.50L67.10 49.50L67.10 30.65Q67.10 28.57 66.81 27.67Q66.53 26.77 65.33 26.77Q64.35 26.77 63.39 27.36Q62.43 27.95 61.43 29.38L61.43 49.50L56.43 49.50L56.43 23.10L60.65 23.10L61.03 25.95Q62.15 24.38 63.48 23.39Q64.80 22.40 66.67 22.40Q68.17 22.40 69.40 23.15Q70.63 23.90 71.20 25.77Q72.30 24.27 73.70 23.34Q75.10 22.40 77 22.40ZM108.97 43.02Q108.97 44.58 109.45 45.29Q109.92 46 110.97 46.35L109.72 50.15Q107.77 49.92 106.38 49.08Q104.97 48.23 104.25 46.50Q102.80 48.33 100.57 49.25Q98.35 50.17 95.82 50.17Q91.82 50.17 89.49 47.91Q87.15 45.65 87.15 41.98Q87.15 37.80 90.40 35.55Q93.65 33.30 99.70 33.30L103.47 33.30L103.47 31.57Q103.47 29.02 101.94 27.90Q100.40 26.77 97.60 26.77Q96.30 26.77 94.45 27.11Q92.60 27.45 90.57 28.15L89.20 24.20Q91.67 23.27 94.05 22.84Q96.42 22.40 98.45 22.40Q103.75 22.40 106.36 24.75Q108.97 27.10 108.97 31.25L108.97 43.02M97.52 46.05Q99.22 46.05 100.85 45.15Q102.47 44.25 103.47 42.63L103.47 36.80L100.38 36.80Q96.42 36.80 94.72 38.11Q93.02 39.42 93.02 41.73Q93.02 43.83 94.16 44.94Q95.30 46.05 97.52 46.05ZM131.67 22.40Q135.18 22.40 137.28 24.11Q139.38 25.82 140.32 28.94Q141.28 32.05 141.28 36.25Q141.28 40.27 140.13 43.42Q138.97 46.58 136.71 48.38Q134.45 50.17 131.10 50.17Q126.95 50.17 124.40 47.25L124.40 59.65L118.80 60.27L118.80 23.10L123.67 23.10L124.02 26.50Q125.52 24.45 127.51 23.42Q129.50 22.40 131.67 22.40M130.13 26.72Q128.25 26.72 126.82 27.85Q125.40 28.97 124.40 30.50L124.40 42.85Q125.35 44.27 126.66 45.04Q127.97 45.80 129.63 45.80Q132.45 45.80 133.93 43.52Q135.40 41.25 135.40 36.27Q135.40 32.90 134.81 30.79Q134.22 28.67 133.06 27.70Q131.90 26.72 130.13 26.72ZM161.67 22.40Q165.18 22.40 167.28 24.11Q169.38 25.82 170.32 28.94Q171.28 32.05 171.28 36.25Q171.28 40.27 170.13 43.42Q168.97 46.58 166.71 48.38Q164.45 50.17 161.10 50.17Q156.95 50.17 154.40 47.25L154.40 59.65L148.80 60.27L148.80 23.10L153.67 23.10L154.03 26.50Q155.53 24.45 157.51 23.42Q159.50 22.40 161.67 22.40M160.13 26.72Q158.25 26.72 156.82 27.85Q155.40 28.97 154.40 30.50L154.40 42.85Q155.35 44.27 156.66 45.04Q157.97 45.80 159.63 45.80Q162.45 45.80 163.93 43.52Q165.40 41.25 165.40 36.27Q165.40 32.90 164.81 30.79Q164.22 28.67 163.06 27.70Q161.90 26.72 160.13 26.72ZM193.22 23.10L193.22 45.40L200.40 45.40L200.40 49.50L179.72 49.50L179.72 45.40L187.63 45.40L187.63 27.20L179.97 27.20L179.97 23.10L193.22 23.10M189.32 10.17Q190.97 10.17 191.99 11.17Q193 12.17 193 13.67Q193 15.17 191.99 16.20Q190.97 17.23 189.32 17.23Q187.72 17.23 186.70 16.20Q185.67 15.17 185.67 13.67Q185.67 12.17 186.70 11.17Q187.72 10.17 189.32 10.17ZM208.80 49.50L208.80 23.10L213.63 23.10L214.05 26.52Q215.70 24.50 217.95 23.45Q220.20 22.40 222.57 22.40Q226.28 22.40 228.11 24.46Q229.95 26.52 229.95 30.25L229.95 49.50L224.35 49.50L224.35 33.02Q224.35 30.72 224.07 29.32Q223.80 27.92 222.99 27.30Q222.17 26.67 220.57 26.67Q219.30 26.67 218.15 27.22Q217 27.77 216.05 28.66Q215.10 29.55 214.40 30.55L214.40 49.50L208.80 49.50ZM261.02 19.75L262.52 24.40Q260.95 24.92 259.06 25.10Q257.18 25.27 254.85 25.27Q257.23 26.32 258.43 27.96Q259.63 29.60 259.63 31.97Q259.63 34.55 258.38 36.58Q257.13 38.60 254.80 39.75Q252.47 40.90 249.22 40.90Q248.07 40.90 247.24 40.80Q246.40 40.70 245.60 40.48Q245.10 40.83 244.76 41.41Q244.42 42 244.42 42.65Q244.42 43.45 245.09 44.04Q245.75 44.63 247.72 44.63L252.32 44.63Q255.15 44.63 257.31 45.59Q259.48 46.55 260.71 48.21Q261.95 49.88 261.95 51.98Q261.95 55.92 258.55 58.10Q255.15 60.27 248.75 60.27Q244.22 60.27 241.65 59.35Q239.07 58.42 238.03 56.60Q236.97 54.77 236.97 52.13L242 52.13Q242 53.50 242.54 54.40Q243.07 55.30 244.55 55.75Q246.03 56.20 248.80 56.20Q251.57 56.20 253.21 55.74Q254.85 55.27 255.59 54.41Q256.32 53.55 256.32 52.35Q256.32 50.75 254.93 49.88Q253.53 49 251.17 49L246.65 49Q242.90 49 241.16 47.48Q239.42 45.95 239.42 43.92Q239.42 42.58 240.19 41.33Q240.95 40.08 242.38 39.15Q240 37.90 238.91 36.11Q237.82 34.33 237.82 31.77Q237.82 28.97 239.22 26.88Q240.63 24.77 243.11 23.60Q245.60 22.42 248.85 22.42Q252.03 22.42 254.15 22.09Q256.27 21.75 257.86 21.13Q259.45 20.50 261.02 19.75M248.90 26.27Q246.22 26.27 244.88 27.79Q243.53 29.30 243.53 31.72Q243.53 34.23 244.91 35.74Q246.30 37.25 248.97 37.25Q251.45 37.25 252.76 35.80Q254.07 34.35 254.07 31.68Q254.07 28.97 252.78 27.63Q251.47 26.27 248.90 26.27ZM277.13 25.88L276.30 12.50L282.40 12.50L281.55 25.88L277.13 25.88ZM304.83 45.65Q304.83 43.83 306.13 42.51Q307.43 41.20 309.33 41.20Q311.25 41.20 312.54 42.51Q313.83 43.83 313.83 45.65Q313.83 47.52 312.54 48.85Q311.25 50.17 309.33 50.17Q307.43 50.17 306.13 48.85Q304.83 47.52 304.83 45.65M304.83 27.90Q304.83 26.67 305.43 25.65Q306.03 24.63 307.05 24.02Q308.08 23.42 309.33 23.42Q311.25 23.42 312.54 24.74Q313.83 26.05 313.83 27.90Q313.83 29.75 312.54 31.09Q311.25 32.42 309.33 32.42Q307.43 32.42 306.13 31.09Q304.83 29.75 304.83 27.90ZM367.13 25.88L366.30 12.50L372.40 12.50L371.55 25.88L367.13 25.88ZM410.85 48.10Q409.40 49.02 407.38 49.60Q405.35 50.17 403.15 50.17Q398.55 50.17 396.16 47.79Q393.78 45.40 393.78 41.50L393.78 27.17L387.90 27.17L387.90 23.10L393.78 23.10L393.78 17.20L399.38 16.52L399.38 23.10L408.28 23.10L407.65 27.17L399.38 27.17L399.38 41.45Q399.38 43.58 400.44 44.61Q401.50 45.65 403.93 45.65Q405.38 45.65 406.60 45.30Q407.83 44.95 408.83 44.40L410.85 48.10ZM429.38 22.40Q433.25 22.40 435.90 24.13Q438.55 25.85 439.91 28.95Q441.28 32.05 441.28 36.25Q441.28 40.42 439.89 43.56Q438.50 46.70 435.84 48.44Q433.18 50.17 429.35 50.17Q425.53 50.17 422.86 48.49Q420.20 46.80 418.81 43.67Q417.43 40.55 417.43 36.30Q417.43 32.17 418.81 29.05Q420.20 25.92 422.88 24.16Q425.55 22.40 429.38 22.40M429.38 26.75Q426.35 26.75 424.83 29.06Q423.30 31.38 423.30 36.30Q423.30 41.20 424.81 43.52Q426.33 45.85 429.35 45.85Q432.38 45.85 433.89 43.52Q435.40 41.20 435.40 36.25Q435.40 31.38 433.90 29.06Q432.40 26.75 429.38 26.75ZM459.38 22.40Q463.25 22.40 465.90 24.13Q468.55 25.85 469.91 28.95Q471.28 32.05 471.28 36.25Q471.28 40.42 469.89 43.56Q468.50 46.70 465.84 48.44Q463.18 50.17 459.35 50.17Q455.53 50.17 452.86 48.49Q450.20 46.80 448.81 43.67Q447.43 40.55 447.43 36.30Q447.43 32.17 448.81 29.05Q450.20 25.92 452.88 24.16Q455.55 22.40 459.38 22.40M459.38 26.75Q456.35 26.75 454.83 29.06Q453.30 31.38 453.30 36.30Q453.30 41.20 454.81 43.52Q456.33 45.85 459.35 45.85Q462.38 45.85 463.89 43.52Q465.40 41.20 465.40 36.25Q465.40 31.38 463.90 29.06Q462.40 26.75 459.38 26.75ZM490.40 12.50L490.40 42.30Q490.40 44.13 491.51 44.89Q492.63 45.65 494.40 45.65Q495.55 45.65 496.58 45.40Q497.60 45.15 498.58 44.77L500 48.67Q498.83 49.27 497.11 49.73Q495.40 50.17 493.20 50.17Q489.23 50.17 487.01 47.94Q484.80 45.70 484.80 41.80L484.80 16.63L476.83 16.63L476.83 12.50L490.40 12.50ZM518.40 45.88Q521.02 45.88 522.58 44.94Q524.13 44 524.13 42.35Q524.13 41.27 523.68 40.51Q523.23 39.75 521.88 39.11Q520.52 38.48 517.77 37.77Q515.18 37.10 513.21 36.17Q511.25 35.25 510.18 33.77Q509.10 32.30 509.10 29.97Q509.10 27.70 510.38 26Q511.65 24.30 514.04 23.35Q516.43 22.40 519.65 22.40Q522.98 22.40 525.45 23.27Q527.93 24.15 529.68 25.45L527.33 28.97Q525.77 27.95 523.94 27.30Q522.10 26.65 519.80 26.65Q517.13 26.65 515.96 27.45Q514.80 28.25 514.80 29.57Q514.80 30.55 515.39 31.21Q515.98 31.88 517.43 32.44Q518.88 33 521.52 33.75Q524.10 34.45 526.01 35.40Q527.93 36.35 528.99 37.91Q530.05 39.48 530.05 41.98Q530.05 44.83 528.41 46.64Q526.77 48.45 524.11 49.31Q521.45 50.17 518.40 50.17Q514.73 50.17 512.05 49.11Q509.38 48.05 507.55 46.45L510.53 43.05Q512.08 44.30 514.08 45.09Q516.08 45.88 518.40 45.88ZM547.13 25.88L546.30 12.50L552.40 12.50L551.55 25.88L547.13 25.88ZM571.50 7.65Q574.10 7.65 576.21 8.06Q578.33 8.47 579.79 9.42Q581.25 10.38 581.93 11.99Q582.60 13.60 582.33 15.98L581.40 24.63Q581.23 26.40 581.94 27.54Q582.65 28.67 584.33 29.21Q586 29.75 588.70 29.75L588.70 34.25Q586 34.25 584.33 34.80Q582.65 35.35 581.94 36.49Q581.23 37.63 581.40 39.40L582.33 48Q582.58 50.40 581.91 52.02Q581.25 53.65 579.79 54.59Q578.33 55.52 576.21 55.94Q574.10 56.35 571.50 56.35L571.50 52.23Q573.20 52.23 574.54 51.91Q575.88 51.60 576.59 50.79Q577.30 49.98 577.15 48.55L576.23 39.38Q575.98 36.92 576.61 35.42Q577.25 33.92 578.73 33.14Q580.20 32.35 582.43 32.02Q580.20 31.68 578.73 30.84Q577.25 30 576.61 28.50Q575.98 27 576.23 24.63L577.15 15.45Q577.30 14.02 576.59 13.23Q575.88 12.42 574.55 12.10Q573.23 11.77 571.50 11.77L571.50 7.65Z"/></g></g></svg>

> 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" class="off-glb" loading="lazy" src="https://img.shields.io/pypi/v/mappingtools.svg?logo=pypi&logoColor=lightblue">
      <img alt="PyPI - Status" class="off-glb" loading="lazy" src="https://img.shields.io/pypi/status/mappingtools.svg?logo=pypi&logoColor=lightblue">
      <img alt="PyPI - Python Version" class="off-glb" loading="lazy" src="https://img.shields.io/pypi/pyversions/mappingtools.svg?logo=python&label=Python&logoColor=lightblue">
      <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dd/mappingtools.svg?logo=pypi&logoColor=lightblue">
      <img alt="Libraries.io SourceRank" src="https://img.shields.io/librariesio/sourcerank/pypi/mappingtools.svg?logo=Libraries.io&label=SourceRank">
    </td>
  </tr>
  <tr>
    <td>Code</td>
    <td>
      <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.svg?label=Size&logo=git">
      <img alt="GitHub last commit (by committer)" src="https://img.shields.io/github/last-commit/erivlis/mappingtools.svg?&logo=git">
      <a href="https://github.com/erivlis/mappingtools/graphs/contributors"><img alt="Contributors" src="https://img.shields.io/github/contributors/erivlis/mappingtools.svg?&logo=git"></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/uv"><img alt="uv" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" style="max-width:100%;"></a>
      <a href="https://github.com/astral-sh/ruff"><img  alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" 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-->
      <a href="https://hatch.pypa.io"><img alt="Hatch project" class="off-glb" loading="lazy" src="https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg"></a>
    </td>
  </tr>
  <tr>
    <td>CI/CD</td>
    <td>
      <a href="https://github.com/erivlis/mappingtools/actions/workflows/test.yml"><img alt="Test" src="https://github.com/erivlis/mappingtools/actions/workflows/test.yml/badge.svg"></a>
      <a href="https://github.com/erivlis/mappingtools/actions/workflows/publish.yml"><img alt="Publish" src="https://github.com/erivlis/mappingtools/actions/workflows/test-beta.yml/badge.svg"></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>
      <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>
      <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>
      <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>
      <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>
      <a href="https://app.deepsource.com/gh/erivlis/mappingtools/" target="_blank"><img alt="DeepSource" title="DeepSource" src="https://app.deepsource.com/gh/erivlis/mappingtools.svg/?label=active+issues&show_trend=true&token=5hN3svCsdJtdULGTc68MngKa"/></a>
      <a href="https://app.deepsource.com/gh/erivlis/mappingtools/" target="_blank"><img alt="DeepSource" title="DeepSource" src="https://app.deepsource.com/gh/erivlis/mappingtools.svg/?label=resolved+issues&show_trend=true&token=5hN3svCsdJtdULGTc68MngKa"/></a>
      <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>

## 🚀 Why use MappingTools?

Built for developers who need more than just standard dictionaries.

| Problem                 | Solution                                                                                             |
|:------------------------|:-----------------------------------------------------------------------------------------------------|
| **Deep JSON Diffing**   | Use `flattened()` to collapse nested JSON into single-layer paths for easy comparison.               |
| **Data Collisions**     | Use `inverse()` to swap keys/values without losing data (automatically creates sets for duplicates). |
| **Slow Config Loading** | Use `MeteredDict` to profile exactly how many times your app reads specific config keys.             |
| **Quick Serialization** | Use `simplify()` to instantly convert Dataclasses, DateTime, and custom objects into pure Dicts.     |

## Overview

The **_MappingTools_** library is organized into several namespaces, each containing specific functionalities for
manipulating and transforming data structures. Below is a brief description of the main namespaces within the library:

- **collectors** - This namespace contains classes and functions for collecting and categorizing data items into
  mappings.
    - **AutoMapper** - A Mapping-like class that automatically generates and assigns unique, minified strings values for
      any new keys accessed.
    - **CategoryCounter** - Extends a dictionary to count occurrences of data items categorized by multiple categories.
    - **MappingCollector** - Collects key-value pairs into an internal mapping based on different modes (ALL, COUNT,
      DISTINCT, FIRST, LAST).
    - **MeteredDict** - A dictionary that tracks changes made to it.
    - **nested_defaultdict** - Creates a nested `defaultdict` with specified depth and factory.
- **operators** - This namespace provides functions that perform operations on mappings.
    - **distinct** - Yields distinct values for a specified key across multiple mappings.
    - **flattened** - Converts a nested mapping structure into a single-level dictionary by flattening the keys into
      tuples.
    - **inverse** - generates an inverse Mapping by swapping keys and values.
    - **keep** - (Deprecated) Yields subsets of mappings by retaining the specified keys.
    - **remove** - (Deprecated) Yields subsets mappings with the specified keys removed.
    - **stream** - (Deprecated) Generates items from a mapping, optionally applying a factory function to each key-value pair.
    - **stream_dict_records** - (Deprecated) Generates dictionary records from a mapping with customizable key and value names.
- **transformers** - This namespace includes functions that reshape objects while maintaining the consistency of their
  structure.
    - **listify** - Transforms complex objects into a list of dictionaries with key and value pairs.
    - **minify** - The minify function is used to shorten the keys of an object using a specified alphabet.
    - **simplify** - Converts objects to strictly structured dictionaries.
    - **strictify** - Applies a strict structural conversion to an object using optional converters for keys and values.
    - **stringify** - Converts an object into a string representation by recursively processing it based on its type.

## Examples

### Collectors

Collectors are classes that collect data items into a Mapping.

#### AutoMapper

A Mapping that automatically generates and assigns unique, minified string values for any new keys accessed.
The values are generated using the specified alphabet.

<!-- name: test_auto_mapper -->

```python
from mappingtools.collectors import AutoMapper

auto_mapper = AutoMapper()
print(auto_mapper['example_key'])
print(auto_mapper['another_key'])
print(auto_mapper['example_key'])
auto_mapper
# output:
# 'A'
# 'B'
# 'A'
# AutoMapper({'example_key': 'A', 'another_key': 'B'})
greek_auto_mapper = AutoMapper(alphabet='αβγ')
print(greek_auto_mapper['first'])
print(greek_auto_mapper['second'])
print(greek_auto_mapper['first'])
print(greek_auto_mapper['third'])
print(greek_auto_mapper['fourth'])
print(greek_auto_mapper['fifth'])
greek_auto_mapper
# output:
# 'α'
# 'β'
# 'γ'
# 'αα'
# 'αβ'
# AutoMapper({'first': 'α', 'second': 'β', 'third': 'γ', 'fourth': 'αα', 'fifth': 'αβ'})
```

#### 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]}
```

#### MeteredDict

A dictionary that tracks changes made to it.

<!-- name: test_metered_dict -->

```python
from mappingtools.collectors import MeteredDict

metered_dict = MeteredDict()
metered_dict['a'] = 1
metered_dict['b'] = 2
_ = metered_dict['a']

metered_dict
# output: {'a': 1, 'b': 2}

metered_dict.summaries()
# output: {'a': {'get': {'count': 1, 'first': datetime.datetime(2025, 10, 26, 9, 3, 52, 347825, tzinfo=datetime.timezone.utc), 'last': datetime.datetime(2025, 10, 26, 9, 3, 52, 347825, tzinfo=datetime.timezone.utc), 'duration': datetime.timedelta(0), 'frequency': 0.0}, 'get_default': {'count': 0, 'first': None, 'last': None, 'duration': datetime.timedelta(0), 'frequency': 0.0}, 'set': {'count': 1, 'first': datetime.datetime(2025, 10, 26, 9, 3, 52, 347806, tzinfo=datetime.timezone.utc), 'last': datetime.datetime(2025, 10, 26, 9, 3, 52, 347806, tzinfo=datetime.timezone.utc), 'duration': datetime.timedelta(0), 'frequency': 0.0}, 'set_default': {'count': 0, 'first': None, 'last': None, 'duration': datetime.timedelta(0), 'frequency': 0.0}, 'pop': {'count': 0, 'first': None, 'last': None, 'duration': datetime.timedelta(0), 'frequency': 0.0}}, 'b': {'get': {'count': 0, 'first': None, 'last': None, 'duration': datetime.timedelta(0), 'frequency': 0.0}, 'get_default': {'count': 0, 'first': None, 'last': None, 'duration': datetime.timedelta(0), 'frequency': 0.0}, 'set': {'count': 1, 'first': datetime.datetime(2025, 10, 26, 9, 3, 52, 347820, tzinfo=datetime.timezone.utc), 'last': datetime.datetime(2025, 10, 26, 9, 3, 52, 347820, tzinfo=datetime.timezone.utc), 'duration': datetime.timedelta(0), 'frequency': 0.0}, 'set_default': {'count': 0, 'first': None, 'last': None, 'duration': datetime.timedelta(0), 'frequency': 0.0}, 'pop': {'count': 0, 'first': None, 'last': None, 'duration': datetime.timedelta(0), 'frequency': 0.0}}}
```

#### 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

Yields distinct values for a specified key across multiple mappings.

<!-- name: test_distinct -->

```python
from mappingtools.operators 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]
```

#### 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.operators import flatten

nested_dict = {
    'a': {'b': 1, 'c': {'d': 2}},
    'e': 3
}
flat_dict = flatten(nested_dict)
print(flat_dict)
# output: {('a', 'b'): 1, ('a', 'c', 'd'): 2, ('e',): 3}
```

#### inverse

Swaps keys and values in a dictionary.

<!-- name: test_inverse -->

```python
from mappingtools.operators 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'}})
```

#### keep
> [!WARNING]
> Deprecated since version 0.8.0. Use a generator expression with a dictionary comprehension instead. See docstring for an example.

Yields subsets of mappings by retaining only the specified keys.

<!-- name: test_keep -->

```python
from mappingtools.operators import keep

mappings = [
    {'a': 1, 'b': 2, 'c': 3},
    {'a': 4, 'b': 5, 'd': 6}
]
keys_to_keep = ['a', 'b']
output = list(keep(keys_to_keep, *mappings))
print(output)
# output: [{'a': 1, 'b': 2}, {'a': 4, 'b': 5}]
```

#### remove
> [!WARNING]
> Deprecated since version 0.8.0. Use a generator expression with a dictionary comprehension instead. See docstring for an example.

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.operators import remove

mappings = [
    {'a': 1, 'b': 2, 'c': 3},
    {'a': 4, 'b': 5, 'd': 6}
]
keys_to_remove = ['a', 'b']
output = list(remove(keys_to_remove, *mappings))
print(output)
# output: [{'c': 3}, {'d': 6}]
```

#### stream
> [!WARNING]
> Deprecated since version 0.8.0. Use `mapping.items()` or a generator comprehension instead. See docstring for an example.

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.operators 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
> [!WARNING]
> Deprecated since version 0.8.0. Use a generator expression with a dictionary literal instead. See docstring for an example.

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.operators 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}
```

### Transformers

Transformers are functions that reshape an object, while maintaining the consistency of the structure.

#### listify

Transforms complex objects into a list of dictionaries with key and value pairs.

<!-- name: test_listify -->

```python
from mappingtools.transformers 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']}]
```

#### minify

The minify function is used to shorten the keys of an object using a specified alphabet.
This function can be particularly useful for reducing the size of data structures, making
them more efficient for storage or transmission.

<!-- name: test_minify -->

```python
from mappingtools.transformers import minify

data = [
    {
        'first_name': 'John',
        'last_name': 'Doe',
        'age': 30,
        'address': {
            'street': '123 Main St',
            'city': 'New York',
            'state': 'CA'
        }
    },
    {
        'first_name': 'Jane',
        'last_name': 'Smith',
        'age': 25,
        'address': {
            'street': '456 Rodeo Dr',
            'city': 'Los Angeles',
            'state': 'CA'
        }
    }
]

# Minify the dictionary keys
minified_dict = minify(data)

print(minified_dict)
# [{'A': 'John', 'B': 'Doe', 'C': 30, 'D': {'E': '123 Main St', 'F': 'New York', 'G': 'CA'}}, {'A': 'Jane', 'B': 'Smith', 'C': 25, 'D': {'E': '456 Rodeo Dr', 'F': 'Los Angeles', 'G': 'CA'}}]
```

#### 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.transformers 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 -->

##### Example 1

```python
from mappingtools.transformers 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}
```

##### Example 2

```python
from mappingtools.transformers import strictify

data = [
    {
        'first_name': 'John',
        'last_name': 'Doe',
        'age': 30,
        'address': {
            'street': '123 Main St',
            'city': 'New York',
            'state': 'CA'
        }
    },
    {
        'first_name': 'Jane',
        'last_name': 'Smith',
        'age': 25,
        'address': {
            'street': '456 Rodeo Dr',
            'city': 'Los Angeles',
            'state': 'CA'
        }
    }
]


def key_converter(key):
    return key.replace('_', ' ').title().replace(' ', '')


result = strictify(data, key_converter=key_converter)
print(result)
# output: 
# [
#     {
#         'FirstName': 'John',
#         'LastName': 'Doe',
#         'Age': 30,
#         'Address': {
#             'Street': '123 Main St',
#             'City': 'New York',
#             'State': 'CA'
#         }
#     },
#     {
#         'FirstName': 'Jane',
#         'LastName': 'Smith',
#         'Age': 25,
#         'Address': {
#             'Street': '456 Rodeo Dr',
#             'City': 'Los Angeles',
#             'State': 'CA'
#         }
#     }
# ]
```

#### 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]"
```

## Compatibility

This project exposes `mappingtools._compat.UTC` as a stable UTC tzinfo object that works across Python versions. On
Python 3.11+ it maps to `datetime.UTC`; on earlier versions it maps to `datetime.timezone.utc`.

Use it in your code or tests when you need a timezone-aware UTC datetime:

```python
from mappingtools._compat import UTC
from datetime import datetime

dt = datetime.now(tz=UTC)
```

## Development

### Ruff

```shell
ruff check src

ruff check tests
```

### Test

#### Standard (cobertura) XML Coverage Report

```shell
python -m pytest tests --cov=src --cov-branch --doctest-modules --cov-report=xml
```

#### HTML Coverage Report

```shell
python -m pytest tests --cov=src --cov-branch --doctest-modules --cov-report=html
```
