cotainr.tracing module

cotainr - a user space Apptainer/Singularity container builder.

Copyright DeiC, deic.dk Licensed under the European Union Public License (EUPL) 1.2 - see the LICENSE file for details.

This module implements functionality for tracing and logging console messages.

Classes

ColoredOutputFormatter(logging.Formatter)

A log formatter for coloring log messages based on log level.

ConsoleSpinner

A console messages spinner context manager.

LogDispatcher

A dispatcher for configuring and handling log messages.

LogSettings

Dataclass containing settings for a LogDispatcher.

MessageSpinner

A spinner for console messages.

StreamWriteProxy

A proxy for manipulating the write methods of streams.

Attributes

console_lock

The lock to acquire for manipulating the console messages.

API reference

class cotainr.tracing.ColoredOutputFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: Formatter

A log formatter for coloring log messages based on log level.

Inserts ANSI escape codes to color lines based on their log level:

• logging.DEBUG : gray

• logging.WARNING : yellow

• logging.ERROR : dark read

• logging.CRITICAL : brighter red

Attributes:

log_level_fg_colorsdict

Mapping of log level to ANSI escape color codes.

reset_colorstr

The ANSI escape code to reset (color) formatting.

Methods

converter([seconds])	Convert seconds since the Epoch to a time tuple expressing local time.
format(record)	Format the specified record as colored text.
formatException(ei)	Format and return the specified exception information as a string.
formatStack(stack_info)	This method is provided as an extension point for specialized formatting of stack information.
formatTime(record[, datefmt])	Return the creation time of the specified LogRecord as formatted text.
usesTime()	Check if the format uses the creation time of the record.

formatMessage

format(record)

Format the specified record as colored text.

log_level_fg_colors = {10: '\x1b[38;5;8m', 20: '', 30: '\x1b[38;5;3m', 40: '\x1b[38;5;1m', 50: '\x1b[38;5;160m'}

reset_color = '\x1b[0m'

class cotainr.tracing.ConsoleSpinner

Bases: object

A console messages spinner context manager.

Creates a context in which messages to sys.stdout and sys.stderr are prepended with a spinner to indicate that the program is still progressing while we are waiting for the next message to be displayed on the console.

Notes

The ConsoleSpinner is implemented by monkeypatching sys.stdout, sys.stderr, and input().

The sys.stdout.write() and sys.stderr.write() methods are replaced by the _update_spinner_msg() method which starts a new MessageSpinner thread every time a new message is written to stdout / stderr. In order to avoid an infinite recursion when the text is actually written to the console, sys.stdout and sys.stderr are wrapped by StreamWriteProxy instances.

The input() function is wrapped to make sure that the spinner is stopped while waiting for the user to provide their input.

As we only ever have a single console which we are interacting with via stdin/stdout/stderr, it makes sense to have a single corresponding ConsoleSpinner that actually manipulates stdin/stdout/stderr. We keep track of this “main” instance by having it acquire the module level console_lock.

Nothing is done to handle the use of the readline module. It may or may not work in a ConsoleSpinner context.

This ConsoleSpinner class is only intended to be used with the threading module. It doesn’t support multiprocessing. Using the ConsoleSpinner within multiple threads should be avoided, since this may lead to strange race conditions. If unavoidable make sure that all those threads are started within a ConsoleSpinner context to ensure correct operation.

class cotainr.tracing.LogDispatcher(*, name, map_log_level_func, log_settings, filters=None)

Bases: object

A dispatcher for configuring and handling log messages.

Sets up the logging machinery and provides methods for logging to the relevant log handlers using the correct log level - to be used in subprocesses. See the cotainr Tracing & Logging documentation page for more details.

Parameters:

namestr

The name to use to identify this log dispatcher in log messages.

map_log_level_funcCallable

A callable that maps a message to a log level to use for the message.

log_settingsLogSettings

The settings to use when setting up the logging machinery.

filterslist of logging.Filter, optional

The filters to add to the log handlers (the default is None with implies that no filters are added to the log handlers).

Attributes:

verbosityint

The cotainr verbosity level used by the log dispatcher.

map_log_levelCallable

The callable that maps a message to a log level to use for the message.

log_file_pathpathlib.Path, optional

The prefix of the file path to save logs to, if specified.

no_colorbool

The indicator of whether or not to disable the coloring of console message.

logger_stdoutlogging.Logger

The logger used to log to stdout.

logger_stderrlogging.Logger

The logger used to log to stderr.

Methods

log_to_stderr(msg)	Log a message to stderr.
log_to_stdout(msg)	Log a message to stdout.
prefix_stderr_name(*, prefix)	Manage a context to prefix the stderr logger name.

log_to_stderr(msg)

Log a message to stderr.

Determines the log level based on the map_log_level function and logs the msg to stderr using that log level.

Parameters:

msgstr

The message to log.

log_to_stdout(msg)

Log a message to stdout.

Determines the log level based on the map_log_level function and logs the msg to stdout using that log level.

Parameters:

msgstr

The message to log.

prefix_stderr_name(*, prefix)

Manage a context to prefix the stderr logger name.

When inside the context, the name of the stderr logger is changed to be prefixed by “prefix/”.

Parameters:

prefixstr

The prefix add to the stderr logger name.

class cotainr.tracing.LogSettings(verbosity: int = 0, log_file_path: Path | None = None, no_color: bool = False)

Bases: object

Dataclass containing settings for a LogDispatcher.

Attributes:

verbosityint, default=0

The cotainr verbosity level used by the log dispatcher.

log_file_pathpathlib.Path, default=None

The prefix of the file path to save logs to, if specified.

no_colorbool, default=False

The indicator of whether or not to disable the coloring of console message.

log_file_path: Path | None = None

no_color: bool = False

verbosity: int = 0

class cotainr.tracing.MessageSpinner(*, msg, stream)

Bases: object

A spinner for console messages.

Creates a thread that continuously updates a prepended spinner to msg on stream. While the spinner is active, the msg is truncated to fit within a single line. When the spinner is stopped, the full msg (without spinner) is written to the stream.

Parameters:

msgstr

The message to prepend with a spinner.

streamio.TextIOWrapper

The text stream on which to spin the message.

Methods

start()	Start the message spinner thread.
stop()	Stop the message spinner thread.

Notes

The spinner is added by continuously rewriting the current console line to update the spinning character prepended to msg. This is done using CR and ANSI escape codes. To avoid interfering with our manipulation of the console line, trailing newlines and ANSI codes, except “Select Graphics Rendition (SGR)” codes used for coloring console lines, are stripped from msg before it is displayed on the console.

start()

Start the message spinner thread.

stop()

Stop the message spinner thread.

class cotainr.tracing.StreamWriteProxy(*, stream)

Bases: object

A proxy for manipulating the write methods of streams.

Provides a write method that guarantees to use the true stream.write method in case stream.write is later monkeypatched. All other method calls to this class are delegated to the corresponding (potentially monkeypatched) methods implemented by stream.

Parameters:

streamio.TextIOWrapper

The text stream to provide a proxy for.

Methods

write(s, /)

Write a string to the stream using the true stream.write method.

Notes

This provides a way for keeping references to the true sys.stdout.write() and sys.stderr.write() methods. This is useful in code that monkeypatches these methods since it is not possible in Python to copy sys.stdout and sys.stderr such that they can later be restored.

write(s, /)

Write a string to the stream using the true stream.write method.

Parameters:

sstr

The string to write.

Returns:

int

The number of characters written.