Source code for psipose.logging

"""Opt-in loguru diagnostics for psipose."""

from __future__ import annotations

import sys
from typing import Any

from loguru import logger as _logger

_HANDLER_ID: int | None = None
_DEFAULT_FORMAT = (
    "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
    "<level>{level: <8}</level> | "
    "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
    "<level>{message}</level>"
)

_logger.disable("psipose")




def configure_logging(
    *,
    sink: Any = None,
    level: str = "INFO",
    format: str = _DEFAULT_FORMAT,
    replace: bool = True,
    **kwargs,
) -> int:
    """Configure loguru output for psipose diagnostics.

    Parameters
    ----------
    sink : object, optional
        Loguru sink. Defaults to ``sys.stderr``.
    level : str, default="INFO"
        Minimum log level for emitted records.
    format : str, default=_DEFAULT_FORMAT
        Loguru message format.
    replace : bool, default=True
        Whether to remove existing loguru handlers before adding this sink.
    **kwargs
        Additional keyword arguments passed to ``loguru.logger.add``.

    Returns
    -------
    int
        The loguru handler id.
    """
    global _HANDLER_ID

    if sink is None:
        sink = sys.stderr
    if replace:
        _logger.remove()
        _HANDLER_ID = None

    _HANDLER_ID = _logger.add(sink, level=level, format=format, **kwargs)
    _logger.enable("psipose")
    return _HANDLER_ID





def disable_logging() -> None:
    """Disable psipose diagnostics and remove the configured handler."""
    global _HANDLER_ID

    if _HANDLER_ID is not None:
        _logger.remove(_HANDLER_ID)
        _HANDLER_ID = None
    _logger.disable("psipose")





def get_logger(name: str = "psipose"):
    """Return a loguru logger bound with psipose context."""
    return _logger.bind(package="psipose", component=name)