Logging

grid_doctor provides a small logging helper so applications and scripts can configure a consistent logging setup without repeating boilerplate.

Logging setup

Use this function to initialize logging for interactive use, scripts, or batch workflows.

setup_logging(verbosity=0, level=None, fmt=_DEFAULT_FORMAT, datefmt=_DEFAULT_DATE_FORMAT)

Configure the root handler and set the global log level.

Call this once at program startup.

Parameters:

Name	Type	Description	Default
verbosity	int	Number of -v flags. Each step moves one rung towards DEBUG on the verbosity ladder.	0
level	int, str, or None	Explicit level — overrides verbosity when given.	None
fmt	str	:mod:logging format string.	_DEFAULT_FORMAT
datefmt	str	Date format string.	_DEFAULT_DATE_FORMAT

Source code in .tox/docs/lib/python3.13/site-packages/grid_doctor/log.py

def setup_logging(
    verbosity: int = 0,
    level: Union[int, str, None] = None,
    fmt: str = _DEFAULT_FORMAT,
    datefmt: str = _DEFAULT_DATE_FORMAT,
) -> None:
    """Configure the root handler and set the global log level.

    Call this **once** at program startup.

    Parameters
    ----------
    verbosity : int, optional
        Number of ``-v`` flags.  Each step moves one rung towards
        ``DEBUG`` on the verbosity ladder.
    level : int, str, or None, optional
        Explicit level — overrides *verbosity* when given.
    fmt : str, optional
        :mod:`logging` format string.
    datefmt : str, optional
        Date format string.
    """
    if not logging.root.handlers:
        handler = logging.StreamHandler()
        handler.setFormatter(logging.Formatter(fmt, datefmt=datefmt))
        logging.root.addHandler(handler)

    if level is not None:
        set_level(level)
    else:
        global _current_index
        _current_index = _DEFAULT_INDEX + verbosity
        _current_index = max(0, min(_current_index, len(_LEVELS) - 1))
        _apply_level(_LEVELS[_current_index])