dantro.tools module

This module implements tools that are generally useful in dantro

dantro.tools.recursive_update(d: dict, u: dict) → dict[source]

Recursively updates the Mapping-like object d with the Mapping-like object u and returns it. Note that this does not create a copy of d, but changes it mutably!

Based on: http://stackoverflow.com/a/32357112/1827608

Parameters
  • d (dict) – The mapping to update

  • u (dict) – The mapping whose values are used to update d

Returns

The updated dict d

Return type

dict

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

ValueError – If any index or key in the key sequence was not available

dantro.tools.clear_line(only_in_tty=True, break_if_not_tty=True)[source]

Clears the current terminal line and resets the cursor to the first position using a POSIX command.

Based on: https://stackoverflow.com/a/25105111/1827608

Parameters
  • only_in_tty (bool, optional) – If True (default) will only clear the line if the script is executed in a TTY

  • break_if_not_tty (bool, optional) – If True (default), will insert a line break if the script is not executed in a TTY

dantro.tools.fill_line(s: str, *, num_cols: int = 79, fill_char: str = ' ', align: str = 'left') → str[source]

Extends the given string such that it fills a whole line of num_cols columns.

Parameters
  • s (str) – The string to extend to a whole line

  • num_cols (int, optional) – The number of colums of the line; defaults to the number of TTY columns or – if those are not available – 79

  • fill_char (str, optional) – The fill character

  • align (str, optional) – The alignment. Can be: ‘left’, ‘right’, ‘center’ or the one-letter equivalents.

Returns

The string of length num_cols

Return type

str

Raises

ValueError – For invalid align or fill_char argument

dantro.tools.print_line(s: str, *, end='\r', **kwargs)[source]

Wrapper around fill_line() that also prints a line with carriage return (without new line) as end character. This is useful for progress report lines that overwrite the previously printed content repetitively.

dantro.tools.center_in_line(s: str, *, num_cols: int = 79, fill_char: str = '·', spacing: int = 1) → str[source]

Shortcut for a common fill_line use case.

Parameters
  • s (str) – The string to center in the line

  • num_cols (int, optional) – The number of columns in the line

  • fill_char (str, optional) – The fill character

  • spacing (int, optional) – The spacing around the string s

Returns

The string centered in the line

Return type

str

dantro.tools.make_columns(items: List[str], *, wrap_width: int = 79, fstr: str = ' {item:<{width:}s} ') → str[source]

Given a sequence of string items, returns a string with these items spread out over several columns. Iteration is first within the row and then into the next row.

The number of columns is determined automatically from the wrap width, the length of the longest item in the items list, and the length of the evaluated format string.

Parameters
  • items (List[str]) – The string items to represent in columns.

  • wrap_width (int, optional) – The maximum width of each full row

  • fstr (str, optional) – The format string to use. Needs to accept the keys item and width, the latter of which will be used for padding. The format string should lead to strings of equal length, otherwise the column layout will be messed up!

dantro.tools.apply_along_axis(func, axis: int, arr: numpy.ndarray, *args, **kwargs) → numpy.ndarray[source]

This is like numpy’s function of the same name, but does not try to cast the results of func to an np.ndarray but tries to keep them as dtype object. Thus, the return value of this function will always have one fewer dimension then the input array.

This goes along the equivalent formulation of np.apply_along_axis, outlined in their documentation of the function.

dantro.tools.decode_bytestrings(obj) → str[source]

Checks whether the given attribute value is or contains byte strings and if so, decodes it to a python string.

Parameters

obj – The object to try to decode into holding python strings

Returns

Either the unchanged object or the decoded one

Return type

str

dantro.tools.is_iterable(obj) → bool[source]

Tries whether the given object is iterable.

dantro.tools.is_hashable(obj) → bool[source]

Tries whether the given object is hashable.

class dantro.tools.DoNothingContext[source]

Bases: object

A context manager that … does nothing.

__enter__()[source]

Called upon entering the context using the with statement

__exit__(*args)[source]

Called upon exiting context, with *args being exceptions etc.

class dantro.tools.adjusted_log_levels(*new_levels: Sequence[Tuple[str, int]])[source]

Bases: object

A context manager that temporarily adjusts log levels

__enter__()[source]

When entering the context, sets these levels

__exit__(*_)[source]

When leaving the context, resets the levels to their old state

dantro.tools.total_bytesize(files: List[str]) → int[source]

Returns the total size of a list of files

dantro.tools.format_bytesize(num: int, *, precision: int = 1) → str[source]

Formats a size in bytes to a human readable (binary) format.

Stripped down from https://stackoverflow.com/a/63839503/1827608 .

Parameters
  • num (int) – Number of bytes

  • precision (int, optional) – The decimal precision to use, can be 0..3

Returns

The formatted, human-readable byte size

Return type

str

dantro.tools.format_time(duration: Union[float, datetime.timedelta], *, ms_precision: int = 0, max_num_parts: int = None) → str[source]

Given a duration (in seconds), formats it into a string.

The formatting divisors are: days, hours, minutes, seconds

If ms_precision > 0 and duration < 60, decimal places will be shown for the seconds.

Parameters
  • duration (Union[float, timedelta]) – The duration in seconds to format into a duration string; it can also be a timedelta object.

  • ms_precision (int, optional) – The precision of the seconds slot

  • max_num_parts (int, optional) – How many parts to include when creating the formatted time string. For example, if the time consists of the parts seconds, minutes, and hours, and the argument is 2, only the hours and minutes parts will be shown, thus reducing the precision of the overall representation of duration. If None, all parts are included.

Returns

The formatted duration string

Return type

str

class dantro.tools.PoolCallbackHandler(n_max: int, *, silent: bool = False, fstr: str = ' Loaded {n}/{n_max} .')[source]

Bases: object

A simple callback handler for multiprocessing pools

__init__(n_max: int, *, silent: bool = False, fstr: str = ' Loaded {n}/{n_max} .')[source]
Parameters
  • n_max (int) – Number of tasks

  • silent (bool, optional) – If true, will not print a message

  • fstr (str, optional) – The format string for the status message. May contain keys n and n_max.

class dantro.tools.PoolErrorCallbackHandler[source]

Bases: object

A simple callback handler for errors in multiprocessing pools

track_error(error: Exception)[source]
property errors