social-data-attribution-w2/src/data_attribution/cli/config.py

"""Shared CLI configuration helpers."""

from __future__ import annotations

import datetime as _dt
import logging
from pathlib import Path
from typing import Any, Dict

try:
    import tomllib
except ModuleNotFoundError:  # Python < 3.11
    import tomli as tomllib  # type: ignore[no-redef]


def configure_logging(verbose: bool = False) -> None:
    """Configure application-wide logging.

    Uses INFO level by default and DEBUG when ``verbose`` is True.
    """

    level = logging.DEBUG if verbose else logging.INFO
    logging.basicConfig(
        level=level,
        format="%(asctime)s [%(levelname)s] %(name)s - %(message)s",
    )


def default_run_id(prefix: str = "run", timestamp: _dt.datetime | None = None) -> str:
    """Produce a monotonically sortable run identifier."""

    ts = timestamp or _dt.datetime.now(tz=_dt.timezone.utc)
    return f"{prefix}-{ts.strftime('%Y%m%dT%H%M%SZ')}"


def load_config(path: Path | None) -> Dict[str, Any]:
    """Load configuration from a YAML or TOML file.

    Parameters
    ----------
    path:
        Path to a configuration file. ``None`` returns an empty mapping.

    Returns
    -------
    dict
        Parsed configuration content.

    Raises
    ------
    FileNotFoundError
        If ``path`` is provided but does not exist.
    ValueError
        If the extension is unsupported.
    RuntimeError
        If YAML parsing is requested without PyYAML available.
    """

    if path is None:
        return {}

    if not path.exists():
        raise FileNotFoundError(f"Config file not found: {path}")

    suffix = path.suffix.lower()
    if suffix in {".yaml", ".yml"}:
        try:
            import yaml  # type: ignore
        except ModuleNotFoundError as exc:  # pragma: no cover - import guard
            raise RuntimeError(
                "PyYAML is required for YAML configuration support."
            ) from exc

        with path.open("r", encoding="utf-8") as stream:
            return yaml.safe_load(stream) or {}

    if suffix == ".toml":
        with path.open("rb") as stream:
            return tomllib.load(stream) or {}

    raise ValueError(f"Unsupported configuration format: {path.suffix}")


__all__ = ["configure_logging", "default_run_id", "load_config"]