paramspace.tools module

paramspace.tools module#

This module provides general methods needed by the ParamSpan and ParamSpace classes.

paramspace.tools.log[source]#

The local logger instance

paramspace.tools.SKIP#

A global paramspace.tools.Skip object to signify a Skip operation in the recursive_* 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 like paramspace.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:

bool

paramspace.tools.recursive_getitem(obj: Union[Mapping, Sequence], *, keys: Sequence)[source]#

Go along the sequence of keys through obj 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 by keys

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 from upd.

Be aware that objects are not copied from upd to obj, but only assigned. This means:

  • the given obj will be changed in place

  • changing 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 in upd

  • 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 the keys sequence in keys and sets the value to the child entry.

Parameters:

  • d (dict) – The dict-like object to invoke setitem on

  • keys (tuple) – The key sequence pointing to the node to set the value of

  • val – The value to set at d[the][key][sequence]

  • create_key (bool, optional) – Whether to create the key if it does not already exist. Default: False.

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 returns True, 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 key

  • info_func : prepends the return value of info_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:

    1. By passing keys, the sequence of keys to get to this element is appended;

    2. by passing info_func, the info_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:

list

Raises:

ValueError – Raised if invalid prepend_info entries were set

paramspace.tools.recursive_replace(obj: Union[Mapping, Sequence], *, select_func: Callable, replace_func: Callable, recurse_after_replace: bool = False, 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 the replace_func.

  • replace_func (Callable) – Called if the select_func returned True. The return value replaces the existing object at the selected position inside obj.

  • recurse_after_replace (bool, optional) – if True, will continue the recursion after having applied the replace function; in effect, the recursive_replace call continues on the result of the replace_func.

  • 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(obj: Union[dict, Any], **kwargs) → Union[dict, Any][source]#

Recursively sorts dicts inside a nested objects by its keys.

Also recurses along lists or tuples, in case they contain other dicts that may require key-sorting.

Note

Does not use OrderedDict types, but instead reconstructs dicts with sorted keys, hence generating shallow copies.

Parameters:

  • obj (Union[dict, Any]) – The object potentially containing to-be-sorted dicts or dict-like objects.

  • **kwargs – Passed on to recursive_replace() which is used for sorting.

Returns:

the object with contained dicts recursively sorted

by their keys

Return type:

Union[dict, Any]

paramspace.tools.to_simple_dict(obj: Union[dict, Any], **kwargs) → Union[dict, Any][source]#

Recursively go through given dict-like object and cast dict on all entries, such that they are stored as plain dicts.

Also recurses along tuples and lists in case they have dicts as elements.

Parameters:

  • obj (Union[dict, Any]) – The dictionary or any other nestable object that may contain dict-like object that should be cast to plain dicts.

  • **kwargs – Passed on to recursive_replace() which is used for recursively converting to dict.

Returns:

the object, but with nested dict-like objects cast

to plain dicts.

Return type:

Union[dict, Any]

paramspace.tools.is_iterable(obj) → bool[source]#

Whether the given object is iterable or not.

This is tested simply by invoking iter(obj) and returning False if this operation raises a TypeError.

Parameters:

obj – The object to test

Returns:

True if iterable, False else

Return type:

bool

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

Contents