pterasoftware.set_up_logging()

pterasoftware.set_up_logging(
level: int | str = 30,
handler: Handler | None = None,
format_string: str | None = None,
) → Logger

Configures logging for the pterasoftware package.

Call this function when you want to see log messages from pterasoftware. Without it, log messages are silently discarded (the package installs a null handler, per the standard pattern for libraries).

If you want log messages printed to the console, call this function without passing a handler (e.g., ps.set_up_logging(level="Info")). This installs a handler that is compatible with TQDM progress bars, so log messages and progress bars can coexist on the console without garbling each other.

If you want log messages written to a file (while any progress bars continue to display on the console), pass a logging.FileHandler (e.g., ps.set_up_logging(level="Info", handler=logging.FileHandler("simulation.log"))).

Parameters:

  • level – The logging level. Can be an int (e.g., logging.DEBUG) or a string (either “debug”, “info”, “warning”, “error”, or “critical”, case insensitive). The default is logging.WARNING.

  • handler – A custom logging handler. If None, a TQDM compatible handler is created that prints to the console without interfering with progress bars. Pass a handler (such as logging.FileHandler) to route log messages elsewhere.

  • format_string – Custom format string for log messages. If None, uses the format “%(levelname)-8s|%(display_name)-<width>s|%(message)s”, where display_name is the logger’s name with the leading “pterasoftware.” stripped. The level name is right padded to the width of the longest standard level name (CRITICAL) and the display name to the width of the package’s longest possible module logger display name, so the messages align across levels and modules. Custom format strings may also reference %(display_name)s.

Returns:

The configured package level logger.