ncaa_eval.utils.logger module

Structured logging with configurable verbosity levels.

Provides project-wide logging configuration using Python’s standard logging module. Four verbosity levels map to standard (and one custom) Python log levels:

Usage:

Configure once at application startup, then obtain named loggers anywhere in the codebase:

>>> from ncaa_eval.utils.logger import configure_logging, get_logger
>>> configure_logging("VERBOSE")
>>> log = get_logger("ingest")
>>> log.info("Loading data...")

The verbosity can also be controlled via the NCAA_EVAL_LOG_LEVEL environment variable (case-insensitive). An explicit level argument to configure_logging takes precedence over the environment variable, which in turn takes precedence over the default (NORMAL).

ncaa_eval.utils.logger.DEBUG: int = 10

Full diagnostic output (maps to DEBUG=10).

ncaa_eval.utils.logger.NORMAL: int = 20

Default project verbosity (maps to INFO=20).

ncaa_eval.utils.logger.QUIET: int = 30

Project verbosity that suppresses routine output (maps to WARNING=30).

ncaa_eval.utils.logger.VERBOSE: int = 15

Custom log level between INFO and DEBUG for detailed operational output.

ncaa_eval.utils.logger.configure_logging(level: str | None = None) → None

Configure project-wide logging with the given verbosity level.

Resolution order:

1. Explicit level argument (if not None).

2. NCAA_EVAL_LOG_LEVEL environment variable.

3. "NORMAL" default.

Parameters:

level – One of "QUIET", "NORMAL", "VERBOSE", or "DEBUG" (case-insensitive). None means fall through to the environment variable or default.

Raises:

ValueError – If the resolved level name is not recognised.

Example

>>> from ncaa_eval.utils.logger import configure_logging, get_logger
>>> configure_logging("VERBOSE")
>>> log = get_logger("ingest")
>>> log.info("Loading data...")

ncaa_eval.utils.logger.get_logger(name: str) → Logger

Return a logger under the ncaa_eval hierarchy.

Parameters:

name – Dot-separated path appended to the root ncaa_eval logger (e.g. "transform.features" yields ncaa_eval.transform.features).

Returns:

A logging.Logger instance.

Example

>>> log = get_logger("transform.features")
>>> log.info("Computing features for season %d", 2025)