flatten-dict 0.5.0__py3-none-any.whl

flatten_dict/__init__.py

@@ -0,0 +1,7 @@
+from importlib.metadata import version
+
+from .flatten_dict import flatten, unflatten  # noqa: F401
+
+__all__ = ["flatten", "unflatten", "splitter"]
+
+__version__ = version("flatten-dict")

flatten_dict/flatten_dict.py

@@ -0,0 +1,167 @@
+import inspect
+from collections.abc import Mapping
+
+from .reducers import dot_reducer, path_reducer, tuple_reducer, underscore_reducer
+from .splitters import dot_splitter, path_splitter, tuple_splitter, underscore_splitter
+
+REDUCER_DICT = {
+    "tuple": tuple_reducer,
+    "path": path_reducer,
+    "dot": dot_reducer,
+    "underscore": underscore_reducer,
+}
+
+SPLITTER_DICT = {
+    "tuple": tuple_splitter,
+    "path": path_splitter,
+    "dot": dot_splitter,
+    "underscore": underscore_splitter,
+}
+
+
+def flatten(
+    d,
+    reducer="tuple",
+    inverse=False,
+    max_flatten_depth=None,
+    enumerate_types=(),
+    keep_empty_types=(),
+):
+    """Flatten `Mapping` object.
+
+    Parameters
+    ----------
+    d : dict-like object
+        The dict that will be flattened.
+    reducer : {'tuple', 'path', 'underscore', 'dot', Callable}
+        The key joining method. If a `Callable` is given, the `Callable` will be
+        used to reduce.
+        'tuple': The resulting key will be tuple of the original keys.
+        'path': Use `os.path.join` to join keys.
+        'underscore': Use underscores to join keys.
+        'dot': Use dots to join keys.
+    inverse : bool
+        Whether you want invert the resulting key and value.
+    max_flatten_depth : Optional[int]
+        Maximum depth to merge.
+    enumerate_types : Sequence[type]
+        Flatten these types using `enumerate`.
+        For example, if we set `enumerate_types` to ``(list,)``,
+        `list` indices become keys: ``{'a': ['b', 'c']}`` -> ``{('a', 0): 'b', ('a', 1): 'c'}``.
+    keep_empty_types : Sequence[type]
+        By default, ``flatten({1: 2, 3: {}})`` will give you ``{(1,): 2}``, that is, the key ``3``
+        will disappear.
+        This is also applied for the types in `enumerate_types`, that is,
+        ``flatten({1: 2, 3: []}, enumerate_types=(list,))`` will give you ``{(1,): 2}``.
+        If you want to keep those empty values, you can specify the types in `keep_empty_types`:
+
+        >>> flatten({1: 2, 3: {}}, keep_empty_types=(dict,))
+        {(1,): 2, (3,): {}}
+
+    Returns
+    -------
+    flat_dict : dict
+    """
+    enumerate_types = tuple(enumerate_types)
+    flattenable_types = (Mapping,) + enumerate_types
+    if not isinstance(d, flattenable_types):
+        raise ValueError(
+            "argument type %s is not in the flattenalbe types %s"
+            % (type(d), flattenable_types)
+        )
+
+    # check max_flatten_depth
+    if max_flatten_depth is not None and max_flatten_depth < 1:
+        raise ValueError("max_flatten_depth should not be less than 1.")
+
+    if isinstance(reducer, str):
+        reducer = REDUCER_DICT[reducer]
+    reducer_accepts_parent_obj = len(inspect.signature(reducer).parameters) == 3
+    flat_dict = {}
+
+    def _flatten(_d, depth, parent=None):
+        key_value_iterable = (
+            enumerate(_d) if isinstance(_d, enumerate_types) else _d.items()
+        )
+        has_item = False
+        for key, value in key_value_iterable:
+            has_item = True
+            if reducer_accepts_parent_obj:
+                flat_key = reducer(parent, key, _d)
+            else:
+                flat_key = reducer(parent, key)
+            if isinstance(value, flattenable_types) and (
+                max_flatten_depth is None or depth < max_flatten_depth
+            ):
+                # recursively build the result
+                has_child = _flatten(value, depth=depth + 1, parent=flat_key)
+                if has_child or not isinstance(value, keep_empty_types):
+                    # ignore the key in this level because it already has child key
+                    # or its value is empty
+                    continue
+
+            # add an item to the result
+            if inverse:
+                flat_key, value = value, flat_key
+            if flat_key in flat_dict:
+                raise ValueError("duplicated key '{}'".format(flat_key))
+            flat_dict[flat_key] = value
+
+        return has_item
+
+    _flatten(d, depth=1)
+    return flat_dict
+
+
+def nested_set_dict(d, keys, value):
+    """Set a value to a sequence of nested keys.
+
+    Parameters
+    ----------
+    d : Mapping
+    keys : Sequence[str]
+    value : Any
+    """
+    assert keys
+    key = keys[0]
+    if len(keys) == 1:
+        if key in d:
+            raise ValueError("duplicated key '{}'".format(key))
+        d[key] = value
+        return
+    d = d.setdefault(key, {})
+    nested_set_dict(d, keys[1:], value)
+
+
+def unflatten(d, splitter="tuple", inverse=False):
+    """Unflatten dict-like object.
+
+    Parameters
+    ----------
+    d : dict-like object
+        The dict that will be unflattened.
+    splitter : {'tuple', 'path', 'underscore', 'dot', Callable}
+        The key splitting method. If a Callable is given, the Callable will be
+        used to split `d`.
+        'tuple': Use each element in the tuple key as the key of the unflattened dict.
+        'path': Use `pathlib.Path.parts` to split keys.
+        'underscore': Use underscores to split keys.
+        'dot': Use dots to split keys.
+    inverse : bool
+        Whether you want to invert the key and value before flattening.
+
+    Returns
+    -------
+    unflattened_dict : dict
+    """
+    if isinstance(splitter, str):
+        splitter = SPLITTER_DICT[splitter]
+
+    unflattened_dict = {}
+    for flat_key, value in d.items():
+        if inverse:
+            flat_key, value = value, flat_key
+        key_tuple = splitter(flat_key)
+        nested_set_dict(unflattened_dict, key_tuple, value)
+
+    return unflattened_dict

flatten_dict/reducer.py

@@ -0,0 +1,11 @@
+"""`flatten_dict.reducer` is deprecated in favor of `flatten_dict.reducers`."""
+
+import warnings
+
+from .reducers import *  # noqa: F401, F403
+
+warnings.warn(
+    "`flatten_dict.reducer` is deprecated in favor of `flatten_dict.reducers`.",
+    FutureWarning,
+    stacklevel=2,
+)

flatten_dict/reducers.py

@@ -0,0 +1,46 @@
+def tuple_reducer(k1, k2):
+    if k1 is None:
+        return (k2,)
+    return k1 + (k2,)
+
+
+def path_reducer(k1, k2):
+    import os.path
+
+    if k1 is None:
+        return k2
+    return os.path.join(k1, k2)
+
+
+def dot_reducer(k1, k2):
+    if k1 is None:
+        return k2
+    return "{}.{}".format(k1, k2)
+
+
+def underscore_reducer(k1, k2):
+    if k1 is None:
+        return k2
+    return "{}_{}".format(k1, k2)
+
+
+def make_reducer(delimiter):
+    """Create a reducer with a custom delimiter.
+
+    Parameters
+    ----------
+    delimiter : str
+        Delimiter to use to join keys.
+
+    Returns
+    -------
+    f : Callable
+        Callable that can be passed to `flatten()`'s `reducer` argument.
+    """
+
+    def f(k1, k2):
+        if k1 is None:
+            return k2
+        return "{}{}{}".format(k1, delimiter, k2)
+
+    return f

flatten_dict/splitter.py

@@ -0,0 +1,11 @@
+"""`flatten_dict.splitter` is deprecated in favor of `flatten_dict.splitters`."""
+
+import warnings
+
+from .splitters import *  # noqa: F401, F403
+
+warnings.warn(
+    "`flatten_dict.splitter` is deprecated in favor of `flatten_dict.splitters`.",
+    FutureWarning,
+    stacklevel=2,
+)

flatten_dict/splitters.py

@@ -0,0 +1,40 @@
+def tuple_splitter(flat_key):
+    return flat_key
+
+
+def path_splitter(flat_key):
+    from pathlib import PurePath
+
+    keys = PurePath(flat_key).parts
+    return keys
+
+
+def dot_splitter(flat_key):
+    keys = tuple(flat_key.split("."))
+    return keys
+
+
+def underscore_splitter(flat_key):
+    keys = tuple(flat_key.split("_"))
+    return keys
+
+
+def make_splitter(delimiter):
+    """Create a reducer with a custom delimiter.
+
+    Parameters
+    ----------
+    delimiter : str
+        Delimiter to use to split keys.
+
+    Returns
+    -------
+    f : Callable
+        Callable that can be passed to ``unflatten``'s ``splitter`` argument.
+    """
+
+    def f(flat_key):
+        keys = tuple(flat_key.split(delimiter))
+        return keys
+
+    return f

flatten_dict/tests/flatten_dict_test.py

@@ -0,0 +1,474 @@
+import json
+import os.path
+from types import GeneratorType
+
+import pytest
+
+from flatten_dict import flatten, unflatten
+from flatten_dict.reducers import (
+    make_reducer,
+    path_reducer,
+    tuple_reducer,
+    underscore_reducer,
+)
+from flatten_dict.splitters import (
+    make_splitter,
+    path_splitter,
+    tuple_splitter,
+    underscore_splitter,
+)
+
+
+@pytest.fixture
+def normal_dict():
+    return {
+        "a": "0",
+        "b": {
+            "a": "1.0",
+            "b": "1.1",
+        },
+        "c": {
+            "a": "2.0",
+            "b": {
+                "a": "2.1.0",
+                "b": "2.1.1",
+            },
+        },
+    }
+
+
+@pytest.fixture
+def flat_tuple_dict():
+    return {
+        ("a",): "0",
+        ("b", "a"): "1.0",
+        ("b", "b"): "1.1",
+        ("c", "a"): "2.0",
+        ("c", "b", "a"): "2.1.0",
+        ("c", "b", "b"): "2.1.1",
+    }
+
+
+@pytest.fixture
+def flat_tuple_dict_depth2():
+    return {
+        ("a",): "0",
+        ("b", "a"): "1.0",
+        ("b", "b"): "1.1",
+        ("c", "a"): "2.0",
+        ("c", "b"): {"a": "2.1.0", "b": "2.1.1"},
+    }
+
+
+@pytest.fixture
+def normal_dict_with_nested_lists():
+    return {
+        "aaa": "0",
+        "bbb": ["1.1", "1.2", "1.3"],
+        "ccc": [{"aaa": "2.1.1"}, {"aaa": "2.2.1"}],
+        "ddd": [["3.1.1", "3.1.2", "3.1.3"], ["3.2.1", "3.2.2", "3.2.3"]],
+        "eee": [
+            {"aaa": ["4.1.1", "4.1.2", "4.1.3"]},
+            {"bbb": ["4.2.1", "4.2.2", "4.2.3"]},
+        ],
+    }
+
+
+@pytest.fixture
+def flat_dict_with_nested_lists_with_list_syntax():
+    return {
+        "aaa": "0",
+        "bbb[0]": "1.1",
+        "bbb[1]": "1.2",
+        "bbb[2]": "1.3",
+        "ccc[0].aaa": "2.1.1",
+        "ccc[1].aaa": "2.2.1",
+        "ddd[0][0]": "3.1.1",
+        "ddd[0][1]": "3.1.2",
+        "ddd[0][2]": "3.1.3",
+        "ddd[1][0]": "3.2.1",
+        "ddd[1][1]": "3.2.2",
+        "ddd[1][2]": "3.2.3",
+        "eee[0].aaa[0]": "4.1.1",
+        "eee[0].aaa[1]": "4.1.2",
+        "eee[0].aaa[2]": "4.1.3",
+        "eee[1].bbb[0]": "4.2.1",
+        "eee[1].bbb[1]": "4.2.2",
+        "eee[1].bbb[2]": "4.2.3",
+    }
+
+
+def get_flat_tuple_dict(flat_tuple_dict):
+    return flat_tuple_dict
+
+
+def get_flat_path_dict(flat_tuple_dict):
+    return {os.path.join(*k): v for k, v in flat_tuple_dict.items()}
+
+
+def get_flat_underscore_dict(flat_tuple_dict):
+    return {"_".join(k): v for k, v in flat_tuple_dict.items()}
+
+
+@pytest.fixture
+def inv_flat_tuple_dict(flat_tuple_dict):
+    return {v: k for k, v in flat_tuple_dict.items()}
+
+
+def test_flatten_dict(normal_dict, flat_tuple_dict):
+    assert flatten(normal_dict) == flat_tuple_dict
+
+
+def test_flatten_dict_invalid_depth_limit(normal_dict):
+    with pytest.raises(ValueError):
+        flatten(normal_dict, max_flatten_depth=0)
+
+
+def test_flatten_dict_depth_limit_1(normal_dict):
+    flattened = flatten(normal_dict, max_flatten_depth=1)
+    values_before = sorted(
+        flattened.values(), key=lambda x: json.dumps(x, sort_keys=True)
+    )
+    values_after = sorted(
+        normal_dict.values(), key=lambda x: json.dumps(x, sort_keys=True)
+    )
+    assert values_before == values_after
+
+
+def test_flatten_dict_depth_limit_2(normal_dict, flat_tuple_dict_depth2):
+    assert flatten(normal_dict, max_flatten_depth=2) == flat_tuple_dict_depth2
+
+
+def test_flatten_dict_irrelevant_depth_limit(normal_dict, flat_tuple_dict):
+    assert flatten(normal_dict, max_flatten_depth=3) == flat_tuple_dict
+
+
+def test_flatten_nonflattenable_type():
+    with pytest.raises(ValueError):
+        flatten([])
+
+
+@pytest.mark.parametrize(
+    "reducer, expected_flat_dict_func",
+    [
+        ("tuple", get_flat_tuple_dict),
+        ("path", get_flat_path_dict),
+        ("underscore", get_flat_underscore_dict),
+        (tuple_reducer, get_flat_tuple_dict),
+        (path_reducer, get_flat_path_dict),
+        (underscore_reducer, get_flat_underscore_dict),
+    ],
+)
+def test_flatten_dict_with_reducer(
+    normal_dict, flat_tuple_dict, reducer, expected_flat_dict_func
+):
+    expected_flat_dict = expected_flat_dict_func(flat_tuple_dict)
+    assert flatten(normal_dict, reducer=reducer) == expected_flat_dict
+
+
+def test_flatten_dict_inverse(normal_dict, inv_flat_tuple_dict):
+    assert flatten(normal_dict, inverse=True) == inv_flat_tuple_dict
+
+
+def test_flatten_dict_inverse_with_duplicated_value(normal_dict):
+    dup_val_dict = normal_dict.copy()
+    dup_val_dict["a"] = "2.1.1"
+    with pytest.raises(ValueError):
+        flatten(dup_val_dict, inverse=True)
+
+
+def test_flatten_dict_with_list_syntax(
+    normal_dict_with_nested_lists, flat_dict_with_nested_lists_with_list_syntax
+):
+    def _reducer(parent_path, key, parent_obj):
+        if parent_path is None:
+            return key
+        if isinstance(parent_obj, list):
+            return "{}[{}]".format(parent_path, key)
+        return "{}.{}".format(parent_path, key)
+
+    assert (
+        flatten(
+            normal_dict_with_nested_lists, reducer=_reducer, enumerate_types=(list,)
+        )
+        == flat_dict_with_nested_lists_with_list_syntax
+    )
+
+
+def test_unflatten_dict(normal_dict, flat_tuple_dict):
+    assert unflatten(flat_tuple_dict) == normal_dict
+
+
+def test_unflatten_dict_inverse(normal_dict, inv_flat_tuple_dict):
+    assert unflatten(inv_flat_tuple_dict, inverse=True) == normal_dict
+
+
+@pytest.mark.parametrize(
+    "splitter, flat_dict_func",
+    [
+        ("tuple", get_flat_tuple_dict),
+        ("path", get_flat_path_dict),
+        ("underscore", get_flat_underscore_dict),
+        (tuple_splitter, get_flat_tuple_dict),
+        (path_splitter, get_flat_path_dict),
+        (underscore_splitter, get_flat_underscore_dict),
+    ],
+)
+def test_unflatten_dict_with_splitter(
+    normal_dict, flat_tuple_dict, splitter, flat_dict_func
+):
+    flat_dict = flat_dict_func(flat_tuple_dict)
+    assert unflatten(flat_dict, splitter=splitter) == normal_dict
+
+
+def test_unflatten_dict_inverse_with_duplicated_value(
+    flat_tuple_dict, inv_flat_tuple_dict
+):
+    inv_flat_tuple_dict["2.1.1"] = ("c", "b", "a")
+    with pytest.raises(ValueError):
+        unflatten(inv_flat_tuple_dict, inverse=True)
+
+
+@pytest.fixture
+def dict_with_list():
+    return {
+        "a": "0",
+        "b": {
+            "a": "1.0",
+            "b": "1.1",
+        },
+        "c": {
+            "a": "2.0",
+            "b": {
+                "a": "2.1.0",
+                "b": ["2.1.1.0", "2.1.1.1"],
+                "c": [],
+            },
+        },
+    }
+
+
+@pytest.fixture
+def flat_tuple_dict_with_list():
+    return {
+        ("a",): "0",
+        ("b", "a"): "1.0",
+        ("b", "b"): "1.1",
+        ("c", "a"): "2.0",
+        ("c", "b", "a"): "2.1.0",
+        ("c", "b", "b"): ["2.1.1.0", "2.1.1.1"],
+        ("c", "b", "c"): [],
+    }
+
+
+@pytest.fixture
+def flat_tuple_dict_with_list_depth2():
+    return {
+        ("a",): "0",
+        ("b", "a"): "1.0",
+        ("b", "b"): "1.1",
+        ("c", "a"): "2.0",
+        ("c", "b"): {
+            "a": "2.1.0",
+            "b": ["2.1.1.0", "2.1.1.1"],
+            "c": [],
+        },
+    }
+
+
+def test_flatten_dict_with_list(dict_with_list, flat_tuple_dict_with_list):
+    assert flatten(dict_with_list) == flat_tuple_dict_with_list
+
+
+def test_flatten_dict_with_list_depth_limit_1(dict_with_list):
+    flattened = flatten(dict_with_list, max_flatten_depth=1)
+    before = sorted(dict_with_list.items(), key=lambda x: x[0])
+    after = sorted(flattened.items(), key=lambda x: x[0])
+    # flatten with the default reducer transforms keys to tuples
+    after = [(x[0][0], x[1]) for x in after]
+    assert before == after
+
+
+def test_flatten_dict_with_list_depth_limit_2(
+    dict_with_list, flat_tuple_dict_with_list_depth2
+):
+    assert (
+        flatten(dict_with_list, max_flatten_depth=2) == flat_tuple_dict_with_list_depth2
+    )
+
+
+def test_flatten_dict_with_list_irrelevant_depth_limit(
+    dict_with_list, flat_tuple_dict_with_list
+):
+    assert flatten(dict_with_list, max_flatten_depth=3) == flat_tuple_dict_with_list
+
+
+@pytest.mark.parametrize(
+    "reducer, expected_flat_dict_func",
+    [
+        ("tuple", get_flat_tuple_dict),
+        ("path", get_flat_path_dict),
+        ("underscore", get_flat_underscore_dict),
+        (tuple_reducer, get_flat_tuple_dict),
+        (path_reducer, get_flat_path_dict),
+        (underscore_reducer, get_flat_underscore_dict),
+    ],
+)
+def test_flatten_dict_with_list_with_reducer(
+    dict_with_list, flat_tuple_dict_with_list, reducer, expected_flat_dict_func
+):
+    expected_flat_dict = expected_flat_dict_func(flat_tuple_dict_with_list)
+    assert flatten(dict_with_list, reducer=reducer) == expected_flat_dict
+
+
+def test_unflatten_dict_with_list(dict_with_list, flat_tuple_dict_with_list):
+    assert unflatten(flat_tuple_dict_with_list) == dict_with_list
+
+
+@pytest.mark.parametrize(
+    "splitter, flat_dict_func",
+    [
+        ("tuple", get_flat_tuple_dict),
+        ("path", get_flat_path_dict),
+        ("underscore", get_flat_underscore_dict),
+        (tuple_splitter, get_flat_tuple_dict),
+        (path_splitter, get_flat_path_dict),
+        (underscore_splitter, get_flat_underscore_dict),
+    ],
+)
+def test_unflatten_dict_with_list_with_splitter(
+    dict_with_list, flat_tuple_dict_with_list, splitter, flat_dict_func
+):
+    flat_dict = flat_dict_func(flat_tuple_dict_with_list)
+    assert unflatten(flat_dict, splitter=splitter) == dict_with_list
+
+
+@pytest.fixture
+def flat_tuple_dict_with_enumerated_list():
+    return {
+        ("a",): "0",
+        ("b", "a"): "1.0",
+        ("b", "b"): "1.1",
+        ("c", "a"): "2.0",
+        ("c", "b", "a"): "2.1.0",
+        ("c", "b", "b", 0): "2.1.1.0",
+        ("c", "b", "b", 1): "2.1.1.1",
+    }
+
+
+def test_flatten_dict_with_list_with_enumerate_types(
+    dict_with_list, flat_tuple_dict_with_enumerated_list
+):
+    assert (
+        flatten(dict_with_list, enumerate_types=(list,))
+        == flat_tuple_dict_with_enumerated_list
+    )
+
+
+def test_flatten_list():
+    assert flatten([1, 2], enumerate_types=(list,)) == {(0,): 1, (1,): 2}
+
+
+@pytest.fixture
+def dict_with_generator():
+    return {
+        "a": "0",
+        "b": {
+            "a": "1.0",
+            "b": "1.1",
+        },
+        "c": {
+            "a": "2.0",
+            "b": {
+                "a": "2.1.0",
+                "b": ("2.1.1.%d" % i for i in range(2)),
+                "c": (i for i in ()),  # empty generator
+            },
+        },
+    }
+
+
+def test_flatten_dict_with_generator_with_enumerate_types(
+    dict_with_generator, flat_tuple_dict_with_enumerated_list
+):
+    assert (
+        flatten(dict_with_generator, enumerate_types=(GeneratorType,))
+        == flat_tuple_dict_with_enumerated_list
+    )
+
+
+@pytest.fixture
+def dict_with_empty_dict():
+    return {
+        "a": "0",
+        "b": {
+            "a": "1.0",
+            "b": "1.1",
+        },
+        "c": {
+            "a": "2.0",
+            "b": {
+                "a": "2.1.0",
+                "b": "2.1.1",
+                "c": {},
+            },
+        },
+    }
+
+
+@pytest.fixture
+def flat_tuple_dict_with_empty_dict():
+    return {
+        ("a",): "0",
+        ("b", "a"): "1.0",
+        ("b", "b"): "1.1",
+        ("c", "a"): "2.0",
+        ("c", "b", "a"): "2.1.0",
+        ("c", "b", "b"): "2.1.1",
+        ("c", "b", "c"): {},
+    }
+
+
+def test_flatten_dict_with_empty_dict(dict_with_empty_dict, flat_tuple_dict):
+    assert flatten(dict_with_empty_dict) == flat_tuple_dict
+
+
+def test_flatten_dict_with_empty_dict_kept(
+    dict_with_empty_dict, flat_tuple_dict_with_empty_dict
+):
+    assert (
+        flatten(dict_with_empty_dict, keep_empty_types=(dict,))
+        == flat_tuple_dict_with_empty_dict
+    )
+
+
+def test_flatten_dict_with_keep_empty_types(normal_dict, flat_tuple_dict):
+    assert flatten(normal_dict, keep_empty_types=(dict, str)) == flat_tuple_dict
+
+
+@pytest.mark.parametrize(
+    "delimiter, delimiter_equivalent", [(".", "dot"), ("_", "underscore")]
+)
+def test_make_reducer(normal_dict, delimiter, delimiter_equivalent):
+    reducer = make_reducer(delimiter)
+    flattened_dict_using_make_reducer = flatten(normal_dict, reducer=reducer)
+    flattened_dict_using_equivalent_reducer = flatten(
+        normal_dict, reducer=delimiter_equivalent
+    )
+    assert flattened_dict_using_make_reducer == flattened_dict_using_equivalent_reducer
+
+
+@pytest.mark.parametrize(
+    "delimiter, delimiter_equivalent", [(".", "dot"), ("_", "underscore")]
+)
+def test_make_splitter(normal_dict, delimiter, delimiter_equivalent):
+    splitter = make_splitter(delimiter)
+    flat_dict = flatten(normal_dict, delimiter_equivalent)
+    unflattened_dict_using_make_splitter = unflatten(flat_dict, splitter=splitter)
+    unflattened_dict_using_equivalent_splitter = unflatten(
+        flat_dict, splitter=delimiter_equivalent
+    )
+    assert (
+        unflattened_dict_using_make_splitter
+        == unflattened_dict_using_equivalent_splitter
+    )

flatten_dict-0.5.0.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: flatten-dict
+Version: 0.5.0
+Summary: A flexible utility for flattening and unflattening dict-like objects in Python.
+License: MIT
+License-File: LICENSE
+Author: Ian Lin
+Author-email: you@example.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Utilities
+Project-URL: Homepage, https://github.com/ianlini/flatten-dict
+Project-URL: Repository, https://github.com/ianlini/flatten-dict
+Description-Content-Type: text/x-rst
+
+flatten-dict
+============
+.. image:: https://github.com/ianlini/flatten-dict/actions/workflows/main.yml/badge.svg
+   :target: https://github.com/ianlini/flatten-dict/actions
+.. image:: https://img.shields.io/pypi/v/flatten-dict.svg
+   :target: https://pypi.org/project/flatten-dict/
+.. image:: https://img.shields.io/pypi/l/flatten-dict.svg
+   :target: https://github.com/ianlini/flatten-dict/blob/master/LICENSE
+.. image:: https://img.shields.io/github/stars/ianlini/flatten-dict.svg?style=social
+   :target: https://github.com/ianlini/flatten-dict
+
+A flexible utility for flattening and unflattening dict-like objects in Python.
+
+
+Introduction
+------------
+This package provides a function ``flatten()`` for flattening dict-like objects in Python (tested with 3.10-3.15).
+It also provides some key joining methods (reducer), and you can choose the reducer you want or even implement your own reducer.
+You can also invert the resulting flat dict using ``unflatten()``.
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install flatten-dict
+
+Documentation
+-------------
+
+Flatten
+```````
+
+.. code-block:: python
+
+   def flatten(d, reducer='tuple', inverse=False, enumerate_types=(), keep_empty_types=()):
+       """Flatten `Mapping` object.
+
+       Parameters
+       ----------
+       d : dict-like object
+           The dict that will be flattened.
+       reducer : {'tuple', 'path', 'underscore', 'dot', Callable}
+           The key joining method. If a `Callable` is given, the `Callable` will be
+           used to reduce.
+           'tuple': The resulting key will be tuple of the original keys.
+           'path': Use `os.path.join` to join keys.
+           'underscore': Use underscores to join keys.
+           'dot': Use dots to join keys.
+       inverse : bool
+           Whether you want invert the resulting key and value.
+       max_flatten_depth : int
+           Maximum depth to merge.
+       enumerate_types : Sequence[type]
+           Flatten these types using `enumerate`.
+           For example, if we set `enumerate_types` to ``(list,)``,
+           `list` indices become keys: ``{'a': ['b', 'c']}`` -> ``{('a', 0): 'b', ('a', 1): 'c'}``.
+       keep_empty_types : Sequence[type]
+           By default, ``flatten({1: 2, 3: {}})`` will give you ``{(1,): 2}``, that is, the key ``3``
+           will disappear.
+           This is also applied for the types in `enumerate_types`, that is,
+           ``flatten({1: 2, 3: []}, enumerate_types=(list,))`` will give you ``{(1,): 2}``.
+           If you want to keep those empty values, you can specify the types in `keep_empty_types`:
+
+           >>> flatten({1: 2, 3: {}}, keep_empty_types=(dict,))
+           {(1,): 2, (3,): {}}
+
+       Returns
+       -------
+       flat_dict : dict
+       """
+
+Examples
+::::::::
+
+>>> from flatten_dict import flatten
+>>> from pprint import pprint
+>>> normal_dict = {
+...     'a': '0',
+...     'b': {
+...         'a': '1.0',
+...         'b': '1.1',
+...     },
+...     'c': {
+...         'a': '2.0',
+...         'b': {
+...             'a': '2.1.0',
+...             'b': '2.1.1',
+...         },
+...     },
+... }
+>>> pprint(flatten(normal_dict))
+{('a',): '0',
+ ('b', 'a'): '1.0',
+ ('b', 'b'): '1.1',
+ ('c', 'a'): '2.0',
+ ('c', 'b', 'a'): '2.1.0',
+ ('c', 'b', 'b'): '2.1.1'}
+>>> pprint(flatten(normal_dict, reducer='path'))
+{'a': '0',
+ 'b/a': '1.0',
+ 'b/b': '1.1',
+ 'c/a': '2.0',
+ 'c/b/a': '2.1.0',
+ 'c/b/b': '2.1.1'}
+>>> pprint(flatten(normal_dict, reducer='path', inverse=True))
+{'0': 'a',
+ '1.0': 'b/a',
+ '1.1': 'b/b',
+ '2.0': 'c/a',
+ '2.1.0': 'c/b/a',
+ '2.1.1': 'c/b/b'}
+>>> pprint(flatten(normal_dict, reducer='path', max_flatten_depth=2))
+{'a': '0',
+ 'b/a': '1.0',
+ 'b/b': '1.1',
+ 'c/a': '2.0',
+ 'c/b': {'a': '2.1.0', 'b': '2.1.1'}}
+
+The `reducer` parameter supports ``'tuple'``, ``'path'``, ``'underscore'``, ``'dot'`` and `Callable`. We can customize the reducer using a function:
+
+>>> def underscore_reducer(k1, k2):
+...     if k1 is None:
+...         return k2
+...     else:
+...         return k1 + "_" + k2
+...
+>>> pprint(flatten(normal_dict, reducer=underscore_reducer))
+{'a': '0',
+ 'b_a': '1.0',
+ 'b_b': '1.1',
+ 'c_a': '2.0',
+ 'c_b_a': '2.1.0',
+ 'c_b_b': '2.1.1'}
+
+There is also a factory function `make_reducer()` to help you create customized reducer. The function currently only supports customized delimiter:
+
+>>> from flatten_dict.reducers import make_reducer
+>>> pprint(flatten(normal_dict, reducer=make_reducer(delimiter='_')))
+{'a': '0',
+ 'b_a': '1.0',
+ 'b_b': '1.1',
+ 'c_a': '2.0',
+ 'c_b_a': '2.1.0',
+ 'c_b_b': '2.1.1'}
+
+If we have some iterable (e.g., `list`) in the `dict`, we will normally get this:
+
+>>> flatten({'a': [1, 2, 3], 'b': 'c'})
+{('a',): [1, 2, 3], ('b',): 'c'}
+
+If we want to use its indices as keys, then we can use the parameter `enumerate_types`:
+
+>>> flatten({'a': [1, 2, 3], 'b': 'c'}, enumerate_types=(list,))
+{('a', 0): 1, ('a', 1): 2, ('a', 2): 3, ('b',): 'c'}
+
+We can even flatten a `list` directly:
+
+>>> flatten([1, 2, 3], enumerate_types=(list,))
+{(0,): 1, (1,): 2, (2,): 3}
+
+If there is an empty dict in the values, by default, it will disappear after flattened:
+
+>>> flatten({1: 2, 3: {}})
+{(1,): 2}
+
+We can keep the empty dict in the result using ``keep_empty_types=(dict,)``:
+
+>>> flatten({1: 2, 3: {}}, keep_empty_types=(dict,))
+{(1,): 2, (3,): {}}
+
+Unflatten
+`````````
+
+.. code-block:: python
+
+   def unflatten(d, splitter='tuple', inverse=False):
+       """Unflatten dict-like object.
+
+       Parameters
+       ----------
+       d : dict-like object
+           The dict that will be unflattened.
+       splitter : {'tuple', 'path', 'underscore', 'dot', Callable}
+           The key splitting method. If a Callable is given, the Callable will be
+           used to split `d`.
+           'tuple': Use each element in the tuple key as the key of the unflattened dict.
+           'path': Use `pathlib.Path.parts` to split keys.
+           'underscore': Use underscores to split keys.
+           'dot': Use dots to split keys.
+       inverse : bool
+           Whether you want to invert the key and value before flattening.
+
+       Returns
+       -------
+       unflattened_dict : dict
+       """
+
+Examples
+::::::::
+
+>>> from pprint import pprint
+>>> from flatten_dict import unflatten
+>>> flat_dict = {
+...     ('a',): '0',
+...     ('b', 'a'): '1.0',
+...     ('b', 'b'): '1.1',
+...     ('c', 'a'): '2.0',
+...     ('c', 'b', 'a'): '2.1.0',
+...     ('c', 'b', 'b'): '2.1.1',
+... }
+>>> pprint(unflatten(flat_dict))
+{'a': '0',
+ 'b': {'a': '1.0', 'b': '1.1'},
+ 'c': {'a': '2.0', 'b': {'a': '2.1.0', 'b': '2.1.1'}}}
+>>> flat_dict = {
+...     'a': '0',
+...     'b/a': '1.0',
+...     'b/b': '1.1',
+...     'c/a': '2.0',
+...     'c/b/a': '2.1.0',
+...     'c/b/b': '2.1.1',
+... }
+>>> pprint(unflatten(flat_dict, splitter='path'))
+{'a': '0',
+ 'b': {'a': '1.0', 'b': '1.1'},
+ 'c': {'a': '2.0', 'b': {'a': '2.1.0', 'b': '2.1.1'}}}
+>>> flat_dict = {
+...     '0': 'a',
+...     '1.0': 'b/a',
+...     '1.1': 'b/b',
+...     '2.0': 'c/a',
+...     '2.1.0': 'c/b/a',
+...     '2.1.1': 'c/b/b',
+... }
+>>> pprint(unflatten(flat_dict, splitter='path', inverse=True))
+{'a': '0',
+ 'b': {'a': '1.0', 'b': '1.1'},
+ 'c': {'a': '2.0', 'b': {'a': '2.1.0', 'b': '2.1.1'}}}
+
+The `splitter` parameter supports ``'tuple'``, ``'path'``, ``'underscore'``, ``'dot'`` and `Callable`. We can customize the reducer using a function:
+
+>>> def underscore_splitter(flat_key):
+...     return flat_key.split("_")
+...
+>>> flat_dict = {
+...     'a': '0',
+...     'b_a': '1.0',
+...     'b_b': '1.1',
+...     'c_a': '2.0',
+...     'c_b_a': '2.1.0',
+...     'c_b_b': '2.1.1',
+... }
+>>> pprint(unflatten(flat_dict, splitter=underscore_splitter))
+{'a': '0',
+ 'b': {'a': '1.0', 'b': '1.1'},
+ 'c': {'a': '2.0', 'b': {'a': '2.1.0', 'b': '2.1.1'}}}
+
+There is also a factory function `make_splitter()` to help you create customized splitter. The function currently only supports customized delimiter:
+
+>>> from flatten_dict.splitters import make_splitter
+>>> pprint(unflatten(flat_dict, splitter=make_splitter(delimiter='_')))
+{'a': '0',
+ 'b': {'a': '1.0', 'b': '1.1'},
+ 'c': {'a': '2.0', 'b': {'a': '2.1.0', 'b': '2.1.1'}}}
+

flatten_dict-0.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+flatten_dict/__init__.py,sha256=f38pB1Z4Q7s5v0jqIq6hVAQIOMbDnADIbd2_WEDW7jw,186
+flatten_dict/flatten_dict.py,sha256=IMGHq2bE1RWTZPqBzIVskOy8PpKUB7jAg20wh7APG30,5513
+flatten_dict/reducer.py,sha256=irHqGQlgcr807TPE_-DsY9286TsDDQ_RKJL4BfwRpI8,278
+flatten_dict/reducers.py,sha256=6_XtTqv9xkFamDmpmQA48gesJFcuBOyAjTOJgCxf3kQ,831
+flatten_dict/splitter.py,sha256=PlEcWhu4eAQIDYoffSHznx3UTdlrV8hHQ9qT5RQnAjA,283
+flatten_dict/splitters.py,sha256=Dt3ufj00m9iV7S7ptEYk76b1SLwvglnxEKHZkzCHW4c,746
+flatten_dict/tests/flatten_dict_test.py,sha256=9KzgRh7c0MZUGvQaYnunNm-PBSKRk7N0A2662nc2iP4,12845
+flatten_dict-0.5.0.dist-info/METADATA,sha256=_VxmnEThCFv8rnHyG6wlbOkfCX77YYa_7tF6kpJthiU,8926
+flatten_dict-0.5.0.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+flatten_dict-0.5.0.dist-info/licenses/LICENSE,sha256=2mzVYhXROtXqbir2WKWhyRQlE9f2JEAeFnkpyqxc_-c,1064
+flatten_dict-0.5.0.dist-info/RECORD,,

flatten_dict-0.5.0.dist-info/WHEEL

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

flatten_dict-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Ian Lin
+
+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.