iblutil.util

Functions

`Listable`	Return a typing.Union if the input and sequence of input.
`dir_size`	Calculate the total size of a directory including all its subdirectories and files.
`ensure_list`	Ensure input is a list.
`flatten`	Flatten a nested Iterable excluding strings and dicts.
`get_mac`	Fetch the machine's unique MAC address formatted according to IEEE 802 specifications.
`log_to_file`	Save log information to a given filename in '.ibl_logs' folder (in home directory).
`range_str`	Given a list of integers, returns a terse string expressing the unique values.
`rrmdir`	Recursively remove a folder and its parents up to a defined level - if they are empty.
`setup_logger`	Set up a log for IBL packages.

Classes

Bunch

A subclass of dictionary with an additional dot syntax.

Listable(t)[source]: Return a typing.Union if the input and sequence of input.

class Bunch(*args, **kwargs)[source]

Bases: dict

A subclass of dictionary with an additional dot syntax.

copy(deep=False)[source]

Return a new Bunch instance which is a copy of the current Bunch instance.

Parameters:: deep (bool) – If True perform a deep copy (see notes). By default a shallow copy is returned.
Returns:: A new copy of the Bunch.
Return type:: Bunch

Notes

A shallow copy constructs a new Bunch object and then (to the extent possible) inserts

references into it to the objects found in the original. - A deep copy constructs a new Bunch and then, recursively, inserts copies into it of the

objects found in the original.

save(npz_file, compress=False)[source]

Saves a npz file containing the arrays of the bunch.

Parameters:

npz_file – output file
compress – bool (False) use compression

Returns:

None

static load(npz_file)[source]

Loads a npz file containing the arrays of the bunch.

Parameters:: npz_file – output file
Returns:: Bunch

flatten(x, generator=False)[source]

Flatten a nested Iterable excluding strings and dicts.

Converts nested Iterable into flat list. Will not iterate through strings or dicts.

Returns:: Flattened list or generator object.
Return type:: list or generator

range_str(values: iter) → str[source]

Given a list of integers, returns a terse string expressing the unique values.

Example

indices = [0, 1, 2, 3, 4, 7, 8, 11, 15, 20] range_str(indices) >> ‘0-4, 7-8, 11, 15 & 20’

Parameters:: values – An iterable of ints
Returns:: A string of unique value ranges

setup_logger(name='ibl', level=0, file=None, no_color=False)[source]

Set up a log for IBL packages.

Uses date time, calling function and distinct colours for levels. Sets the name if not set already and add a stream handler. If the stream handler already exists, does not duplicate. The naming/level allows not to interfere with third-party libraries when setting level.

Parameters:

name (str) – Log name, should be set to the root package name for consistent logging throughout the app.
level (str, int) – The logging level (defaults to NOTSET, which inherits the parent log level)
file (bool, str, pathlib.Path) – If True, a file handler is added with the default file location, otherwise a log file path may be passed.
no_color (bool) – If true the colour log is deactivated. May be useful when directing the std out to a file.

Returns:

The configured log.

Return type:

logging.Logger, logging.RootLogger

log_to_file(log='ibl', filename=None)[source]

Save log information to a given filename in ‘.ibl_logs’ folder (in home directory).

Parameters:

log (str, logging.Logger) – The log (name or object) to add file handler to.
filename (str, Pathlib.Path) – The name of the log file to save to.

Returns:

The log with the file handler attached.

Return type:

logging.Logger

rrmdir(folder: Path, levels: int = 0)[source]

Recursively remove a folder and its parents up to a defined level - if they are empty.

Parameters:

folder (pathlib.Path) – The path to a folder at which to start the recursion.
levels (int) – Recursion level, i.e. the number of parents to delete, relative to folder. Defaults to 0 - which has the same effect as pathlib.Path.rmdir except that it won’t raise an OSError if the directory is not empty.

Returns:

A list of folders that were recursively removed.

Return type:

list of pathlib.Path

Raises:

FileNotFoundError – If folder does not exist.
PermissionError – Insufficient privileges or folder in use by another process.
NotADirectoryError – The folder provided is most likely a file.

dir_size(directory: str | Path, follow_symlinks: bool = False) → int[source]

Calculate the total size of a directory including all its subdirectories and files.

Parameters:

directory (str | Path) – The path to the directory for which the size needs to be calculated.
follow_symlinks (bool, optional) – Whether to follow symbolic links when calculating the size. Default is False.

Returns:

The total size of the directory in bytes.

Return type:

int

get_mac() → str[source]

Fetch the machine’s unique MAC address formatted according to IEEE 802 specifications.

Returns:: The MAC address of the device formatted in six groups of two hexadecimal digits separated by hyphens in transmission order (e.g., ‘BA-DB-AD-C0-FF-EE’).
Return type:: str

ensure_list(value, exclude_type=(<class 'str'>, <class 'dict'>))[source]

Ensure input is a list.

Wraps value in a list if not already an iterator or if it is a member of specific iterable classes.

To allow users the option of passing a single value or multiple values, this function will wrap the former in a list and by default will consider str and dict instances as a single value. This function is useful because it treats tuples, lists, sets, and generators all as ‘lists’, but not dictionaries and strings.

Parameters:

value (any) – Input to ensure list.
exclude_type (tuple, optional) – A list of iterable classes to wrap in a list.

Returns:

Either value if iterable and not in exclude_type list, or value wrapped in a list.

Return type:

Iterable