#!/usr/bin/env python3
# --------------------( LICENSE                            )--------------------
# Copyright (c) 2014-2025 Beartype authors.
# See "LICENSE" for further details.

'''
Beartype **configuration class testers** (i.e., low-level callables testing and
validating various metadata of interest to the high-level
:class:`beartype.BeartypeConf` dataclass).

This private submodule is *not* intended for importation by downstream callers.
'''

# ....................{ IMPORTS                            }....................
import beartype
from beartype.roar import (
    BeartypeConfException,
    BeartypeConfParamException,
    BeartypeCallHintParamViolation,
    BeartypeCallHintReturnViolation,
    BeartypeDoorHintViolation,
)
from beartype._cave._cavemap import NoneTypeOr
from beartype._conf.confenum import (
    BeartypeStrategy,
    BeartypeViolationVerbosity,
)
from beartype._conf.decorplace.confplaceenum import BeartypeDecorPlace
from beartype._conf._confoverrides import sanify_conf_kwargs_is_pep484_tower
from beartype._data.typing.datatyping import (
    DictStrToAny,
    TypeException,
)
from beartype._util.cls.utilclstest import is_type_subclass
from beartype._util.error.utilerrwarn import issue_warning
from beartype._util.kind.maplike.utilmapfrozen import FrozenDict
from beartype._util.text.utiltextidentifier import is_identifier
from collections.abc import (
    Collection as CollectionABC,
)

# ....................{ DEFAULTERS                         }....................
def default_conf_kwargs(conf_kwargs: DictStrToAny) -> None:
    '''
    Default all parameters not explicitly passed by the user in the passed
    dictionary of configuration parameters to sane internal defaults *before*
    the :func:`.die_if_conf_kwargs_invalid` raiser validates these parameters.

    Parameters
    ----------
    conf_kwargs : Dict[str, object]
        Dictionary mapping from the names to values of *all* possible keyword
        parameters configuring this configuration.
    '''
    assert isinstance(conf_kwargs, dict), f'{repr(conf_kwargs)} not dictionary.'

    # ..................{ DEFAULT ~ violation_*type          }..................
    # Default violation type if passed *OR* "None" if unpassed.
    violation_type = conf_kwargs['violation_type']

    # If...
    if (
        # The caller explicitly passed a default violation type...
        violation_type is not None and
        # That is *NOT* an exception subclass...
        not is_type_subclass(violation_type, Exception)
    # Raise an exception.
    ):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "violation_type" value '
            f'{repr(violation_type)} not exception type.'
        )
    # Else, the caller either passed *NO* default violation type or passed a
    # valid default violation type.

    # If the caller did *NOT* explicitly pass a DOOR violation type, default
    # this type to either the default violation type if passed *OR* the default
    # DOOR violation type if unpassed.
    if conf_kwargs['violation_door_type'] is None:
        conf_kwargs['violation_door_type'] = (
            violation_type or BeartypeDoorHintViolation)
    # Else, the caller explicitly passed a DOOR violation type.

    # If the caller did *NOT* explicitly pass a parameter violation type,
    # default this type to either the default violation type if passed *OR* the
    # default DOOR violation type if unpassed.
    if conf_kwargs['violation_param_type'] is None:
        conf_kwargs['violation_param_type'] = (
            violation_type or BeartypeCallHintParamViolation)

    # If the caller did *NOT* explicitly pass a return violation type, default
    # this type to either the default violation type if passed *OR* the default
    # DOOR violation type if unpassed.
    if conf_kwargs['violation_return_type'] is None:
        conf_kwargs['violation_return_type'] = (
            violation_type or BeartypeCallHintReturnViolation)
    # Else, the caller explicitly passed a DOOR violation type.

# ....................{ RAISERS                            }....................
def die_unless_conf(
    # Mandatory parameters.
    conf: 'beartype.BeartypeConf',

    # Optional parameters.
    exception_cls: TypeException = BeartypeConfException,
) -> None:
    '''
    Raise an exception unless the passed object is a beartype configuration.

    Parameters
    ----------
    conf : beartype.BeartypeConf
        Object to be validated.
    exception_cls : Type[Exception]
        Type of exception to be raised in the event of a fatal error. Defaults
        to :exc:`._BeartypeConfException`.

    Raises
    ------
    exception_cls
        If this object is *not* a beartype configuration.
    '''

    # Avoid circular import dependencies.
    from beartype._conf.confmain import BeartypeConf

    # If this object is *NOT* a configuration, raise an exception.
    if not isinstance(conf, BeartypeConf):
        assert isinstance(exception_cls, type), (
            f'{repr(exception_cls)} not exception type.')

        raise exception_cls(
            f'Beartype configuration {repr(conf)} invalid '
            f'(i.e., not "beartype.BeartypeConf" instance).'
        )
    # Else, this object is a configuration.


def die_if_conf_kwargs_invalid(conf_kwargs: DictStrToAny) -> None:
    '''
    Raise an exception if one or more configuration parameters in the passed
    dictionary of such parameters are invalid.

    Parameters
    ----------
    conf_kwargs : Dict[str, object]
        Dictionary mapping from the names to values of *all* possible keyword
        parameters configuring this configuration.

    Raises
    ------
    BeartypeConfParamException
        If one or more configurations parameter in this dictionary are invalid.
    '''

    # ..................{ VALIDATE                           }..................
    # If "claw_decor_place_func" is *NOT* an enumeration member, raise
    # an exception.
    if not isinstance(
        conf_kwargs['claw_decor_place_func'],
        BeartypeDecorPlace
    ):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "claw_decor_place_func" '
            f'value {repr(conf_kwargs["claw_decor_place_func"])} not '
            f'"beartype.BeartypeDecorPlace" enumeration member.'
        )
    # Else, "claw_decor_place_func" is an enumeration member.
    #
    # If "claw_decor_place_type" is *NOT* an enumeration member, raise
    # an exception.
    elif not isinstance(
        conf_kwargs['claw_decor_place_type'],
        BeartypeDecorPlace
    ):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "claw_decor_place_type" '
            f'value {repr(conf_kwargs["claw_decor_place_type"])} not '
            f'"beartype.BeartypeDecorPlace" enumeration member.'
        )
    # Else, "claw_decor_place_type" is an enumeration member.
    #
    # If "claw_is_pep526" is *NOT* a boolean, raise an exception.
    elif not isinstance(conf_kwargs['claw_is_pep526'], bool):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "claw_is_pep526" '
            f'value {repr(conf_kwargs["claw_is_pep526"])} not boolean.'
        )
    # Else, "claw_is_pep526" is a boolean.
    #
    # If "claw_skip_package_names" is *NOT* an iterable of non-empty strings,
    # raise an exception. Specifically, if the value of this parameter is not...
    elif not (
        # A collection *AND*...
        isinstance(conf_kwargs['claw_skip_package_names'], CollectionABC) and
        all(
            (
                # This item is a string *AND*...
                isinstance(claw_skip_package_name, str) and
                # This string is a "."-delimited Python identifier...
                is_identifier(claw_skip_package_name)
            )
            # For each item of this iterable.
            for claw_skip_package_name in conf_kwargs['claw_skip_package_names']
        )
    ):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "claw_skip_package_names" '
            f'value {repr(conf_kwargs["claw_skip_package_names"])} not '
            f'collection of "."-delimited Python identifiers.'
        )
    # Else, "claw_skip_package_names" is an iterable of non-empty strings.
    #
    # If "hint_overrides" is *NOT* a frozen dict, raise an exception.
    elif not isinstance(conf_kwargs['hint_overrides'], FrozenDict):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "hint_overrides" '
            f'value {repr(conf_kwargs["hint_overrides"])} not '
            f'frozen dictionary '
            f'(i.e., "beartype.FrozenDict" instance).'
        )
    # Else, "hint_overrides" is a frozen dict.
    #
    # If "is_pep557_fields" is *NOT* a boolean, raise an exception.
    elif not isinstance(conf_kwargs['is_pep557_fields'], bool):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "is_pep557_fields" '
            f'value {repr(conf_kwargs["is_pep557_fields"])} not boolean.'
        )
    # Else, "is_pep557_fields" is a boolean.
    #
    # If "is_color" is *NOT* a tri-state boolean, raise an exception.
    elif not isinstance(conf_kwargs['is_color'], NoneTypeOr[bool]):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "is_color" '
            f'value {repr(conf_kwargs["is_color"])} not tri-state boolean '
            f'(i.e., "True", "False", or "None").'
        )
    # Else, "is_color" is a tri-state boolean.
    #
    # If "is_debug" is *NOT* a boolean, raise an exception.
    elif not isinstance(conf_kwargs['is_debug'], bool):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "is_debug" '
            f'value {repr(conf_kwargs["is_debug"])} not boolean.'
        )
    # Else, "is_debug" is a boolean.
    #
    # If "is_pep484_tower" is *NOT* a boolean, raise an exception.
    elif not isinstance(conf_kwargs['is_pep484_tower'], bool):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "is_pep484_tower" '
            f'value {repr(conf_kwargs["is_debug"])} not boolean.'
        )
    # Else, "is_pep484_tower" is a boolean.
    #
    # If "strategy" is *NOT* an enumeration member, raise an exception.
    elif not isinstance(conf_kwargs['strategy'], BeartypeStrategy):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "strategy" '
            f'value {repr(conf_kwargs["strategy"])} not '
            f'"beartype.BeartypeStrategy" enumeration member.'
        )
    # Else, "strategy" is an enumeration member.
    #
    # If "violation_verbosity" is *NOT* an enumeration member, raise an
    # exception.
    elif not isinstance(
        conf_kwargs['violation_verbosity'], BeartypeViolationVerbosity):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter "violation_verbosity" '
            f'value {repr(conf_kwargs["violation_verbosity"])} not '
            f'"beartype.BeartypeViolationVerbosity" enumeration member.'
        )
    # Else, "violation_verbosity" is an enumeration member.
    #
    # If "warning_cls_on_decorator_exception" is neither "None" *NOR* a
    # warning category, raise an exception.
    elif not (
        conf_kwargs['warning_cls_on_decorator_exception'] is None or
        is_type_subclass(
            conf_kwargs['warning_cls_on_decorator_exception'], Warning)
    ):
        raise BeartypeConfParamException(
            f'Beartype configuration parameter '
            f'"warning_cls_on_decorator_exception" value '
            f'{repr(conf_kwargs["warning_cls_on_decorator_exception"])} '
            f'neither "None" nor warning category '
            f'(i.e., "Warning" subclass).'
        )
    # Else, "warning_cls_on_decorator_exception" is either "None" *OR* a
    # warning category.

    # For the name of each keyword parameter whose value is expected to be an
    # exception subclass...
    for arg_name_exception_subclass in _ARG_NAMES_EXCEPTION_SUBCLASS:
        # If the value of this keyword parameter is *NOT* an exception subclass,
        # raise an exception.
        if not is_type_subclass(
            conf_kwargs[arg_name_exception_subclass], Exception):
            raise BeartypeConfParamException(
                f'Beartype configuration parameter '
                f'"{arg_name_exception_subclass}" value '
                f'{repr(conf_kwargs[arg_name_exception_subclass])} not '
                f'exception type.'
            )

# ....................{ DEPRECATORS                        }....................
def issue_warning_deprecated_option(
    option_name_old: str, option_name_new: str) -> None:
    '''
    Issue a non-fatal deprecation warning advising the caller that the parameter
    with the passed "old" name has been deprecated in favour of the parameter
    with the passed "new" name.

    Parameters
    ----------
    option_name_old : str
        Name of the deprecated "old" configuration option passed by the caller.
    option_name_new : str
        Name of the corresponding non-deprecated "new" configuration option
        *not* passed by the caller.
    '''
    assert isinstance(option_name_old, str)
    assert isinstance(option_name_new, str)

    # Issue this non-fatal deprecation warning.
    issue_warning(
        cls=DeprecationWarning,
        message=(
            f'Beartype configuration option "{option_name_old}" '
            f'deprecated by new option "{option_name_new}", '
            f'because beartype is here to annoy you when you were '
            f'just about to go home.\n'
            f'tl;dr: pass "{option_name_new}" instead, please. *sigh*'
        ),
    )

# ....................{ SANIFIERS                          }....................
def sanify_conf_kwargs(conf_kwargs: DictStrToAny) -> None:
    '''
    Sanify (i.e., sanitize) the passed dictionary of configuration parameters
    *after* the :func:`.die_if_conf_kwargs_invalid` raiser validates these
    parameters.

    Parameters
    ----------
    conf_kwargs : Dict[str, object]
        Dictionary mapping from the names to values of *all* possible keyword
        parameters configuring this configuration.
    '''
    assert isinstance(conf_kwargs, dict), f'{repr(conf_kwargs)} not dictionary.'

    # ..................{ DEFAULT ~ hint_overrides           }..................
    # If enabling the PEP 484-compliant implicit numeric tower, dynamically
    # synthesize this tower from this existing configuration.
    if conf_kwargs['is_pep484_tower']:
        sanify_conf_kwargs_is_pep484_tower(conf_kwargs)
    # Else, the PEP 484-compliant implicit numeric tower is disabled.

# ....................{ PRIVATE ~ globals                  }....................
_ARG_NAMES_EXCEPTION_SUBCLASS = (
    'violation_door_type',
    'violation_param_type',
    'violation_return_type',
)
'''
Tuple of the names of all keyword parameters to the
:meth:`beartype.BeartypeConf.__new__` dunder method whose values are expected to
be exception subclasses.
'''