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:
- slice(None): Keep all
- function: Keep if function(key) is True
- list, set: Keep if key in list/set
- 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:
- slice(None): Keep all
- function: Keep if function(key) is True
- list, set: Keep if key in list/set
- 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