Logging#

Collection of classes and functions to configuration Python Logger objects, re-purposed to provide detailed status messages during model program execution.

class balsa.logging.LogFormats(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#
class balsa.logging.ModelLogger(name: str, level: int = 0)#
report(msg, *args, **kwargs)#

Report useful model statistics or results to the user. Distinct from .info() which provides status information. Printed in green when colours are available.

subproc_err(msg, *args, **kwargs)#

Report subprocess errors to the user. Distinct from .error() which provides error information.

subproc_message(msg, *args, **kwargs)#

Report subprocess messages to the user. Distinct from .info() which provides status information.

tip(msg, *args, **kwargs)#

Provide a more significant status statement (e.g. new section of the model). Similar to .info(), but more emphasized. Printed in blue when colours are available.

balsa.logging.get_model_logger(name: str) → ModelLogger#

Retrieve a ModelLogger

balsa.logging.init_root(root_name: str, *, stream_format: str | LogFormats = LogFormats.FANCY, log_debug: bool = True) → ModelLogger#

Initialize a ModelLogger

balsa.logging.log_to_file(file_name: str | PathLike, name: str, *, append: bool = False, raw_ascii: bool = False) → Generator#

Context manager for opening and closing a logfile. Cleans up its file handler on exit.

This is especially important during batch runs, because loggers are module-based (e.g. global). Without the cleanup, old file handlers would stick around and get written to.

Parameters:

  • file_name (Union[str, PathLike]) – The filepath of the log file to write to

  • name (str) – The name of the logger to write log records from

  • append (bool, optional) – Defaults to False. Option to append new log records to an existing log file

  • raw_ascii (bool, optional) – Defaults to False. Ensures log file only contains valid ASCII characters