FlatDict

Warnings

• breaking Python 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.
• breaking 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.
  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.
• deprecated The `__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.
• gotcha 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.
  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.

Install

• pip install flatdict Install latest version

Imports

• FlatDict

  from flatdict import FlatDict

• FlatterDict

  from flatdict import FlatterDict

• __version__

  from importlib.metadata import version; version('flatdict')

  `__version__` attribute was removed in flatdict 4.1.0. Use `importlib.metadata.version` for programmatic version retrieval.

Quickstart

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())