"""Structured logging wrapper with performance optimizations.

This module provides a logger wrapper that:
1. Avoids dict allocation when logging is disabled (performance)
2. Provides clean kwargs API for structured fields (usability)
3. Centralizes logging logic for future enhancements (maintainability)
"""

from __future__ import annotations

import logging

from typing import Any


class StructuredLogger:
    """Logger wrapper that avoids allocations when logging is disabled.

    This wrapper checks if a log level is enabled before allocating the extra
    dict, providing performance benefits in high-throughput code paths where
    logging is typically disabled (e.g., DEBUG logs in production).

    The wrapper preserves all standard logging behavior including module names,
    logger hierarchy, and filtering.

    Args:
        logger: Standard library logger instance

    Example:
        >>> logger = get_logger(__name__)
        >>> logger.info("Request completed", status=200, duration=0.5)
        >>> logger.debug("Headers", headers={"Content-Type": "application/json"})
    """

    def __init__(self, logger: logging.Logger):
        self._logger = logger

    def debug(self, msg: str, **fields: Any) -> None:
        """Log debug message with structured fields.

        Args:
            msg: Log message
            **fields: Structured fields to include as extra context
        """
        if self._logger.isEnabledFor(logging.DEBUG):
            self._logger.debug(msg, extra=fields)

    def info(self, msg: str, **fields: Any) -> None:
        """Log info message with structured fields.

        Args:
            msg: Log message
            **fields: Structured fields to include as extra context
        """
        if self._logger.isEnabledFor(logging.INFO):
            self._logger.info(msg, extra=fields)

    def warning(self, msg: str, **fields: Any) -> None:
        """Log warning message with structured fields.

        Args:
            msg: Log message
            **fields: Structured fields to include as extra context
        """
        if self._logger.isEnabledFor(logging.WARNING):
            self._logger.warning(msg, extra=fields)

    def error(self, msg: str, **fields: Any) -> None:
        """Log error message with structured fields.

        Args:
            msg: Log message
            **fields: Structured fields to include as extra context
        """
        if self._logger.isEnabledFor(logging.ERROR):
            self._logger.error(msg, extra=fields)

    def exception(self, msg: str, **fields: Any) -> None:
        """Log exception with structured fields.

        Should be called from an exception handler to include traceback.

        Args:
            msg: Log message
            **fields: Structured fields to include as extra context
        """
        if self._logger.isEnabledFor(logging.ERROR):
            self._logger.exception(msg, extra=fields)


def get_logger(name: str) -> StructuredLogger:
    """Get a structured logger for the given module name.

    Args:
        name: Logger name (typically __name__)

    Returns:
        StructuredLogger instance wrapping stdlib logger

    Example:
        >>> logger = get_logger(__name__)
        >>> logger.info("Operation completed", count=10)
    """
    return StructuredLogger(logging.getLogger(name))
