Registry / serialization / flatdict

flatdict

JSON →
library4.1.0pypypi✓ verified 24d ago

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.

pip install flatdict
INSTALL
IMPORT
SIG · FLATDICT
F
flatdict
serializationpythonv4.1.0
Install
1.7s avg
Import
11ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.010s · 17.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.7s · import 0.006s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FlatDict
from flatdict import FlatDict
FlatterDict
from flatdict import FlatterDict
__version__
from importlib.metadata import version; version('flatdict')
import flatdict; flatdict.__version__
`__version__` attribute was removed in flatdict 4.1.0. Use `importlib.metadata.version` for programmatic version retrieval.

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.

import flatdict import pprint from importlib.metadata import version # Get the library version (new way, as __version__ was removed in 4.1.0) print(f"flatdict version: {version('flatdict')}") # Example with FlatDict nested_dict = { 'user': { 'name': 'Alice', 'contact': {'email': 'alice@example.com', 'phone': '123-456-7890'} }, 'app_settings': {'theme': 'dark'} } flat = flatdict.FlatDict(nested_dict) print("\nFlatDict example:") print(f"Original nested dict: {nested_dict}") print(f"Flat dict representation: {flat}") # Accessing values with delimited keys print(f"Accessing 'user:name': {flat['user:name']}") print(f"Accessing 'user:contact:email': {flat['user:contact:email']}") # Modifying values flat['app_settings:theme'] = 'light' print(f"Modified 'app_settings:theme': {flat['app_settings:theme']}") # Adding new values flat['new:key'] = 'new_value' print(f"Added 'new:key': {flat['new:key']}") # Converting back to nested dict print("\nConverted back to nested dict (FlatDict.as_dict()):") pprint.pprint(flat.as_dict()) # Example with FlatterDict (handles lists/tuples by enumerating elements) nested_with_list = { 'items': ['apple', 'banana', {'fruit': 'cherry'}], 'settings': {'verbose': True} } flatter = flatdict.FlatterDict(nested_with_list) print("\nFlatterDict example:") print(f"Original nested dict with list: {nested_with_list}") print(f"Flatter dict representation: {flatter}") # Accessing list elements using numerical keys print(f"Accessing 'items:0': {flatter['items:0']}") print(f"Accessing 'items:2:fruit': {flatter['items:2:fruit']}") # Converting back to nested dict print("\nConverted back to nested dict (FlatterDict.as_dict()):") pprint.pprint(flatter.as_dict())
Debug
Known issues
breakingPython 2 and Python 3.4 support was dropped in version 4.0.0. The minimum required Python version is now 3.10+.
fix
Upgrade your Python environment to version 3.10 or newer.
affects: >=4.0.0
breakingVersion 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.
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.
affects: >=3.0.0
deprecatedThe `__version__` attribute was removed in version 4.1.0. Attempting to access `flatdict.__version__` will result in an `AttributeError`.
fix
Use `from importlib.metadata import version; version('flatdict')` to retrieve the package version programmatically.
affects: >=4.1.0
gotchaModifying 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.
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.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flatdict'
The `flatdict` library has not been installed in your Python environment.
fix
pip install flatdict
TypeError: Assignment to invalid type for key {key_name}
This error often occurs when attempting to assign a value to a flattened key that was originally part of a list or tuple in a `FlatterDict`, and the new assignment is incompatible with how `FlatterDict` manages array-like structures internally.
fix
Ensure that when modifying elements that originated from lists or tuples in a `FlatterDict`, you either reassign the entire (sub)list/tuple or access its elements as if they were part of a dictionary with integer keys. For example, if 'list_key' was originally a list, `flatter_dict['list_key:0'] = 'new_value'` is generally correct, but trying to assign a non-indexable type to a key representing an array segment can fail. It might be necessary to convert the `FlatterDict` to a regular dict using `as_dict()` for complex modifications, then re-flatten if needed, or reconstruct the problematic section.
KeyError: '{key}'
This error occurs when attempting to access or remove a key that does not exist in the `FlatDict` or `FlatterDict`.
fix
Before accessing or manipulating a key, check for its existence using `if 'key' in flat_dict:` or use methods like `flat_dict.get('key', default_value)` or `flat_dict.pop('key', default_value)` which allow specifying a default return value instead of raising a `KeyError`.
AttributeError: module 'collections' has no attribute 'MutableMapping'
This issue arises in Python 3.9 and newer versions where `collections.MutableMapping` has been moved to `collections.abc.MutableMapping`. Older versions of `flatdict` or other libraries that import `flatdict` might not correctly handle this change.
fix
Upgrade `flatdict` to its latest version (4.1.0 or newer) which includes compatibility fixes for this change. If the issue persists due to other dependencies, ensure all related packages are updated to be compatible with your Python version.
Upgrade
Version history
4.1.0latest on PyPI · released Feb 15, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
Agent activity
5 hits · last 30 days
node
4
Resources
flatdict — pip install flatdict · libregistry