src/utils/logging.py

"""
Logging helper functions for consistent, centralized log formatting.

This module provides helper functions to reduce verbose multi-line logging
statements in the main code, improving readability while maintaining
detailed log output.
"""

import logging
from typing import List, Optional, TYPE_CHECKING

if TYPE_CHECKING:
    from tracking import PlayEvent


def log_flag_plays(flag_plays: List["PlayEvent"], logger_instance: logging.Logger) -> None:
    """
    Log details of FLAG plays in a consistent format.

    Args:
        flag_plays: List of FLAG PlayEvent objects to log
        logger_instance: Logger to use for output
    """
    for fp in flag_plays:
        logger_instance.info(
            "  FLAG: %.1fs - %.1fs (duration=%.1fs)",
            fp.start_time,
            fp.end_time,
            fp.end_time - fp.start_time,
        )


def log_play_complete(play: "PlayEvent", method: str, logger_instance: logging.Logger) -> None:
    """
    Log when a play is completed (via backward calc or capped).

    Replaces 7-line logging blocks like:
        logger.info(
            "Play #%d complete (backward calc, %s): %.1fs - %.1fs (duration: %.1fs)",
            play.play_number, play.play_type, play.start_time, play.end_time,
            play.end_time - play.start_time,
        )

    Args:
        play: The completed PlayEvent
        method: Completion method ("backward_calc" or "capped")
        logger_instance: Logger to use for output
    """
    logger_instance.info(
        "Play #%d complete (%s, %s): %.1fs - %.1fs (duration: %.1fs)",
        play.play_number,
        method,
        play.play_type,
        play.start_time,
        play.end_time,
        play.end_time - play.start_time,
    )


def log_play_created(
    play: "PlayEvent",
    play_type: str,
    logger_instance: logging.Logger,
    extra_info: Optional[str] = None,
) -> None:
    """
    Log when a play is created (timeout, special, turnover, etc.).

    Replaces 6-7 line logging blocks like:
        logger.info(
            "Play #%d created (special): %.1fs - %.1fs (duration: %.1fs, end_method: %s)",
            play.play_number, play.start_time, play.end_time,
            play.end_time - play.start_time, end_method,
        )

    Args:
        play: The created PlayEvent
        play_type: Type description ("timeout, home", "special", "normal, turnover")
        logger_instance: Logger to use for output
        extra_info: Optional additional info to append (e.g., end_method)
    """
    duration = play.end_time - play.start_time
    if extra_info:
        logger_instance.info(
            "Play #%d created (%s): %.1fs - %.1fs (duration: %.1fs, %s)",
            play.play_number,
            play_type,
            play.start_time,
            play.end_time,
            duration,
            extra_info,
        )
    else:
        logger_instance.info(
            "Play #%d created (%s): %.1fs - %.1fs (duration: %.1fs)",
            play.play_number,
            play_type,
            play.start_time,
            play.end_time,
            duration,
        )