paramspace.tools module#
This module provides general methods needed by the ParamSpan and ParamSpace classes.
- paramspace.tools.SKIP#
A global
paramspace.tools.Skip
object to signify a Skip operation in therecursive_*
functions. Not supported everywhere.
- class paramspace.tools.Skip[source]#
Bases:
object
A Skip object can be used to indiciate that no action should be taken.
It is used in the
recursive_**
functions likeparamspace.tools.recursive_update()
to indicate that a value is to be skipped.
- paramspace.tools.recursive_contains(obj: Union[Mapping, Sequence], *, keys: Sequence) bool [source]#
Checks whether the given keysequence is reachable in the
obj
.- Parameters:
obj (Union[Mapping, Sequence]) – The object to check recursively
keys (Sequence) – The sequence of keys to check for
- Returns:
Whether the key sequence is reachable
- Return type:
- paramspace.tools.recursive_getitem(obj: Union[Mapping, Sequence], *, keys: Sequence)[source]#
Go along the sequence of
keys
throughobj
and return the target item.- Parameters:
obj (Union[Mapping, Sequence]) – The object to get the item from
keys (Sequence) – The sequence of keys to follow
- Returns:
The target item from
obj
, specified bykeys
- Raises:
IndexError – If any index in the key sequence was not available
KeyError – If any key in the key sequence was not available
- paramspace.tools.recursive_update(obj: ~typing.Union[~typing.Mapping, ~typing.List], upd: ~typing.Union[~typing.Mapping, ~typing.List], *, try_list_conversion: bool = False, no_convert: ~typing.Sequence[type] = (<class 'str'>,)) Union[Mapping, List] [source]#
Recursively update items in
obj
with the values fromupd
.Be aware that objects are not copied from
upd
toobj
, but only assigned. This means:the given
obj
will be changed in placechanging mutable elements in
obj
will also change them in upd
After the update, obj holds all entries of upd plus those that it did not have in common with upd.
If recursion is possible is determined by type; it is only done for types mappings (dicts) or lists.
To indicate that a value in a list should not be updated, an instance of the tools.Skip class, e.g. the tools.SKIP object, can be passed instead.
- Parameters:
obj (Union[Mapping, List]) – The object to update.
upd (Union[Mapping, List]) – The object to use for updating.
try_list_conversion (bool, optional) – If true, it is tried to convert an entry in
obj
to a list if it is a list inupd
no_convert (Sequence[type], optional) – For these types, conversion is skipped and an empty list is generated instead.
- Returns:
The updated
obj
- Return type:
Union[Mapping, List]
- paramspace.tools.recursive_setitem(d: dict, *, keys: Tuple[str], val, create_key: bool = False)[source]#
Recursively goes through dict-like
d
along thekeys
sequence in keys and sets the value to the child entry.- Parameters:
- Raises:
KeyError – On missing entry at
keys
.
- paramspace.tools.recursive_collect(obj: Union[Mapping, Sequence], *, select_func: Callable, prepend_info: Optional[Sequence] = None, info_func: Optional[Callable] = None, stop_recursion_types: Optional[Sequence[type]] = None, _parent_keys: Optional[tuple] = None) list [source]#
Go recursively through a mapping or sequence and collect selected elements.
The
select_func
is called on each value. If it returnsTrue
, that value will be collected to a list, which is returned at the end.Additionally, some information can be gathered about these elements, controlled by
prepend_info
.With
prepend_info
, information can be prepended to the return value. Then, not only the values but also these additional items can be gathered:keys
: prepends the keyinfo_func
: prepends the return value ofinfo_func(val)
The resulting return value is then a list of tuples (in that order).
- Parameters:
obj (Union[Mapping, Sequence]) – The object to recursively search
select_func (Callable) – Each element is passed to this function; if True is returned, the element is collected and search ends here.
prepend_info (Sequence, optional) –
If given, additional info about the selected elements can be gathered in two ways:
By passing
keys
, the sequence of keys to get to this element is appended;by passing
info_func
, theinfo_func
function is called on the argument and that value is added to the information tuple.
info_func (Callable, optional) – The function used to prepend info
stop_recursion_types (Sequence[type], optional) – Can specify types here that will not be further recursed through. NOTE that strings are never recursed through further.
_parent_keys (tuple, optional) – Used to track the keys; not public!
- Returns:
the collected elements, as selected by select_func(val) or – if
prepend_info
was set – tuples of(info, element)
, where the requested information is in the first entries of the tuple- Return type:
- Raises:
ValueError – Raised if invalid
prepend_info
entries were set
- paramspace.tools.recursive_replace(obj: Union[Mapping, Sequence], *, select_func: Callable, replace_func: Callable, stop_recursion_types: Optional[Sequence[type]] = None) Union[Mapping, Sequence] [source]#
Go recursively through a mapping or sequence and call a replace function on each element that the select function returned true on.
For passing arguments to any of the two, use lambda functions.
- Parameters:
cont (Union[Mapping, Sequence]) – The object to walk through recursively
select_func (Callable) – The function that each value is passed to. If it returns
True
, the element will be replaced using thereplace_func
.replace_func (Callable) – Called if the
select_func
returned True. The return value replaces the existing object at the selected position insideobj
.stop_recursion_types (Sequence[type], optional) – Can specify types here that will not be further recursed through. NOTE that strings are never recursed through further.
- Returns:
The updated mapping where each element that was selected was replaced by the return value of the replacement function.
- Return type:
Union[Mapping, Sequence]
- paramspace.tools.recursively_sort_dict(d: dict) OrderedDict [source]#
Recursively sorts a dictionary by its keys, transforming it to an OrderedDict in the process.
From: http://stackoverflow.com/a/22721724/1827608
- Parameters:
d (dict) – The dictionary to be sorted
- Returns:
the recursively sorted dict
- Return type:
OrderedDict
- paramspace.tools.is_iterable(obj) bool [source]#
Whether the given object is iterable or not.
This is tested simply by invoking
iter(obj)
and returningFalse
if this operation raises a TypeError.- Parameters:
obj – The object to test
- Returns:
True if iterable, False else
- Return type:
- paramspace.tools.get_key_val_iter(obj: Union[Mapping, Sequence]) Iterator [source]#
Given an object – assumed dict- or sequence-like – returns a
(key, value)
iterator.- Parameters:
obj (Union[Mapping, Sequence]) – The object to generate the key-value iterator from
- Returns:
An iterator that emits
(key, value)
tuples- Return type:
Iterator