StructuredNestedDict / sndict

StructuredNestedDict/sndict s are heavy-weight data structures hierarchical of dict s. Unlike the light-weight ndict, sndict transforms all underlying dict s to sndict s and enforces a fixed dictionary depth internally.

In turn, these constraints allow for more powerful operations to be performed across the different levels of hierarchy.

class sndict.structurednesteddict.StructuredNestedDict(*args, **kwargs)[source]

Extension of OrderedDict that exposes advanced operations on nested dicts of fixed depth

data: dict, or list
Nested dictionary
levels: int
Number of levels
level_names: list
List of level names
convert(dict_type=None)[source]

Convert all nested dictionaries to desired type.

dict_type: [‘sndict’, ‘ndict’, ‘dict’, ‘odict’]
Dict-type in string format

dict, OrderedDict or NestedDict

dim

Dimensions of whole StructuredNestedDict, up to defined level

tuple:
Tuple of widths of nested dictionaries, one per level
dim_dict

Dimensions of whole StructuredNestedDict as dict, up to defined level

dict
Dimensions keyed by level name
filter_key(criteria_ls, filter_out=False, drop_empty=False)[source]

Filter StructuredNestedDict by criteria.

The criteria used in the following ways, based on type:
  1. slice(None): Keep all
  2. function: Keep if function(key) is True
  3. list, set: Keep if key in list/set
  4. other: Keep if key==other
criteria_ls: list or dict
Filter based on criteria
filter_out: bool
Whether to filter in or out
drop_empty:
Whether to drop empty nested dictionaries (nested dictionaries with all elements filtered out)

StructuredNestedDict

filter_values(criteria, filter_out=False, level=None, drop_empty=False)[source]

Filter StructuredNestedDict values by criteria.

The criteria used in the following ways, based on type:
  1. slice(None): Keep all
  2. function: Keep if function(key) is True
  3. list, set: Keep if key in list/set
  4. other: Keep if key==other
criteria: See above
Filter based on criteria
filter_out: bool
Whether to filter in or out
drop_empty:
Whether to drop empty nested dictionaries (nested dictionaries with all elements filtered out)

StructuredNestedDict

flatten(levels=-1, named=True, flattened_name=None)[source]

Returns an StructuredNestedDict with multiple levels flattened

WARNING:
If there are empty dictionaries within the levels being flattened, their keys will be lost. This is consistent with the logic of flattening - those dictionaries contain no values for a (level-tuple)-keyed dictionary.
Note:
.flatten(levels=0) does nothing, .flatten(levels=1) compresses 1 level (i.e. keys will be 2-ples) .flatten(levels=-1) compresses all levels
levels: int, default=1
Number of levels to flatten by. Defaults to flattening one level
named: bool
Whether output key-tuples are namedtuples
flattened_name: str
Name of new flattened level. Defaults to original level names joined by “___”

StructuredNestedDict

flatten_keys(levels=-1, named=True)[source]

Returns an list with of keys of flattened dict

WARNING:
If there are empty dictionaries within the levels being flattened, their keys will be lost. This is consistent with the logic of flattening - those dictionaries contain no values for a (level-tuple)-keyed dictionary.
Note:
.flatten(levels=0) does nothing, .flatten(levels=1) compresses 1 level (i.e. keys will be 2-ples) .flatten(levels=-1) compresses all levels
levels: int, default=1
Number of levels to flatten by. Defaults to flattening one level
named: bool
Whether output key-tuples are namedtuples

list

flatten_values(levels=-1)[source]

Returns an list with of values of flattened dict

WARNING:
If there are empty dictionaries within the levels being flattened, their keys will be lost. This is consistent with the logic of flattening - those dictionaries contain no values for a (level-tuple)-keyed dictionary.
Note:
.flatten(levels=0) does nothing, .flatten(levels=1) compresses 1 level (i.e. keys will be 2-ples) .flatten(levels=-1) compresses all levels
levels: int, default=-1
Number of levels to flatten by. Defaults to flattening all levels.

list

get_named_tuple(levels)[source]

Get namedtuple class for named keys

levels: Number of levels to construct named keys for

class

classmethod groupby(data, by, levels=None, level_names=None)[source]

Initialize by grouping elements from list

data: list or dictionary
List or dictionary to group by
by: function
Function applied to list elements to form key elements
levels: int
Number of levels
level_names: list
List of level names

StructuredNestedDict

has_nested_key(key_list)[source]

Check if nested keys are valid

key_list: list
List of keys, one for each dict depth

bool

iterflatten(levels=-1, named=True)[source]

Returns an iterator with multiple levels flattened

WARNING:
If there are empty dictionaries within the levels being flattened, their keys will be lost. This is consistent with the logic of flattening - those dictionaries contain no values for a (level-tuple)-keyed dictionary.
Note:
.flatten(levels=0) does nothing, .flatten(levels=1) compresses 1 level (i.e. keys will be 2-ples) .flatten(levels=-1) compresses all levels
levels: int, default=1
Number of levels to flatten by. Defaults to flattening one level
named: bool
Whether output key-tuples are namedtuples

StructuredNestedDict

iterflatten_keys(levels=-1, named=True)[source]

Returns an iterator with of keys of flattened dict

WARNING:
If there are empty dictionaries within the levels being flattened, their keys will be lost. This is consistent with the logic of flattening - those dictionaries contain no values for a (level-tuple)-keyed dictionary.
Note:
.flatten(levels=0) does nothing, .flatten(levels=1) compresses 1 level (i.e. keys will be 2-ples) .flatten(levels=-1) compresses all levels
levels: int, default=1
Number of levels to flatten by. Defaults to flattening one level
named: bool
Whether output key-tuples are namedtuples

list

iterflatten_values(levels=-1)[source]

Returns an iterator with of values of flattened dict

WARNING:
If there are empty dictionaries within the levels being flattened, their keys will be lost. This is consistent with the logic of flattening - those dictionaries contain no values for a (level-tuple)-keyed dictionary.
Note:
.flatten(levels=0) does nothing, .flatten(levels=1) compresses 1 level (i.e. keys will be 2-ples) .flatten(levels=-1) compresses all levels
levels: int, default=-1
Number of levels to flatten by. Defaults to flattening all levels.

list

ix

Indexer that allows for indexing by nested key/criteria list e.g.

my_ndict.ix[“key1”, “key2”, “key3”]

or with criteria such as

my_sndict.ix[“key1”, :, lambda _: “3” in _]

Also supports:

my_sndict.ix[“key1”]

If behavior is ambiguous, use sndict.ixkeys[key_list] and sndict[key] directly instead

Indexable

ixkeys

Indexer that allows for indexing by nested key list e.g.

my_ndict.ix[“key1”, “key2”, “key3”]

or with criteria such as

my_sndict.ix[“key1”, :, lambda _: “3” in _]

Note that for a single key, a tuple/list needs to be provided, e.g.

my_sndict.ix[“key1”,]

Indexable

level_names

Names of levels. Defaults to [“level0”, “level1”, …] is no names are provided

list

levels

Number of levels

int

map(key_func=None, val_func=None, at_level=-1, warn=False)[source]

Apply transformations to keys and values

key_func: function, optional
Function to transform keys. Defaults to identity.
val_func: function, optional
Function to transform values. Defaults to identity.
at_level: int
Level to transform keys at
warn: bool
Warn if dimensions of dictionary have been changed

StructuredNestedDict

map_keys(key_func, at_level=-1)[source]

Apply transformations to keys and values

key_func: function
Function to transform keys
at_level: int
Level to transform keys at

StructuredNestedDict

map_values(val_func, at_level=-1)[source]

Apply transformations to keys and values

val_func: function
Function to transform values
at_level: int
Level to transform values at

StructuredNestedDict

nested_get(key_list)[source]

Get value at depth

key_list: list
List of keys, one for each dict depth

obj

nested_set(key_list, value)[source]

Set a value within nested dicts, creating StructuredNestedDict at depth if they don’t exist yet

Note: Only allowed to set up to level of StructuredNestedDict

key_list: list
List of keys, one for each dict depth
value: object
Value to set nested
nested_setdefault(key_list, default=None)[source]

Nested version of dict.setdefault. Set a value within nested dicts, creating StructuredNestedDict at depth if they don’t exist yet

Note: Only allowed to set up to level of StructuredNestedDict

key_list: list
List of keys, one for each dict depth
default: object, optional
Value to set nested
rearrange(level_ls=None, level_name_ls=None)[source]

Rearrange levels of StructuredNestedDict Only supply either level_ls or level_name_ls.

Note: Whether supplying level_ls or level_name_ls, the supplied list

must cover all levels contiguously from the start. I.e.

level_ls=[2, 0, 1, 3]

is valid but

level_ls=[2, 0]

is not.

level_ls: list
List of level ints. If level_ls contains level_names instead, the arguments is passed on to level_name_ls
level_name_ls: list
List of level names

StructuredNestedDict

replace_data(data)[source]

Return new StructuredNestedDict with different data but same metadata

data: dict, or list
Nested dictionary

StructuredNestedDict

replace_metadata(**kwargs)[source]

Return new StructuredNestedDict with different metadata but same data

levels: int
Number of nested levels that StructuredNestedDict will work on
level_names: list
List of level names

StructuredNestedDict

sort_keys(cmp=None, key=None, reverse=False)[source]

Sort keys of StructuredNestedDict (top-level only)

cmp: function, optional
Comparator function
key: function, optional
Key function
reverse: bool, optional
Whether to sort in reverse

StructuredNestedDict

sort_values(key=None, reverse=False)[source]

Sort values of StructuredNestedDict (top-level only)

key: function
Key function
reverse: bool
Whether to sort in reverse

StructuredNestedDict

stratify(levels=None, stratified_names=None)[source]
Increases depth (nests) of StructuredNestedDict by splitting up
keys in the top-most level
levels: int, default=None
Number of levels to stratify by. Defaults to length of first key. Note: levels must be <= length of all top-level keys
stratified_names: default=None
Names of newly created stratified levels. Must be same length as levels.

StructuredNestedDict

swap_levels(level_a, level_b)[source]

Swap two levels in a StructuredNestedDict

Unlike sndict.rearrange, there’s no need to be contiguous

level_a: int or str
level or level_name
level_b: int or str
level or level_name

StructuredNestedDict

to_tree_string(indent=' - ', key_mode='str', val_mode='type')[source]

Returns structure of NestedDict in tree format string

indent: str
Indentation string for levels
key_mode: “type”, “str” or “repr”
How to serialize key
val_mode: “type”, “str” or “repr”
How to serialize terminal value

str

unique_keys(named=False, sort_keys=True)[source]

Returns the unique keys in each level of the dictionary

named: bool
If True, return OrderedDict of list of keys of each level. If False, return a list of list of keys.
sort_keys: bool
Whether to sort each list of keys

list or dict