FlatterDict Class

This module contains the implementation of the FlatterDict class, which provides a dictionary-like interface for working with nested dictionaries using delimited keys but it is designed to handle lists and sets as child-dict instances with the offset as the key.

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

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

as_dict() → Sequence[Any] | set[Any] | dict[Any, Any]

[Deprecated] Return the nested data type representation of the FlatterDict.

Returns:

A nested data type

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 flatter dictionary.

copy() → FlatterDict

Return a deep copy of the flatter dictionary.

property delimiter: str

The key delimiter used for the flat dictionary.

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

Flattens a nested data type structure into a flatter dictionary with delimited keys.

Parameters:

• value – The nested data structure to flatten, can be a dictionary or a FlatDict

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

Returns:

A flat dictionary with delimited keys representing the nested structure

Raises:

ValueError – if the delimiter is an empty string or if any keys in the nested structure 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() → Sequence[Any] | set[Any] | dict[Any, Any]

Inflates the flatter dictionary into a nested data type structure.

Any lists, sets, tuples, or dictionaries will be inflated as their respective types, with the keys of the flat dictionary used as indices for lists and sets and as keys for dictionaries.

Returns:

A nested data type representing the inflated structure of the flatter dictionary

items() → ItemsView[str, Any]

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

This viewer will automatically reflect any changes to the flatter dictionary, including changes to the flatter dictionary and any nested data types that would affect the items.

keys() → KeysView[str]

Return a view of the flatter dictionary’s keys.

This viewer will automatically reflect any changes to the flatter dictionary, including changes to the flatter dictionary and any nested data types that would affect the keys.

property meta_keys: tuple[str, ...]

The keys that exist as parent keys to nested dictionaries or sequences and are not themselves present in the flat dictionary.

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 flatter 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) → Sequence[Any] | set[Any] | dict[Any, Any]

Inflates a flatter dictionary into a nested data type structure.

Parameters:

• value – The flat dictionary to unflatten

• delimiter – The delimiter used in the flatter dictionary keys

Returns:

A nested data type representing the inflated structure of the flatter dictionary

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 flatter 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 flatter dictionary with.

Returns:

None

values() → ValuesView[Any]

Return a view of the flatter dictionary’s values.

This viewer will automatically reflect any changes to the flatter dictionary, including changes to the flatter dictionary and any nested data types that would affect the values.

Examples

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