{"id":2031,"library":"flatten-dict","title":"Flatten-dict","description":"Flatten-dict is a flexible utility library for flattening and unflattening dict-like objects in Python. It supports custom key formatters (splitters/reducers) and handles nested structures, lists, and tuples. The current version is 0.4.2, and it maintains an active release cadence with improvements and bug fixes.","status":"active","version":"0.4.2","language":"en","source_language":"en","source_url":"https://github.com/ianlini/flatten-dict","tags":["dictionary","data-structure","flatten","unflatten","utility","nested-data"],"install":[{"cmd":"pip install flatten-dict","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for Python versions < 3.8 to ensure optimal import performance.","package":"importlib-metadata","optional":false},{"reason":"Optional dependency for Python versions < 3.4. If not installed, some file path related functionalities might be limited.","package":"pathlib2","optional":true}],"imports":[{"symbol":"flatten","correct":"from flatten_dict import flatten"},{"symbol":"unflatten","correct":"from flatten_dict import unflatten"},{"note":"The 'splitter' module was deprecated in 0.4.0 in favor of 'splitters' (plural).","wrong":"from flatten_dict.splitter import make_splitter","symbol":"make_splitter","correct":"from flatten_dict.splitters import make_splitter"},{"note":"The 'reducer' module was deprecated in 0.4.0 in favor of 'reducers' (plural).","wrong":"from flatten_dict.reducer import make_reducer","symbol":"make_reducer","correct":"from flatten_dict.reducers import make_reducer"}],"quickstart":{"code":"from flatten_dict import flatten, unflatten\n\ndata = {\n    'user': {\n        'name': 'Alice',\n        'address': {'city': 'Wonderland', 'zip': '12345'}\n    },\n    'products': [\n        {'id': 1, 'item': 'Tea Cup'},\n        {'id': 2, 'item': 'Rabbit Hole'}\n    ]\n}\n\n# Flatten the dictionary with default underscore delimiter\nflat_data = flatten(data)\nprint('Flattened (default underscore):')\nprint(flat_data)\n# 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'}\n\n# Unflatten it back\nunflat_data = unflatten(flat_data)\nprint('\\nUnflattened back:')\nprint(unflat_data)\n# Expected: {'user': {'name': 'Alice', 'address': {'city': 'Wonderland', 'zip': '12345'}}, 'products': [{'id': 1, 'item': 'Tea Cup'}, {'id': 2, 'item': 'Rabbit Hole'}]}\n\n# Flatten with a custom dot delimiter\nfrom flatten_dict.splitters import dot_splitter\nflat_data_dot = flatten(data, splitter=dot_splitter)\nprint('\\nFlattened (dot splitter):')\nprint(flat_data_dot)\n# 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'}\n","lang":"python","description":"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."},"warnings":[{"fix":"Update your imports: `from flatten_dict.splitter import ...` to `from flatten_dict.splitters import ...` and similarly for `reducer` to `reducers`.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"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 (`.`).","severity":"gotcha","affected_versions":"All"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.8 (importlib-metadata), <3.4 (pathlib2)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}