FlatDict Class

This module contains the implementation of the FlatDict class, which provides a dictionary-like interface for working with nested dictionaries using delimited keys.

class cj365.flatdict.flat_dict.FlatDict(value: dict[Any, Any] | NamedTuple | FlatDict | None = None, delimiter: str = '.')

A dictionary object that allows for single level, delimited key/value pair mapping of nested dictionaries.

as_dict() → dict[Any, Any]

[Deprecated] Return the nested dictionary representation of the FlatDict.

Returns:

A nested dictionary

Deprecated since version 5.0.0: Use the ‘inflate’ method instead, ‘as_dict()’ will be removed in a future version

clear()

Remove all items from the flat dictionary.

copy() → FlatDict

Return a deep copy of the flat dictionary.

property delimiter: str

The key delimiter used for the flat dictionary.

static flatten(value: dict[Any, Any] | FlatDict, delimiter: str) → dict[str, Any]

Flattens a nested dictionary into a single level dictionary with delimited keys.

Parameters:

• value – The nested dictionary or FlatDict to flatten

• delimiter – The delimiter to use for the keys in the flat dictionary

Returns:

A flat dictionary with delimited keys representing the nested structure of the input

Raises:

ValueError – if the delimiter is an empty string or if any keys in the input collide with the delimiter

get(key: str, default: Any = None) → Any

Retrieves the value for a delimited-key if key exists, otherwise returns the default.

If default is not given, it defaults to None, so this method never raises KeyError.

Parameters:

• key – The key name (with delimiters if necessary)

• default – The value to return if the key is not found

inflate() → dict[Any, Any]

Inflates the flat dictionary into a nested dictionary structure.

Returns:

A nested dictionary representing the inflated structure of the flat dictionary

items() → ItemsView[str, Any]

Return a view of the flat dictionary’s items (key-value pairs).

This viewer will automatically reflect any changes to the flat dictionary, including changes to the flat dictionary and any nested dictionaries that would affect the items.

keys() → KeysView[str]

Return a view of the flat dictionary’s keys.

This viewer will automatically reflect any changes to the flat dictionary, including changes to the flat dictionary and any nested dictionaries that would affect the keys.

property meta_keys: tuple[str, ...]

The keys that exist as parent keys to nested dictionaries

pop(key: str, default: Any = None) → Any

Remove the specified key and return the corresponding value. If the key is not found, return the default value.

Parameters:

• key – The delimited-key of the value to remove

• default – The value to return if the key is not found

Returns:

The value for the key if it exists, otherwise the default

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

set_delimiter(delimiter: str) → Self

Set the key delimiter for the flat dictionary

Parameters:

delimiter – The delimiter to use

Raises:

ValueError – if the delimiter collides with an existing key

setdefault(key: str, default: Any = None) → Any

Safely retrieve a delimited-key value, or insert the default value if the key does not exist.

Parameters:

• key – The key name (with delimiters if necessary)

• default – The value to set and return if the key is not found

Returns:

The value for the key if it exists, otherwise the default

static unflatten(value: dict[str, Any], delimiter: str) → dict[Any, Any]

Inflates a flat dictionary with delimited keys into a nested dictionary.

Parameters:

• value – The flat dictionary to unflatten

• delimiter – The delimiter used in the flat dictionary keys

Returns:

A nested dictionary representing the inflated structure

Raises:

ValueError – if the delimiter is an empty string

update(arg: SupportsKeysAndGetItem[str, Any], /, **kwargs: Any) → None

update(arg: Iterable[tuple[str, Any]], /, **kwargs: Any) → None

update(**kwargs: Any) → None

Update the flat dictionary with the key/value pairs from arg and kwargs.

Parameters:

• arg – The argument can be either a mapping or an iterable of key/value pairs.

• kwargs – Additional key/value pairs to update the flat dictionary with.

Returns:

None

values() → ValuesView[Any]

Return a view of the flat dictionary’s values.

This viewer will automatically reflect any changes to the flat dictionary, including changes to the flat dictionary and any nested dictionaries that would affect the values.

Examples

For examples of how to use the FlatDict class, check out the Example Use section.