Source code for libretro.api.log

r"""
Types for allowing :class:`.Core`\s to log messages.

.. seealso::
    :class:`.LogDriver`
        The protocol that uses these types to implement logging support in libretro.py.

    :mod:`libretro.drivers.log`
        libretro.py's included :class:`.LogDriver` implementations.
"""

import logging
from ctypes import Structure, c_int
from dataclasses import dataclass
from enum import IntEnum

from libretro.ctypes import CIntArg, CStringArg, TypedFunctionPointer

RETRO_LOG_DEBUG = 0
RETRO_LOG_INFO = RETRO_LOG_DEBUG + 1
RETRO_LOG_WARN = RETRO_LOG_INFO + 1
RETRO_LOG_ERROR = RETRO_LOG_WARN + 1
RETRO_LOG_DUMMY = 0x7FFFFFFF

retro_log_level = c_int


retro_log_printf_t = TypedFunctionPointer[None, [CIntArg[retro_log_level], CStringArg]]
"""
Log a message at the given severity level.

Registered by the :term:`frontend` and called by the :term:`core`
to write a ``printf``-style message to the frontend's log.

:param level: A :class:`.LogLevel` that classifies the severity of the message.
:param fmt: The format string to log, as a :obj:`bytes`-like object.

.. warning::
    :c:type:`retro_log_printf_t` normally has ``printf``-style variadic arguments,
    but :mod:`!ctypes` :python-issue:`doesn't currently support variadic callbacks <135620>`.

    As a workaround, your :class:`.Core` can format log messages with ``sprintf`` or similar,
    then pass the result as the format string.

Corresponds to :c:type:`retro_log_printf_t` in ``libretro.h``.

.. seealso::
    :attr:`.LogDriver.log`
        The suggested entry point for this callback in libretro.py.
"""




class LogLevel(IntEnum):
    """
    libretro's defined log severity levels.

    Corresponds to :c:type:`retro_log_level` in ``libretro.h``.
    """

    DEBUG = RETRO_LOG_DEBUG
    INFO = RETRO_LOG_INFO
    WARNING = RETRO_LOG_WARN
    ERROR = RETRO_LOG_ERROR

    @property
    def logging_level(self) -> int:
        """
        Returns the equivalent :mod:`logging` level.

        >>> import logging
        >>> from libretro.api import LogLevel
        >>> LogLevel.WARNING.logging_level == logging.WARN
        True
        """
        match self:
            case self.DEBUG:
                return logging.DEBUG
            case self.INFO:
                return logging.INFO
            case self.WARNING:
                return logging.WARN
            case self.ERROR:
                return logging.ERROR





@dataclass(init=False, slots=True)
class retro_log_callback(Structure):
    """
    Provides the :class:`.Core` with a logging function.

    Corresponds to :c:type:`retro_log_callback` in ``libretro.h``.
    """

    log: retro_log_printf_t | None
    """
    A printf-style logging function. Set by the frontend.

    .. seealso::
        :attr:`.LogDriver.log`
            The suggested entry point for this callback in libretro.py.
    """

    _fields_ = (("log", retro_log_printf_t),)



    def __deepcopy__(self, _):
        """
        Return a copy of this object.
        Intended for use with :func:`copy.deepcopy`.
        """
        return retro_log_callback(self.log)




__all__ = [
    "LogLevel",
    "retro_log_callback",
    "retro_log_printf_t",
    "retro_log_level",
]