Source code for askemblaex.logging_

"""
Logging configuration for the askemblaex pipeline.

Provides two loggers:

* A **main logger** (``askemblaex``) that writes to a shared log file under
  the output directory's ``logs/`` folder.
* **Per-folder loggers** (``askemblaex.folder.<hash>``) that write to a file
  inside each document's hash-keyed output folder.
"""

from __future__ import annotations

import logging
from pathlib import Path
from typing import Optional


_LOG_FORMAT = (
    "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
)


_LOG_FORMAT = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"




def setup_main_logger(
    log_dir: Path,
    level: int = logging.INFO,
) -> logging.Logger:
    """
    Configure the global ``askemblaex`` logger to write to a file.

    Creates *log_dir* if it does not exist. Idempotent — repeated calls
    do not add duplicate handlers.

    Args:
        log_dir: Directory where ``askemblaex.log`` will be written.
        level:   Logging level (default :data:`logging.INFO`).

    Returns:
        The configured ``askemblaex`` :class:`logging.Logger` instance.
    """
    log_dir.mkdir(parents=True, exist_ok=True)
    log_file = log_dir / "askemblaex.log"

    logger = logging.getLogger("askemblaex")
    logger.setLevel(level)
    logger.propagate = False

    if not logger.handlers:
        handler = logging.FileHandler(log_file, encoding="utf-8")
        handler.setFormatter(logging.Formatter(_LOG_FORMAT))
        logger.addHandler(handler)

    return logger




def get_folder_logger(
    folder: Path,
    *,
    log_name: str,
    level: int = logging.INFO,
) -> logging.Logger:
    """
    Create or retrieve a per-document logger that writes to ``<folder>/<log_name>.log``.

    Idempotent — if a logger with the same name already has handlers, the
    existing instance is returned unchanged.

    Args:
        folder:   Hash-keyed document output folder. Created if absent.
        log_name: Base name for the log file (usually the document hash).
        level:    Logging level (default :data:`logging.INFO`).

    Returns:
        A :class:`logging.Logger` named ``askemblaex.folder.<log_name>``.
    """
    folder.mkdir(parents=True, exist_ok=True)
    log_file = folder / f"{log_name}.log"

    logger_name = f"askemblaex.folder.{log_name}"
    logger = logging.getLogger(logger_name)
    logger.setLevel(level)
    logger.propagate = False

    if not logger.handlers:
        handler = logging.FileHandler(log_file, encoding="utf-8")
        handler.setFormatter(logging.Formatter(_LOG_FORMAT))
        logger.addHandler(handler)

    return logger