Miscellaneous

Provides some utilities functions used by the shennong library

Those fonctions are not designed to be used by the end-user.

shennong.utils.null_logger()[source]

Configures and returns a logger sending messages to nowhere

This is used as default logger for some functions.

Returns

logging.Logger – Logging instance ignoring all the messages.

shennong.utils.get_logger(name=None, level='info', formatter='%(levelname)s - %(message)s')[source]

Configures and returns a logger sending messages to standard error

Parameters
  • name (str) – Name of the created logger, to be displayed in the header of log messages.

  • level (str, optional) – The minimum log level handled by the logger (any message above this level will be ignored). Must be ‘debug’, ‘info’, ‘warning’ or ‘error’. Default to ‘info’.

  • formatter (str, optional) – A string to format the log messages, see https://docs.python.org/3/library/logging.html#formatter-objects. By default display level and message. Use ‘%(asctime)s - %(levelname)s - %(name)s - %(message)s’ to display time, level, name and message.

Returns

logging.Logger – A configured logging instance displaying messages to the standard error stream.

Raises

ValueError – If the logging level is not ‘debug’, ‘info’, ‘warning’ or ‘error’.

shennong.utils.get_njobs(njobs, log=<RootLogger None (INFO)>)[source]

Returns the number of parallel jobs to run

The returned number of jobs is adapted from the input njobs value, considering the number of CPU cores available on the machine.

Parameters
  • njobs (int) – The desired number of jobs to use.

  • log (logging.Logger, optional) – A logger where to send messages, no logging by default.

Returns

njobs (int) – The returned value is min(njobs, ncpus).

Raises

ValueError – If njobs is not a strictly positive integer.

shennong.utils.list2array(x)[source]

Converts lists in x into numpy arrays

shennong.utils.array2list(x)[source]

Converts numpy arrays in x into lists

shennong.utils.dict_equal(x, y)[source]

Returns True if x and y are equals

The dictionnaries x and y can contain numpy arrays.

Parameters
  • x (dict) – The first dictionnary to compare

  • y (dict) – The second dictionnary to compare

Returns

equal (bool) – True if x == y, False otherwise

shennong.utils.list_files_with_extension(directory, extension, abspath=False, realpath=True, recursive=True)[source]

Return all files of given extension in directory hierarchy

Parameters
  • directory (str) – The directory where to search for files

  • extension (str) – The extension of the targeted files (e.g. ‘.wav’)

  • abspath (bool, optional) – If True, return the absolute path to the file/link, default to False.

  • realpath (bool, optional) – If True, return resolved links, default to True.

  • recursive (bool, optional) – If True, list files in the whole subdirectories tree, if False just list the top-level directory, default to True.

Returns

files (list) – The files are returned in a sorted list with a path relative to ‘directory’, except if abspath or realpath is True

class shennong.utils.CatchExceptions(function)[source]

Bases: object

Decorator wrapping a function in a try/except block

When an exception occurs, display a user friendly message on standard output before exiting with error code 1.

The detected exceptions are ValueError, OSError, RuntimeError, AssertionError, KeyboardInterrupt and pkg_resources.DistributionNotFound.

Parameters

function – The function to wrap in a try/except block

static exit(msg)[source]

Write msg on stderr and exit with error code 1