"""
Centralized logging utility module for BIPAuto project.

Provides a standardized logger configuration for consistent logging across
all BIPAuto components. Supports console output with optional file logging.

Basic usage examples:

    # Basic usage - console logging at INFO level
    from utils.logging import get_logger
    logger = get_logger('bipauto.auth')
    logger.info('Login successful')

    # With debug level for detailed output
    logger = get_logger('bipauto.extractor', level=logging.DEBUG)
    logger.debug('Processing batch 1 of 5...')

    # With file output for persistent logs
    logger = get_logger('bipauto.app', level=logging.INFO, log_file='app.log')
    logger.info('Application started')

Logger naming convention:
    Use hierarchical names with 'bipauto.' prefix:
    - 'bipauto.auth' - Authentication module
    - 'bipauto.extractor' - Material plan extractor
    - 'bipauto.converter' - Excel converter
    - 'bipauto.utils' - Utility functions
"""

import logging
from typing import Optional


def get_logger(
    name: str,
    level: int = logging.INFO,
    log_file: Optional[str] = None
) -> logging.Logger:
    """
    Create and configure a logger with console and optional file handlers.

    Args:
        name: Logger name (use hierarchical naming, e.g., 'bipauto.auth')
        level: Logging level (default: logging.INFO)
        log_file: Optional path to log file. If None, only console output.

    Returns:
        Configured logging.Logger instance

    Example:
        >>> logger = get_logger('bipauto.auth')
        >>> logger.info('User logged in')
        [INFO] bipauto.auth: User logged in
    """
    logger = logging.getLogger(name)
    logger.setLevel(level)

    # Avoid adding duplicate handlers if logger already configured
    if logger.handlers:
        return logger

    # Create formatter
    formatter = logging.Formatter("[%(levelname)s] %(name)s: %(message)s")

    # Console handler (always added)
    console_handler = logging.StreamHandler()
    console_handler.setLevel(level)
    console_handler.setFormatter(formatter)
    logger.addHandler(console_handler)

    # File handler (optional)
    if log_file:
        file_handler = logging.FileHandler(log_file)
        file_handler.setLevel(level)
        file_handler.setFormatter(formatter)
        logger.addHandler(file_handler)

    # Prevent log propagation to root logger (avoids duplicate output)
    logger.propagate = False

    return logger