logging

remove_log_handlers()

Removes all current log handlers

remove_log_handler(handler)

is_log_handler_active(handler)

is_enabled() → bool

Returns

True if logging is enabled (at least one log handler exists)

set_configure_callback(callback: Callable[[], None], append: bool = True) → None

Configures a function to be called when logging is configured, e.g. through configure, :func:`run_main() or run_cli(). A typical use for the callback is to configure the logging behaviour of packages, setting appropriate log levels.

Parameters

• callback – the function to call

• append – whether to append to the list of callbacks; if False, any existing callbacks will be removed

configure(format='%(levelname)-5s %(asctime)-15s %(name)s:%(funcName)s:%(lineno)d - %(message)s', level=10)

Configures logging to stdout with the given format and log level, also configuring the default log levels of some overly verbose libraries as well as some pandas output options.

Parameters

• format – the log format

• level – the minimum log level

run_main(main_fn: Callable[[], Any], format='%(levelname)-5s %(asctime)-15s %(name)s:%(funcName)s:%(lineno)d - %(message)s', level=10)

Configures logging with the given parameters, ensuring that any exceptions that occur during the execution of the given function are logged. Logs two additional messages, one before the execution of the function, and one upon its completion.

Parameters

• main_fn – the function to be executed

• format – the log message format

• level – the minimum log level

Returns

the result of main_fn

run_cli(main_fn: Callable[[], Any], format='%(levelname)-5s %(asctime)-15s %(name)s:%(funcName)s:%(lineno)d - %(message)s', level=10)

Configures logging with the given parameters and runs the given main function as a CLI using jsonargparse (which is configured to also parse attribute docstrings, such that dataclasses can be used as function arguments). Using this function requires that jsonargparse and docstring_parser be available. Like run_main, two additional log messages will be logged (at the beginning and end of the execution), and it is ensured that all exceptions will be logged.

Parameters

• main_fn – the function to be executed

• format – the log message format

• level – the minimum log level

Returns

the result of main_fn

datetime_tag() → str

Returns

a string tag for use in log file names which contains the current date and time (compact but readable)

add_file_logger(path, register_atexit=True)

add_memory_logger() → None

Enables in-memory logging (if it is not already enabled), i.e. all log statements are written to a memory buffer and can later be read via function get_memory_log()

get_memory_log()

class StopWatch(start=True)

Bases: object

Represents a stop watch for timing an execution. Constructing an instance starts the stopwatch.

__init__(start=True)

reset(start=True)

Resets the stopwatch, setting the elapsed time to zero.

Parameters

start – whether to start the stopwatch immediately

restart()

Resets the stopwatch (setting the elapsed time to zero) and restarts it immediately

pause()

Pauses the stopwatch. It can be resumed via method ‘resume’.

resume()

Resumes the stopwatch (assuming that it is currently paused). If the stopwatch is not paused, the method has no effect (and a warning is logged).

get_elapsed_time_secs() → float

Gets the total elapsed time, in seconds, on this stopwatch.

Returns

the elapsed time in seconds

get_elapsed_timedelta() → pandas._libs.tslibs.timedeltas.Timedelta

Returns

the elapsed time as a pandas.Timedelta object

get_elapsed_time_string() → str

Returns

a string representation of the elapsed time

class StopWatchManager(secret)

Bases: object

A singleton which manages a pool of named stopwatches, such that executions to be timed by referring to a name only - without the need for a limited scope.

classmethod get_instance()

__init__(secret)

start(name)

stop(name) → float

Parameters

name – the name of the stopwatch

Returns

the time that has passed in seconds

is_running(name)

class LogTime(name, enabled=True, logger: Optional[logging.Logger] = None)

Bases: object

An execution time logger which can be conveniently applied using a with-statement - in order to log the executing time of the respective with-block.

__init__(name, enabled=True, logger: Optional[logging.Logger] = None)

Parameters

• name – the name of the event whose time is to be logged upon completion as “<name> completed in <time>”

• enabled – whether the logging is actually enabled; can be set to False to disable logging without necessitating changes to client code

• logger – the logger to use; if None, use the logger of LogTime’s module

start()

Starts the stopwatch

stop()

Stops the stopwatch and logs the time taken (if enabled)

class FileLoggerContext(path: str, enabled=True)

Bases: object

A context handler to be used in conjunction with Python’s with statement which enables file-based logging.

__init__(path: str, enabled=True)

Parameters

• path – the path to the log file

• enabled – whether to actually perform any logging. This switch allows the with statement to be applied regardless of whether logging shall be enabled.

class LoggingDisabledContext(highest_level=50)

Bases: object

A context manager that will temporarily disable logging

__init__(highest_level=50)

Parameters

highest_level – the highest level to disable

class FallbackHandler(handler: logging.Handler, level=0)

Bases: logging.Handler

A log handler which applies the given handler only if the root logger has no defined handlers (or no handlers other than this fallback handler itself)

__init__(handler: logging.Handler, level=0)

Parameters

• handler – the handler to which messages shall be passed on

• level – the minimum level to output; if NOTSET, pass on everything

emit(record)

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.