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.create_indices(*, from_range: list = None, unique: bool = False, sort: bool = True, append: list = None, remove: list = None) → List[int][source]

Generates a list of integer elements.

Parameters

  • from_range (list, optional) – range arguments to use as the basis of the list

  • unique (bool, optional) – Whether to ascertain uniqueness of elements

  • sort (bool, optional) – Whether to sort the list before returning

  • append (list, optional) – Additional elements to append to the list

  • remove (list, optional) – Elements to remove all occurrences of

Returns

The generated list

Return type

List[int]

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: Union[Mapping, List], upd: Union[Mapping, List], *, try_list_conversion: bool = False, no_convert: 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: Sequence = None, info_func: Callable = None, stop_recursion_types: Sequence[type] = None, _parent_keys: 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, stop_recursion_types: 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.

  • 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.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