marketflows.logging_utils

Logging helpers.

This module configures the root logger so application code can simply call logging.getLogger(__name__) and emit messages.

Behavior:

  • A file handler is attached at the requested level (default: INFO) and writes to an OS-appropriate directory (XDG_STATE_HOME on Linux/WSL or LOCALAPPDATA on Windows).

  • A stderr handler is attached at WARNING and above.

  • Python warnings are routed through logging (via logging.captureWarnings).

In tutorial mode (is_tutorial=True), log timestamps are made deterministic so test outputs and tutorial logs are reproducible.

Functions

configure_logging(*[, level, node, is_tutorial])

Configure root logging for the application.
marketflows.logging_utils.configure_logging(*, level='INFO', node='', is_tutorial=False)

Configure root logging for the application.

This attaches two handlers to the root logger:

  1. A file handler at level writing to <state-dir>/marketflows/logs/<node>.log. - On Linux/WSL: $XDG_STATE_HOME (fallback: ~/.local/state) - On Windows: %LOCALAPPDATA% (fallback: ~/AppData/Local)

  2. A stderr handler at WARNING and above.

Calling this function multiple times is safe: existing root handlers are removed and closed before new handlers are installed.

Parameters:

  • level (str) – Logging level name (e.g., "DEBUG", "INFO").

  • node (str) – Logical node name used for the log filename.

  • is_tutorial (bool) – If True, use deterministic timestamps and overwrite the log file each run.

Raises:

ValueError – If level is not a valid logging level name.

Return type:

None