Utilities

Provides several useful utility functions.

e13tools.utils.add_to_all(obj)

Custom decorator that allows for the name of the provided object obj to be automatically added to the __all__ attribute of the frame this decorator is used in. The provided obj must have a __name__ attribute.

e13tools.utils.check_instance(instance, cls)

Checks if provided instance has been initialized from a proper cls (sub)class. Raises a TypeError if instance is not an instance of cls.

Parameters:

• instance (object) – Class instance that needs to be checked.
• cls (class) – The class which instance needs to be properly initialized from.

Returns:

result (bool) – Bool indicating whether or not the provided instance was initialized from a proper cls (sub)class.

e13tools.utils.delist(list_obj)

Returns a copy of list_obj with all empty lists and tuples removed.

Parameters:list_obj (list) – A list object that requires its empty list/tuple elements to be removed. Returns:delisted_copy (list) – Copy of list_obj with all empty lists/tuples removed.

e13tools.utils.docstring_append(addendum, join='')

Custom decorator that allows a given string addendum to be appended to the docstring of the target function/class, separated by a given string join.

If addendum is not a string, its __doc__ attribute is used instead.

e13tools.utils.docstring_copy(source)

Custom decorator that allows the docstring of a function/class source to be copied to the target function/class.

e13tools.utils.docstring_substitute(*args, **kwargs)

Custom decorator that allows either given positional arguments args or keyword arguments kwargs to be substituted into the docstring of the target function/class.

Both % and .format() string formatting styles are supported. Keep in mind that this decorator will always attempt to do %-formatting first, and only uses .format() if the first fails.

e13tools.utils.get_main_desc(source)

Retrieves the main description of the provided object source and returns it.

The main description is defined as the first paragraph of its docstring.

Parameters:source (object) – The object whose main description must be retrieved. Returns:main_desc (str or None) – The main description string of the provided source or None if source has not docstring.

e13tools.utils.get_outer_frame(func)

Checks whether or not the calling function contains an outer frame corresponding to func and returns it if so. If this frame cannot be found, returns None instead.

Parameters:func (function) – The function or method whose frame must be located in the outer frames. Returns:outer_frame (frame or None) – The requested outer frame if it was found, or None if it was not.

e13tools.utils.raise_error(err_msg, err_type=<class 'Exception'>, logger=None, err_traceback=None)

Raises a given error err_msg of type err_type and logs the error using the provided logger.

Parameters:

err_msg (str) – The message included in the error.

Other Parameters:  

• err_type (Exception subclass. Default: Exception) – The type of error that needs to be raised.

• logger (Logger object or None. Default: None) – The logger to which the error message must be written. If None, the RootLogger logger is used instead.

• err_traceback (traceback object or None. Default: None) – The traceback object that must be used for this exception, useful for when this function is used for reraising a caught exception. If None, no additional traceback is used.

  New in version 0.6.17.

See also

raise_warning()

Raises and logs a given warning.

e13tools.utils.raise_warning(warn_msg, warn_type=<class 'UserWarning'>, logger=None, stacklevel=1)

Raises/issues a given warning warn_msg of type warn_type and logs the warning using the provided logger.

Parameters:

warn_msg (str) – The message included in the warning.

Other Parameters:  

• warn_type (Warning subclass. Default: UserWarning) – The type of warning that needs to be raised/issued.
• logger (Logger object or None. Default: None) – The logger to which the warning message must be written. If None, the RootLogger logger is used instead.
• stacklevel (int. Default: 1) – The stack level of the warning message at the location of this function call. The actual used stack level is increased by one to account for this function call.

See also

raise_error()

Raises and logs a given error.

e13tools.utils.split_seq(*seq)

Converts a provided sequence seq to a string, removes all auxiliary characters from it, splits it up into individual elements and converts all elements back to booleans; floats; integers; and/or strings.

The auxiliary characters are given by aux_char_set. One can add, change and remove characters from the set if required. If one wishes to keep an auxiliary character that is in seq, it must be escaped by a backslash (note that backslashes themselves also need to be escaped).

This function can be used to easily unpack a large sequence of nested iterables into a single list, or to convert a formatted string to a list of elements.

Parameters:seq (str, array_like or tuple of arguments) – The sequence that needs to be split into individual elements. If array_like, seq is first unpacked into a string. It is possible for seq to be a nested iterable. Returns:new_seq (list) – A list with all individual elements converted to booleans; floats; integers; and/or strings.

Examples

The following function calls all produce the same output:

>>> split_seq('A', 1, 20.0, 'B')
['A', 1, 20.0, 'B']
>>> split_seq(['A', 1, 2e1, 'B'])
['A', 1, 20.0, 'B']
>>> split_seq("A 1 20. B")
['A', 1, 20.0, 'B']
>>> split_seq([("A", 1), (["20."], "B")])
['A', 1, 20.0, 'B']
>>> split_seq("[(A / }| ; <1{}) , ,>20.0000 !! < )?% \B")
['A', 1, 20.0, 'B']

If one wants to keep the ‘?’ in the last string above, it must be escaped:

>>> split_seq("[(A / }| ; <1{}) , ,>20.0000 !! < )\?% \B")
['A', 1, 20.0, '?', 'B']

See also

unpack_str_seq()

Unpacks a provided (nested) sequence into a single string.

e13tools.utils.unpack_str_seq(*seq, sep=', ')

Unpacks a provided sequence seq of elements and iterables, and converts it to a single string separated by sep.

Use split_seq() if it is instead required to unpack seq into a single list while maintaining the types of all elements.

Parameters:seq (str, array_like or tuple of arguments) – The sequence that needs to be unpacked into a single string. If seq contains nested iterables, this function is used recursively to unpack them as well. Other Parameters:  sep (str. Default: ‘, ‘) – The string to use for separating the elements in the unpacked string. Returns:unpacked_seq (str) – A string containing all elements in seq unpacked and converted to a string, separated by sep.

Examples

The following function calls all produce the same output:

>>> unpack_str_seq('A', 1, 20.0, 'B')
'A, 1, 20.0, B'
>>> unpack_str_seq(['A', 1, 2e1, 'B'])
'A, 1, 20.0, B'
>>> unpack_str_seq("A, 1, 20.0, B")
'A, 1, 20.0, B'
>>> unpack_str_seq([("A", 1), (["20.0"], "B")])
'A, 1, 20.0, B'

See also

split_seq()

Splits up a provided (nested) sequence into a list of individual elements.