API for balsa.scribe

class ModelLogger(logging.Logger):
    def report(self, msg: str, *args, **kwargs)

Subclass of the standard Python Logger object. In addition to the usual info(), warning(), debug() and error() methods, this class adds a custom level "REPORT" with its own method. The purpose of this special level is to distinguish between logged model results and logged model status. For example, logging that the model completed its traffic assignment should be logged at the INFO level, but the convergence criterion and value should be logged at the REPORT level.

---

def get_root_logger(root_name: str) -> ModelLogger

Gets the root model logger for a defined name. This is similar to the standard getLogger() method but it also sets up the logger's formatting rules. At the start of the model run, somewhere the root logger should be called. For example, in the TRESO project, the root logger is called:

root_logger = get_root_logger('treso')

Modules in the same framework should inherit from the root logger using the standard namespace rules (see get_model_logger() below)

Scribe's loggers are setup to log all levels, with levels WARN and higher logged to sys.stderr, and with lower levels being logged to sys.stdout. The format for log statements is "%(asctime)s %(levelname)s %(name)s -> %(message)s". For example, a logger with the namespace "gghm.BaseTolls", logging at the INFO level would produce the following message:

2017-04-05 17:33:54,698 INFO gghm.BaseTolls -> Computing road tolls for AM Peak

Ideally, messages should be kept to one-line, to facilitate the parsing of the log file after a model run. Multi-line reports belong as files in the model's output directory.

---

def get_model_logger(name: str):

Retrieves the model logger for the specified namespace, using getLogger(). Ideally the name for the logger should be <root_name>.<class_name> for a class-based module, where the root logger was defined elsewhere in the code.

---

def remove_jupyter_handler():

When running a model API from a Jupyter Notebook, often the Notebook will duplicate each log message. So every statement is repeated twice. Calling this function once at the start of your Jupyter Notebook fixes this problem.

---

@contextmanager
def log_to_file(log_file: Union[Path, str], logger=None):

Context manager for adding a file handler to the logging system. If logger is not provided, it will default to the root logger.

Args: log_file: Path to the log file. logger (Logger): An optional logger to add the file handler to.