Logging

yosys_mau.task_loop.logging.log(*args, level='info', cls=<class 'yosys_mau.task_loop.logging.LogEvent'>)

Produce log output.

This is done by emitting a LogEvent.

When the task loop is not running anymore or there is no current task, it will directly write to the log files registered with the root task.

Parameters:

  • args (Any) – The message to log, will be converted to strings and joined with spaces.

  • level (Literal['debug', 'info', 'warning', 'error']) – The log level, one of “debug”, “info”, “warning” or “error”. Defaults to “info”. To log at a different level you can also use log_debug, log_warning or log_error. Note that log_error will, by default, also raise an exception.

  • cls (type[LogEvent]) – Customize the event class used. This allows user defined event handlers to only listen to specific types of log messages.

Returns:

The emitted event.

Return type:

LogEvent

yosys_mau.task_loop.logging.log_debug(*args, cls=<class 'yosys_mau.task_loop.logging.LogEvent'>)

Produce debug log output.

This calls log with level="debug".

Parameters:
Return type:

LogEvent

yosys_mau.task_loop.logging.log_warning(*args, cls=<class 'yosys_mau.task_loop.logging.LogEvent'>)

Produce debug log output.

This calls log with level="warning".

Parameters:
Return type:

LogEvent

yosys_mau.task_loop.logging.log_error(*args: Any, cls: type[LogEvent] = LogEvent, raise_error: Literal[True] = True) → NoReturn
yosys_mau.task_loop.logging.log_error(*args: Any, cls: type[LogEvent] = LogEvent, raise_error: Literal[False]) → LogEvent

Produce error log output and optionally raise a LoggedError.

This calls log with level="error" to produce the log output.

Parameters:

raise_error – Whether to raise a LoggedError exception. Defaults to True.

yosys_mau.task_loop.logging.log_exception(exception: BaseException, raise_error: Literal[True] = True) → NoReturn
yosys_mau.task_loop.logging.log_exception(exception: BaseException, raise_error: Literal[False]) → LoggedError

Produce error log output for an exception and optionally raise a LoggedError.

If the exception was already logged, it will not be logged again. When raising a LoggedError, it will have the passed exception as cause, unless it already is a LoggedError in which case it will be re-raised directly.

Parameters:

raise_error – Whether to raise a LoggedError exception. Defaults to True.

Returns:

The LoggedError exception that would be raised if raise_error were True.

yosys_mau.task_loop.logging.start_logging(file=None, err=False, color=None, destination_label=None)

Start logging all log events reaching the current task.

Can be called multiple times to log to multiple destinations.

It is possible to stop logging by closing the file object passed to this function.

Parameters:

  • file (IO[Any] | None) – The file to log to. Defaults to sys.stdout or sys.stderr depending on err.

  • err (bool) – Whether to log to sys.stderr instead of sys.stdout. Defaults to False.

  • color (bool | None) – Whether to use colors. Defaults to True for terminals and False otherwise. When the NO_COLOR environment variable is set, this will be ignored and no colors will be used.

  • destination_label (str | None) – Used to look up destination specific log level filtering. Used with LogContext.destination_levels.

Return type:

None

yosys_mau.task_loop.logging.start_debug_event_logging(file=None, err=False, color=None, include_log=False)
Parameters:
yosys_mau.task_loop.logging.install_root_error_handler()

Installs a fallback error handler in the root task that logs an exception and re-raises it, aborting the root task and therefore the entire task loop.

Context Variables

class yosys_mau.task_loop.logging.LogContext

Context variables to customize logging behavior.

When the default formatter formats a log message, the values of the emitting task are used. This allows setting different values of work_dir, scope, etc. for different tasks.

app_name: str | None = None

The default formatter will prefix all log messages with this if set.

work_dir: str | None = None

Working directory to display as part of log messages.

scope: str | None = None

Scope prefix to display as part of log messages.

quiet: bool = False

Downgrade all info level messages to debug level messages.

When set, the downgrading happens before the LogEvent is emitted.

level: Literal['debug', 'info', 'warning', 'error'] = 'info'

The minimum log level to display/log.

Can be overridden for named destinations with destination_levels.

This does not stop LogEvent of smaller levels to be emitted. It is only used to filter which messages to actually print/log. Hence, it does not affect any user installed LogEvent handlers.

log_format: Callable[[LogEvent], str] = <function default_formatter>

The formatter used to format log messages.

Note that unlike the preceding context variables, this is looked up by the log writing task, not the emitting task.

Parameters:

event (LogEvent)

time_format: Callable[[float], str] = <function default_time_formatter>

The formatter used by the default formatter to format the time of log messages.

This is provided so it can be overridden with a fixed timestamp when running tests that check the log output.

Like log_format this is looked up by the log writing task, not the emitting task.

Parameters:

t (float)

Return type:

str

destination_levels: TaskContextDict[str, Literal['debug', 'info', 'warning', 'error']]

The minimum log level to display/log for named destinations.

Like log_format this is looked up by the log writing task, not the emitting task. If the current destination has no key:value pair in this dictionary, the level will be looked up by the task which emit the log.

Events

class yosys_mau.task_loop.logging.LogEvent(msg: 'str', level: 'Level')

Bases: TaskEvent

Parameters:

  • msg (str)

  • level (Literal['debug', 'info', 'warning', 'error'])

Exceptions

class yosys_mau.task_loop.logging.LoggedError(event)

Bases: Exception

Parameters:

event (LogEvent)