Flatten-dict

Warnings

• breaking The modules `flatten_dict.splitter` and `flatten_dict.reducer` were deprecated in version 0.4.0 in favor of their pluralized counterparts, `flatten_dict.splitters` and `flatten_dict.reducers`. Direct imports from the old paths will raise a DeprecationWarning and may break in future versions.
  Fix: Update your imports: `from flatten_dict.splitter import ...` to `from flatten_dict.splitters import ...` and similarly for `reducer` to `reducers`.
• gotcha By default, `flatten()` uses an underscore (`_`) as a delimiter and automatically enumerates items in lists/tuples. This might not be the desired key format, especially if keys already contain underscores or you prefer a different delimiter like a dot (`.`).
  Fix: Specify a custom `splitter` (for `flatten`) and `reducer` (for `unflatten`) when calling the functions. For example, use `splitter=dot_splitter` from `flatten_dict.splitters` for dot-separated keys, or `make_splitter('your_delimiter')` for custom delimiters.
• gotcha The `enumerate_types` parameter in `flatten()` (defaulting to `(list, tuple)`) will turn list/tuple indices into parts of the flattened key (e.g., `products_0_id`). If you want to prevent enumeration for certain types or handle them differently, you need to adjust this parameter.
  Fix: Set `enumerate_types=()` to disable enumeration for all types, or provide a tuple of specific types that should be enumerated (e.g., `enumerate_types=(list,)` to enumerate only lists, not tuples).
• gotcha For Python versions prior to 3.8, `importlib-metadata` is a required dependency to ensure good import performance. While `pathlib2` is optional for Python < 3.4, not having these can lead to slower performance or potentially missed functionality on older Python versions.
  Fix: Ensure `importlib-metadata` is installed (`pip install importlib-metadata`) when using Python < 3.8. Consider installing `pathlib2` if on Python < 3.4 for full compatibility.

Install

• pip install flatten-dict Install stable version

Imports

• flatten

  from flatten_dict import flatten

• unflatten

  from flatten_dict import unflatten

• make_splitter

  from flatten_dict.splitters import make_splitter

  The 'splitter' module was deprecated in 0.4.0 in favor of 'splitters' (plural).
• make_reducer

  from flatten_dict.reducers import make_reducer

  The 'reducer' module was deprecated in 0.4.0 in favor of 'reducers' (plural).

Quickstart

This quickstart demonstrates basic flattening and unflattening of a nested dictionary using the default underscore delimiter, and then shows how to use a custom dot delimiter for flattening.

from flatten_dict import flatten, unflatten

data = {
    'user': {
        'name': 'Alice',
        'address': {'city': 'Wonderland', 'zip': '12345'}
    },
    'products': [
        {'id': 1, 'item': 'Tea Cup'},
        {'id': 2, 'item': 'Rabbit Hole'}
    ]
}

# Flatten the dictionary with default underscore delimiter
flat_data = flatten(data)
print('Flattened (default underscore):')
print(flat_data)
# Expected: {'user_name': 'Alice', 'user_address_city': 'Wonderland', 'user_address_zip': '12345', 'products_0_id': 1, 'products_0_item': 'Tea Cup', 'products_1_id': 2, 'products_1_item': 'Rabbit Hole'}

# Unflatten it back
unflat_data = unflatten(flat_data)
print('\nUnflattened back:')
print(unflat_data)
# Expected: {'user': {'name': 'Alice', 'address': {'city': 'Wonderland', 'zip': '12345'}}, 'products': [{'id': 1, 'item': 'Tea Cup'}, {'id': 2, 'item': 'Rabbit Hole'}]}

# Flatten with a custom dot delimiter
from flatten_dict.splitters import dot_splitter
flat_data_dot = flatten(data, splitter=dot_splitter)
print('\nFlattened (dot splitter):')
print(flat_data_dot)
# Expected: {'user.name': 'Alice', 'user.address.city': 'Wonderland', 'user.address.zip': '12345', 'products.0.id': 1, 'products.0.item': 'Tea Cup', 'products.1.id': 2, 'products.1.item': 'Rabbit Hole'}