src/fpgm/utils/logging.py

"""Consistent logging setup shared by library code and CLI scripts alike."""

from __future__ import annotations

import logging

_FORMAT = "%(asctime)s %(levelname)-7s %(name)s: %(message)s"
_DATEFMT = "%H:%M:%S"

_configured = False


def setup_logging(level: int | str = logging.INFO) -> None:
    """Attach a stream handler to the ``fpgm`` root logger.

    Safe to call more than once (e.g. once from library import time, again
    explicitly from a CLI's ``main()`` to change the level): the handler is
    only ever added on the first call, later calls just adjust the level.
    """
    global _configured
    root = logging.getLogger("fpgm")
    if _configured:
        root.setLevel(level)
        return
    handler = logging.StreamHandler()
    handler.setFormatter(logging.Formatter(_FORMAT, datefmt=_DATEFMT))
    root.addHandler(handler)
    root.setLevel(level)
    root.propagate = False  # avoid duplicate lines if the host app also configures root
    _configured = True


def get_logger(name: str) -> logging.Logger:
    """A logger under the ``fpgm`` namespace, configuring defaults on first use."""
    if not _configured:
        setup_logging()
    qualified = name if name == "fpgm" or name.startswith("fpgm.") else f"fpgm.{name}"
    return logging.getLogger(qualified)