# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
# See LICENSE for details.
"""Convenience API for log level encoding, decoding, and type metadata.

``LogLevelCoder`` bundles the ``Literal`` type, default value, valid values
list, and encode/decode functions into a single importable object. This is
especially useful in Pydantic models where a Field definition needs the type
annotation, default, description text, and runtime conversion all in one
place::

    from vcti.logging import LogLevelCoder

    class Config(BaseModel):
        log_level: LogLevelCoder.Literal = Field(
            default=LogLevelCoder.default,
            description=f"Supported: {'/'.join(LogLevelCoder.list)}",
        )

The underlying encoding logic lives in :mod:`vcti.logging.log_level`.
"""

from .log_level import (
    DEFAULT_LOG_LEVEL_STR,
    LOG_LEVEL_VALUES,
    LogLevel,
    LogLevelStr,
    decode_log_level,
    encode_log_level,
)


class LogLevelCoder:
    """Log level encoder/decoder with type metadata.

    Provides a single import that bundles everything needed for declaring,
    validating, and converting log level values:

    - ``Literal`` — the ``Literal["notset", "trace", ...]`` type alias
    - ``default`` — the default log level string (``"info"``)
    - ``list`` — all valid log level strings
    - ``encode()`` — convert a :class:`LogLevel` enum to its string name
    - ``decode()`` — convert a string name to a :class:`LogLevel` enum
    """

    Literal = LogLevelStr
    default = DEFAULT_LOG_LEVEL_STR
    list = LOG_LEVEL_VALUES

    @staticmethod
    def encode(level: LogLevel) -> str:
        """Convert a LogLevel enum member to its string representation.

        Args:
            level: The LogLevel enum member to encode.

        Returns:
            Lowercase string name (e.g., ``"info"``, ``"debug"``).
        """
        return encode_log_level(level)

    @staticmethod
    def decode(value: str) -> LogLevel:
        """Convert a string name to a LogLevel enum member.

        The lookup is case-insensitive.

        Args:
            value: Level name (e.g., ``"info"``, ``"INFO"``).

        Returns:
            The corresponding LogLevel enum member.

        Raises:
            ValueError: If *value* doesn't match any log level.
        """
        return decode_log_level(value)
