Utilities

Various tools used in ceed.

ceed.utils.update_key_if_other_key(items, key, value, other_key, key_map)

Given a dict, or list/tuple of dicts (recursively), it goes through all the dicts and updates the keys who match.

Specifically, if a key matches key, its value matches value, there’s another key named other_key in the dict, and the value of other_key is in key_map, then the value of other_key is updated to that value from key_map.

ceed.utils.collapse_list_to_counts(values: list) → List[Tuple[Any, int]]

Converts a sequence of items to tuples of the item and count of sequential items.

E.g.:

>>> collapse_list_to_counts([1, 1, 2, 3, 1, 1, 1, 3,])
[(1, 2), (2, 1), (3, 1), (1, 3), (3, 1)]

ceed.utils.get_plugin_modules(base_package: str, root: Union[str, pathlib.Path]) → Tuple[List[str], List[Tuple[Tuple[str], bytes]]]

Takes a package name and it’s corresponding root path and returns a list of the modules recursively within this package, as well as the source files in bytes.

Only *.py files are considered, and although included with the source bytes, the packages list skips any files that start with a underscore (except __init__.py of course).

class ceed.utils.CeedWithID

Bases: object

Adds ceed_id to the class so that any inheriting class instance can be associated with a unique integer ID for logging purposes.

The ID is not automatically set for every object, it is manually set when set_ceed_id() is called. See stage/function for when it’s called.

ceed_id: int = 0: The integer id of the object.

set_ceed_id(min_available: int) → int

Sets the ID of this and any sub objects, each to a number equal or greater than min_available and returns the next minimum number available to be used.

See event_data for more details.

Parameters: min_available – The minimum number available to be used for the ID so it is unique.
Returns: The next minimum available number that can be used. Any number larger or equal to it is free to be used.

class ceed.utils.UniqueNames(*args, **kwargs)

Bases: set

A set of names, that helps ensure no names in the set is duplicated.

It provides a fix_name() method that fixes the name, given some input such that the returned name will not be in the set.

E.g.:

>>> names = UniqueNames()
>>> names.fix_name('floor')
'floor'
>>> names.add('floor')
>>> names.fix_name('floor')
'floor-1'
>>> names.add('floor-1')
>>> names.fix_name('floor')
'floor-2'
>>> names.fix_name('floor-1')
'floor-2'
>>> names.fix_name('floor-0')
'floor-0'
>>> names.remove('floor')
>>> names.fix_name('floor')
'floor'
>>> names.fix_name('floor-1')
'floor-2'
>>> names.add('floor-1')
Traceback (most recent call last):
  File "<ipython-input-14-b43fff249a6b>", line 1, in <module>
    names.add('floor-1')
  File "G:\Python\libs\ceed\ceed\utils.py", line 202, in add
    >>> names.add('floor')
ValueError: Tried to add floor-1, but it is already in the set

add(element: str) → None

Add an element to a set.

This has no effect if the element is already present.

fix_name(name: str) → str

If the name is already in the set, it returns a new name so that is not in the set. Otherwise, it returns the original name.

Parameters: name – The name to check if it already exists in the set.
Returns: The original or fixed name, such that it is not in the set.

remove(element: str) → None

Remove an element from a set; it must be a member.

If the element is not a member, raise a KeyError.

clear() → None: Remove all elements from this set.