{"id":3497,"library":"flatdict","title":"FlatDict","description":"FlatDict is a Python module for interacting with nested dictionaries as a single-level dictionary with delimited keys. It provides both `FlatDict` for general nested dictionaries and `FlatterDict` for dictionaries that may contain lists or tuples. The library is actively maintained with regular releases and is currently at version 4.1.0.","status":"active","version":"4.1.0","language":"en","source_language":"en","source_url":"https://github.com/gmr/flatdict","tags":["dictionary","nested","flat","mapping","utility"],"install":[{"cmd":"pip install flatdict","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"symbol":"FlatDict","correct":"from flatdict import FlatDict"},{"symbol":"FlatterDict","correct":"from flatdict import FlatterDict"},{"note":"`__version__` attribute was removed in flatdict 4.1.0. Use `importlib.metadata.version` for programmatic version retrieval.","wrong":"import flatdict; flatdict.__version__","symbol":"__version__","correct":"from importlib.metadata import version; version('flatdict')"}],"quickstart":{"code":"import flatdict\nimport pprint\nfrom importlib.metadata import version\n\n# Get the library version (new way, as __version__ was removed in 4.1.0)\nprint(f\"flatdict version: {version('flatdict')}\")\n\n# Example with FlatDict\nnested_dict = {\n    'user': {\n        'name': 'Alice',\n        'contact': {'email': 'alice@example.com', 'phone': '123-456-7890'}\n    },\n    'app_settings': {'theme': 'dark'}\n}\n\nflat = flatdict.FlatDict(nested_dict)\nprint(\"\\nFlatDict example:\")\nprint(f\"Original nested dict: {nested_dict}\")\nprint(f\"Flat dict representation: {flat}\")\n\n# Accessing values with delimited keys\nprint(f\"Accessing 'user:name': {flat['user:name']}\")\nprint(f\"Accessing 'user:contact:email': {flat['user:contact:email']}\")\n\n# Modifying values\nflat['app_settings:theme'] = 'light'\nprint(f\"Modified 'app_settings:theme': {flat['app_settings:theme']}\")\n\n# Adding new values\nflat['new:key'] = 'new_value'\nprint(f\"Added 'new:key': {flat['new:key']}\")\n\n# Converting back to nested dict\nprint(\"\\nConverted back to nested dict (FlatDict.as_dict()):\")\npprint.pprint(flat.as_dict())\n\n# Example with FlatterDict (handles lists/tuples by enumerating elements)\nnested_with_list = {\n    'items': ['apple', 'banana', {'fruit': 'cherry'}],\n    'settings': {'verbose': True}\n}\nflatter = flatdict.FlatterDict(nested_with_list)\nprint(\"\\nFlatterDict example:\")\nprint(f\"Original nested dict with list: {nested_with_list}\")\nprint(f\"Flatter dict representation: {flatter}\")\n\n# Accessing list elements using numerical keys\nprint(f\"Accessing 'items:0': {flatter['items:0']}\")\nprint(f\"Accessing 'items:2:fruit': {flatter['items:2:fruit']}\")\n\n# Converting back to nested dict\nprint(\"\\nConverted back to nested dict (FlatterDict.as_dict()):\")\npprint.pprint(flatter.as_dict())","lang":"python","description":"This quickstart demonstrates the basic usage of `FlatDict` and `FlatterDict`. It shows how to create flattened dictionaries, access and modify values using delimited keys, add new keys, and convert them back to nested dictionaries. It also illustrates how to correctly retrieve the library version after the removal of the `__version__` attribute in `flatdict` 4.1.0."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or newer.","message":"Python 2 and Python 3.4 support was dropped in version 4.0.0. The minimum required Python version is now 3.10+.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review your code for direct `dict` inheritance assumptions, `as_dict()` return types, and equality comparisons, especially if migrating from versions prior to 3.0.0.","message":"Version 3.0.0 introduced significant changes to core behaviors: `FlatDict.as_dict()` now consistently returns a fully nested data structure, `dict(FlatDict())` yields a shallow dictionary with delimited keys, `FlatDict` extends `collections.MutableMapping` instead of `dict`, and `FlatDict.__eq__` was adjusted to compare only against `dict` instances or other `FlatDict` instances.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use `from importlib.metadata import version; version('flatdict')` to retrieve the package version programmatically.","message":"The `__version__` attribute was removed in version 4.1.0. Attempting to access `flatdict.__version__` will result in an `AttributeError`.","severity":"deprecated","affected_versions":">=4.1.0"},{"fix":"If you need to modify the dictionary during iteration, either iterate over a copy (e.g., `list(flat.items())`) or collect the keys/items to modify beforehand and then perform modifications after the initial iteration.","message":"Modifying a `FlatDict` or `FlatterDict` instance (e.g., adding or deleting items) while actively iterating over its `iteritems()`, `iterkeys()`, or `itervalues()` methods can lead to `RuntimeError` or inconsistent iteration results. This is standard Python dictionary behavior for mutable iterators.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}