cotainr.tracing module#

cotainr - a user space Apptainer/Singularity container builder.

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)	A context manager for prefixing 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)#

A context manager for prefixing 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.

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.

Methods

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

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.

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.

Methods

write(s, /)

Write a string to the stream using the true stream.write method and return the number of characters written.

write(s, /)#

Write a string to the stream using the true stream.write method and return the number of characters written.

Parameters:

sstr: The string to write.