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

'''
Beartype **exception hierarchy** (i.e., public and private exception subclasses
raised at decoration, call, and usage time by :mod:`beartype`).

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

# ....................{ IMPORTS                            }....................
#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
# WARNING: To avoid polluting the public module namespace, external attributes
# should be locally imported at module scope *ONLY* under alternate private
# names (e.g., "from argparse import ArgumentParser as _ArgumentParser" rather
# than merely "from argparse import ArgumentParser").
#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
from abc import ABCMeta as _ABCMeta

# ....................{ PRIVATE ~ mixins                   }....................
class _BeartypeHintForwardRefExceptionMixin(Exception, metaclass=_ABCMeta):
    '''
    Mixin of all **beartype forward reference exceptions** (i.e., exceptions
    concerning parent type hints containing one or more forward references to
    child type hints that have yet to be declared).

    This mixin enables internal logic throughout the :mod:`beartype` codebase to
    conveniently, efficiently, and transparently handle *all* forward reference
    exceptions -- including:

    * :exc:`.BeartypeCallHintForwardRefException`.
    * :exc:`.BeartypeDecorHintForwardRefException`.
    '''

    pass

# ....................{ SUPERCLASS                         }....................
class BeartypeException(Exception, metaclass=_ABCMeta):
    '''
    Abstract base class of all **beartype exceptions.**

    Instances of subclasses of this exception are raised either:

    * At decoration time from the :func:`beartype.beartype` decorator.
    * At call time from the new callable generated by the
      :func:`beartype.beartype` decorator to wrap the original callable.
    '''

    # ..................{ INITIALIZERS                       }..................
    # Note that this dunder method intentionally accepts both positional and
    # variadic arguments to support transmission of exceptions by the standard
    # "multiprocessing" package via the standard "pickle" module. See also:
    #     https://stackoverflow.com/a/28335286/2809027
    def __init__(self, message: str, *args, **kwargs) -> None:
        '''
        Initialize this exception.

        This constructor (in order):

        #. Passes all passed arguments as is to the superclass constructor.
        #. Sanitizes the fully-qualified module name of this
           exception from the private ``"beartype.roar._roarexc"`` submodule to
           the public ``"beartype.roar"`` subpackage to both improve the
           readability of exception messages and discourage end users from
           accessing this private submodule. By default, Python emits less
           readable and dangerous exception messages resembling:

               beartype.roar._roarexc.BeartypeCallHintParamViolation:
               @beartyped quote_wiggum_safer() parameter lines=[] violates type
               hint typing.Annotated[list[str], Is[lambda lst: bool(lst)]], as
               value [] violates validator Is[lambda lst: bool(lst)].

        Parameters
        ----------
        message : str
            Human-readable message describing this exception.

        All remaining parameters are passed as is to the superclass
        :meth:`__init__` method.
        '''
        assert isinstance(message, str), (
            f'{repr(message)} not exception message.')
        # print(f'{type(self)} message: {message}')

        # If...
        #
        # Note that this logic unavoidably duplicates the body of the existing
        # beartype._util.text.utiltextmunge.uppercase_str_char_first() function
        # for safety. Attempting to call *ANY* beartype-specific callable
        # (including that function) from within an exception initializer would
        # invite a shocking calamity that would surely shatter the whole world.
        if (
            # This message contains at least two characters *AND*...
            len(message) >= 2 and
            # The first character of this message is lowercase...
            message[0].islower()
        ):
            # Then uppercase only this character for readability.
            message = f'{message[0].upper()}{message[1:]}'

        # Defer to the superclass constructor.
        super().__init__(message, *args, **kwargs)

        # Sanitize the fully-qualified module name of the class of this
        # exception. See the docstring for justification.
        self.__class__.__module__ = 'beartype.roar'
        # print(f'{self.__class__.__name__}: {message}')

    # ..................{ DUNDERS                            }..................
    def __str__(self) -> str:
        '''
        Human-readable message describing this exception.

        Note that this dunder method *should* be redundant. Since the
        :meth:`__init__` method of this subclass explicitly passes this same
        exact message to the :meth:`__init__` method of the :exc:`Exception`
        superclass, there should be *no* need to expose this message yet again
        by defining this dunder method.

        Indeed, this dunder method *is* redundant for almost all edge cases --
        except one. For unknown reasons, the standard :mod:`multiprocessing`
        package renders a non-human-readable tuple rather than this
        human-readable message when a Python subprocess forked by a
        multiprocessing pool raises an instance of this exception resembling:

            beartype.roar.BeartypeDoorHintViolation: ('Die_if_unbearable() value
            \x1b[1m\x1b[31m42\x1b[0m violates type hint
            \x1b[1m\x1b[32mtyping.List[str]\x1b[0m, as \x1b[1m\x1b[33mint
            \x1b[0m\x1b[1m\x1b[31m42\x1b[0m not instance of
            \x1b[1m\x1b[32mlist\x1b[0m.', (42,))

        Clearly, this has something inexplicable to do with exception pickling
        internally performed by the :mod:`multiprocessing` package. Just as
        clearly, we have neither the inclination nor the patience to get to the
        bottom of this. Indeed, this implementation is inspired by the standard
        :exc:`subprocess.CalledProcessError` exception subclass -- which defines
        the ``__str__()`` dunder method in a similar manner and (presumably) for
        the exact same reasons. This is a mess that we want nothing to do with.
        '''

        # Return the first parameter passed to the superclass __init__() method,
        # guaranteed to be the desired human-readable exception message.
        return self.args[0]


class BeartypeHintViolation(BeartypeException):
    '''
    Abstract base class of all **beartype type-checking violations.**

    Instances of subclasses of this exception are raised by :mod:`beartype` when
    an object to be type-checked violates the type hint annotating that object,
    including wrapper functions generated by the :func:`beartype.beartype`
    decorator when either passed a parameter or returning an object violating
    the type hint annotating that parameter or return.

    Attributes
    ----------
    _culprits_weakref_and_repr : Tuple[(object, str), ...]
        Tuple of 2-tuples ``(culprit_weakref, culprit_repr)`` weakly referring
        to culprits previously passed to the :meth:`__init__` method, where:

        * ``culprits_weakref`` is a weak reference to that culprit, defined as
            either:

            * If that culprit is not ``None`` *and* that culprit can be weakly
              referenced, a **weak reference** (i.e., :class:`weakref.ref`
              instance) to that culprit.
            * If that culprit is ``None``, a singleton non-``None`` placeholder.
              Since the :class:`weakref.ref` class ambiguously returns ``None``
              when that culprit has already been garbage-collected, this
              attribute intentionally substitutes ``None`` for this placeholder.
            * If that culprit *cannot* be weakly referenced (e.g., due to being
              an instance of a builtin variable-sized C-based type), ``None``.

        * ``culprits_repr`` is the machine-readable string representation of the
          culprit weakly referred to by the ``culprit_weakref`` reference.
    '''

    # ..................{ INITIALIZERS                       }..................
    # Note that this dunder method intentionally accepts both positional and
    # variadic arguments to support transmission of exceptions by the standard
    # "multiprocessing" package via the standard "pickle" module. See also:
    #     https://stackoverflow.com/a/28335286/2809027
    def __init__(self, message: str, culprits: tuple, *args, **kwargs) -> None:
        '''
        Initialize this type-checking exception.

        Parameters
        ----------
        message : str
            Human-readable message describing this exception.
        culprits : Tuple[object, ...]
            Tuple of one or more **culprits** (i.e., user-defined objects
            directly responsible for this exception, typically due to violating
            a type hint annotating a parameter passed to *or* object returned
            from the wrapper function generated by the :func:`beartype.beartype`
            decorator raising this exception). This exception internally
            preserves a weak reference to these culprits, which callers may then
            safely retrieve at any time via the :meth:`culprits` property.

        All remaining parameters are passed as is to the superclass
        :meth:`__init__` method.

        Raises
        ------
        _BeartypeUtilExceptionException
            If the culprits are either:

            * *Not* a tuple.
            * The empty tuple.
        '''

        # Avoid circular import dependencies.
        from beartype._util.py.utilpyweakref import make_obj_weakref_and_repr

        # Initialize the superclass with the passed message.
        #
        # Note that the call to the superclass __init__() method *MUST* pass all
        # mandatory parameters passed to this subclass __init__() method call to
        # support transmission of exceptions by the standard "multiprocessing"
        # package via the standard "pickle" module. See also:
        #     https://stackoverflow.com/a/28335286/2809027
        super().__init__(message, culprits, *args, **kwargs)

        #FIXME: Unit test us up, please.
        # If the culprits are *NOT* a tuple, raise an exception.
        if not isinstance(culprits, tuple):
            raise _BeartypeUtilExceptionException(
                f'Culprits {repr(culprits)} not tuple.')
        # Else, the culprits are a tuple.
        #
        # If the culprits are the empty tuple, raise an exception.
        elif not culprits:
            raise _BeartypeUtilExceptionException('Culprits tuple empty.')
        # Else, the culprits are a non-empty tuple.

        # Tuple of 2-tuples ("culprit_weakref", "culprit_repr") weakly referring
        # to all of the passed culprits.
        self._culprits_weakref_and_repr = tuple(
            make_obj_weakref_and_repr(culprit)
            for culprit in culprits
        )

    # ..................{ DUNDERS                            }..................
    #FIXME: Unit test us up, please.
    def __reduce__(self):
        '''
        **Pickled object reduction** (i.e., 3-tuple ``(exception_factory,
        exception_args, exception_state)`` precisely describing how to pickle
        this exception).

        Ideally, overriding *only* the :meth:`__getstate__` dunder method would
        suffice. Sadly, the :meth:`BaseException.__reduce__` exception root
        superclass method fails to explicitly call that dunder method. We have
        *no* recourse but to override the former with a more extensible
        implementation that explicitly calls the latter. Welcome to Pickle Hell.

        Returns
        -------
        tuple[callable, tuple, dict[str, object]]
            3-tuple ``(exception_factory, exception_args, exception_state)``
            such that:

            * ``exception_factory`` is the :meth:`__new__` method possibly
              unique to the type of this exception.
            * ``exception_args`` is the 1-tuple ``(exception_type,)``, where
              ``exception_type`` is the type of this exception. *sigh*
            * ``exception_state`` is the pickleable object state created and
              returned by the :meth:`__getstate__` dunder method.

        See Also
        --------
        https://docs.python.org/3/library/pickle.html#object.__reduce__
            Official documentation for this protocol, which is stupidly complex.
        '''

        # Concrete exception subclass of the currently reduced exception.
        exception_type = type(self)

        # Tuple of all positional arguments to be passed to the __new__()
        # exception factory method unique to this exception subclass.
        exception_args = (exception_type,)

        # Pickleable object state for this exception.
        exception_state = self.__getstate__()

        # Pickled object reduction describing how to pickle this exception.
        return (
            exception_type.__new__,
            exception_args,
            exception_state,
        )


    def __getstate__(self):
        '''
        **Pickleable object state** (i.e., the :attr:`__dict__` dunder
        dictionary mapping from the names of all instance variables bound this
        object that may be safely pickled by the standard :func:`pickle.dumps`
        function to the values of those variables).

        Caveats
        -------
        **Python fails to explicitly call this dunder method.** Why? In all
        likelihood, the :meth:`BaseException.__reduce__` exception root
        superclass method fails to explicitly call this dunder method. Ergo,
        this exception subclass overrides the :meth:`__reduce__` method so as to
        explicitly call this dunder method. Welcome to Pickle Exception Hell.

        Returns
        -------
        dict[str, object]
            Pickleable object state as described above.
        '''

        # Tuple of 2-tuples "(None, culprit_repr)" providing *ONLY* the
        # machine-readable string representations of the one or more culprits
        # previously passed to the __init__() method. This tuple intentionally
        # omits the first "culprit_weakref" item of the
        # "self._culprits_weakref_and_repr" tuple from pickling, as the value of
        # that item is an unpickleable weak reference (i.e.,
        # "weakref.ReferenceType" object). The standard pickle.dumps() function
        # raises exceptions when attempting to pickle weak references: e.g.,
        #     TypeError: cannot pickle 'weakref.ReferenceType' object
        culprits_weakref_and_repr_pickleable = tuple(
            (None, culprit_repr)
            for _, culprit_repr in self._culprits_weakref_and_repr
        )

        # Pickleable object state to be returned, copied to avoid destroying
        # the current contents of this exception.
        exception_state = self.__dict__.copy()

        # Replace the unpickleable "_culprits_weakref_and_repr" instance
        # variable in this state with the pickleable variant defined above.
        exception_state['_culprits_weakref_and_repr'] = (
            culprits_weakref_and_repr_pickleable)
        # print('pickling!')

        # Return this state.
        return exception_state

    # ..................{ PROPERTIES                         }..................
    # Read-only properties intentionally providing no corresponding setters.

    @property
    def culprits(self) -> tuple:
        '''
        Tuple of one or more **culprits** (i.e., user-defined objects directly
        responsible for this exception, typically due to violating a type hint
        annotating a parameter passed to *or* object returned from the wrapper
        function generated by the :func:`beartype.beartype` decorator raising
        this exception).

        Specifically, this property returns either:

        * If a container (e.g., dictionary, list, set, tuple) is responsible for
          this exception, the 2-tuple ``(culprit_root, culprit_leaf)`` where:

          * ``culprit_root`` is the outermost such container. Typically, this is
            the passed parameter or returned value indirectly violating this
            hint.
          * ``culprit_leaf`` is the innermost item transitively contained in
            ``culprit_root`` directly violating this hint.

        * If a non-container (e.g., scalar, class instance) is responsible for
          this exception, the 1-tuple ``(culprit,)`` where ``culprit`` is that
          non-container.

        Caveats
        -------
        **This property is safely accessible from any context.** However, this
        property is most usefully accessed *only* from the ``except ...:`` block
        directly catching this exception. To avoid memory leaks, this property
        only weakly rather than strongly refers to these culprits and is thus
        best accessed only where these culprits are accessible. Notably, this
        property is guaranteed to refer to these culprits *only* for the
        duration of the ``except ...:`` block directly catching this exception.
        Since these culprits may be garbage-collected at any time thereafter,
        this property *cannot* be guaranteed to refer to these culprits outside
        that block. If this property is accessed from *any* other context and
        ore or more of these culprits have already been garbage-collected, the
        corresponding item(s) of this property are only the machine-readable
        representations of those culprits rather than those actual culprits.

        **This property returns the machine-readable representation of instances
        of builtin variable-sized C-based types** (e.g., :class:`dict`,
        :class:`int`, :class:`list`, :class:`tuple`) **rather than those
        instances themselves.** Why? Because CPython limitations prevent those
        instances from being weakly referred to. Blame Guido and the BDFL!
        '''

        # Avoid circular import dependencies.
        from beartype._util.py.utilpyweakref import get_weakref_obj_or_repr

        # Tuple of one or more strong references to the culprits previously
        # passed to the __init__() method for those culprits that are alive
        # *OR* their representations otherwise.
        culprits = tuple(
            get_weakref_obj_or_repr(
                obj_weakref=culprit_weakref, obj_repr=culprit_repr)
            for culprit_weakref, culprit_repr in self._culprits_weakref_and_repr
        )
        # print(f'culprits_weakref_and_repr: {self._culprits_weakref_and_repr}')

        # Return these culprits.
        return culprits

# ....................{ DECORATOR                          }....................
class BeartypeDecorException(BeartypeException):
    '''
    Abstract base class of all **beartype decorator exceptions.**

    Instances of subclasses of this exception are raised at decoration time
    from the :func:`beartype.beartype` decorator.
    '''

    pass

# ....................{ DECORATOR ~ wrapp[ee|er]           }....................
class BeartypeDecorWrappeeException(BeartypeDecorException):
    '''
    **Beartype decorator wrappee exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator when passed a **wrappee** (i.e., object
    to be decorated by this decorator) of invalid type.
    '''

    pass


class BeartypeDecorWrapperException(BeartypeDecorException):
    '''
    **Beartype decorator parse exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on accidentally generating an **invalid
    wrapper** (i.e., syntactically invalid new callable to wrap the original
    callable).
    '''

    pass

# ....................{ DECORATOR ~ hint                   }....................
class BeartypeDecorHintException(BeartypeDecorException):
    '''
    Abstract base class of all **beartype decorator type hint exceptions.**

    Instances of subclasses of this exception are raised at decoration time
    from the :func:`beartype.beartype` decorator on receiving a callable
    annotated by one or more **invalid type hints** (i.e., annotations that are
    neither PEP-compliant nor PEP-compliant type hints supported by this
    decorator).
    '''

    pass


class BeartypeDecorHintForwardRefException(
    BeartypeDecorHintException, _BeartypeHintForwardRefExceptionMixin):
    '''
    **Beartype decorator forward reference type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated by an
    **invalid forward reference type hint** (i.e., string whose value is the
    name of a user-defined class that has yet to be declared).
    '''

    pass


class BeartypeDecorHintTypeException(BeartypeDecorHintException):
    '''
    **Beartype decorator class type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated by an
    **invalid class type hint** (i.e., class invalid for use as a type hint,
    typically due to failing to support runtime :func:`isinstance` calls).
    '''

    pass

# ....................{ DECORATOR ~ hint : non-pep         }....................
class BeartypeDecorHintNonpepException(BeartypeDecorHintException):
    '''
    **Beartype decorator PEP-noncompliant type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated by an
    **invalid PEP-noncompliant type hint** (i.e., type hint failing to comply
    with :mod:`beartype`-specific semantics, including tuple unions and
    fully-qualified forward references).

    Tuple unions, for example, are required to contain *only* PEP-noncompliant
    annotations. This exception is thus raised for callables type-hinted with
    tuples containing one or more PEP-compliant items (e.g., instances or
    classes declared by the stdlib :mod:`typing` module) *or* arbitrary objects
    (e.g., dictionaries, lists, numbers, sets).
    '''

    pass


class BeartypeDecorHintNonpepNumpyException(BeartypeDecorHintNonpepException):
    '''
    **Beartype decorator PEP-noncompliant NumPy type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated by an
    **invalid NumPy type hint** (e.g., ``numpy.typing.NDArray[...]`` type hint
    subscripted by an invalid number of arguments).
    '''

    pass


class BeartypeDecorHintNonpepPanderaException(BeartypeDecorHintNonpepException):
    '''
    **Beartype decorator PEP-noncompliant Pandera type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated by an
    **invalid Pandera type hint** (e.g., ``pandera.typing.DataFrame[...]`` type
    hint annotating a parameter or return of a callable *not* decorated by the
    PEP-noncompliant :func:`pandera.check_types` decorator).
    '''

    pass

# ....................{ DECORATOR ~ hint : pep             }....................
class BeartypeDecorHintPepException(BeartypeDecorHintException):
    '''
    Abstract base class of all **beartype decorator PEP-compliant type hint
    value exceptions.**

    Instances of subclasses of this exception are raised at decoration time
    from the :func:`beartype.beartype` decorator on receiving a callable
    annotated with one or more PEP-compliant type hints either violating an
    annotation-centric PEP (e.g., :pep:`484`) *or* this decorator's
    implementation of such a PEP.
    '''

    pass


class BeartypeDecorHintPepSignException(BeartypeDecorHintPepException):
    '''
    **Beartype decorator PEP-compliant type hint sign exception.**

    Instances of subclasses of this exception are raised at decoration time
    from the :func:`beartype.beartype` decorator on receiving a callable
    annotated with one or more PEP-compliant type hints *not* uniquely
    identifiable by a **sign** (i.e., object uniquely identifying a category
    of PEP-compliant type hints).
    '''

    pass


class BeartypeDecorHintPepUnsupportedException(BeartypeDecorHintPepException):
    '''
    **Beartype decorator unsupported PEP-compliant type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints (e.g., instances or classes declared
    by the stdlib :mod:`typing` module) currently unsupported by this
    decorator.
    '''

    pass

# ....................{ DECORATOR ~ hint : pep : proposal  }....................
class BeartypeDecorHintPep3119Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`3119`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`3119` *or* this
    decorator's implementation of :pep:`3119`, including:

    * Hints that are **non-isinstanceable classes** (i.e., classes that
      prohibit being passed as the second parameter to the :func:`isinstance`
      builtin by leveraging metaclasses overriding the ``__instancecheck__()``
      dunder method to raise exceptions). Notably, this includes most public
      classes declared by the standard :mod:`typing` module.
    '''

    pass


class BeartypeDecorHintPep484585Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`484`- or :pep:`585`-compliant **dual type hint
    exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints violating :pep:`484`, :pep:`585`, *or*
    this decorator's implementation of :pep:`484` or :pep:`585`.
    '''

    pass


class BeartypeDecorHintPep484612646Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`484`-, :pep:`612`-, or :pep:`646`-compliant
    **type parameter exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints violating :pep:`484`, :pep:`612`, *or*
    :pep:`646` -- the standards covering **type parameters** (i.e.,
    :pep:`484`-compliant type variable, pep:`612`-compliant parameter
    specification, and :pep:`646`-compliant type variable tuples).
    '''

    pass


class BeartypeDecorHintPep544Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`544`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`544` *or* this
    decorator's implementation of :pep:`544`.
    '''

    pass


class BeartypeDecorHintPep557Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`557`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`557` *or* this
    decorator's implementation of :pep:`557`.
    '''

    pass


class BeartypeDecorHintPep585Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`585`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`585` *or* this
    decorator's implementation of :pep:`585`.
    '''

    pass


class BeartypeDecorHintPep586Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`586`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`586` *or* this
    decorator's implementation of :pep:`586`.
    '''

    pass


class BeartypeDecorHintPep591Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`591`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`591` *or* this
    decorator's implementation of :pep:`591`.
    '''

    pass


class BeartypeDecorHintPep593Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`593`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`593` *or* this
    decorator's implementation of :pep:`593`.
    '''

    pass


class BeartypeDecorHintPep604Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`604`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`604` *or* this
    decorator's implementation of :pep:`604`.
    '''

    pass


class BeartypeDecorHintPep612Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`612`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`612` *or* this
    decorator's implementation of :pep:`612`.
    '''

    pass


class BeartypeDecorHintPep646Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`646`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`646` *or* this
    decorator's implementation of :pep:`646`.
    '''

    pass


class BeartypeDecorHintPep647Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`647`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`647` *or* this
    decorator's implementation of :pep:`647`.
    '''

    pass


class BeartypeDecorHintPep673Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`673`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`673` *or* this
    decorator's implementation of :pep:`673`.
    '''

    pass


class BeartypeDecorHintPep692Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`692`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`692` *or* this
    decorator's implementation of :pep:`692`.
    '''

    pass


class BeartypeDecorHintPep695Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`695`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`695` *or* this
    decorator's implementation of :pep:`695`.
    '''

    pass


class BeartypeDecorHintPep742Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`742`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`742` *or* this
    decorator's implementation of :pep:`742`.
    '''

    pass

# ....................{ DECORATOR ~ hint : pep : 484       }....................
class BeartypeDecorHintPep484Exception(BeartypeDecorHintPepException):
    '''
    **Beartype decorator** :pep:`484`-compliant **type hint exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more PEP-compliant type hints either violating :pep:`484` *or* this
    decorator's implementation of :pep:`484`, including:

    * Hints subscripted by the :attr:`typing.NoReturn` type hint (e.g.,
      ``typing.List[typing.NoReturn]``).
    '''

    pass


class BeartypeDecorHintPep484TypeVarException(BeartypeDecorHintPep484Exception):
    '''
    **Beartype decorator** :pep:`484`-compliant **type variable exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more :pep:`484`-compliant **type hints** (i.e.,
    :class:`typing.TypeVar` objects) either violating :pep:`484` *or* this
    decorator's implementation of :pep:`484`.
    '''

    pass

# ....................{ DECORATOR ~ hint : reduce          }....................
class BeartypeDecorHintReduceException(BeartypeDecorHintException):
    '''
    **Beartype decorator type hint reduction exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable annotated with
    one or more **irreducible type hints** (e.g., hints inducing infinite
    recursion on attempting to reduce these hints to alternative variants more
    readily digestible by :mod:`beartype`).
    '''

    pass

# ....................{ DECORATOR ~ param                  }....................
class BeartypeDecorParamException(BeartypeDecorException):
    '''
    Abstract base class of all **beartype decorator parameter exceptions.**

    Instances of subclasses of this exception are raised at decoration time
    from the :func:`beartype.beartype` decorator on receiving a callable
    declaring invalid parameters.
    '''

    pass


class BeartypeDecorParamNameException(BeartypeDecorParamException):
    '''
    **Beartype decorator parameter name exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator on receiving a callable declaring
    parameters with **invalid names** (i.e., prefixed by the
    :mod:`beartype`-reserved substring ``"__bear"``).
    '''

    pass

# ....................{ DECORATOR ~ hint : violation       }....................
class BeartypeDecorHintViolation(BeartypeHintViolation):
    '''
    Abstract base class of all **beartype decoration-time type-checking
    violations.**

    Instances of subclasses of this exception are raised at decoration- rather
    than call-time when an object to be type-checked violates the type hint
    annotating that object, including:

    * When a :func:`beartype.beartype`-decorated callable accepts an optional
      parameter whose default value violates the type hint annotating that
      parameter.
    * When either a :pep:`484`- or :pep:`585`-compliant generic *or*
      :pep:`695`-compliant type alias parametrized by a :pep:`484`-compliant
      bounded or constrained type variable is then subscripted by a type hint
      violating that bounds or constraint.
    '''

    pass


class BeartypeDecorHintParamDefaultViolation(BeartypeDecorHintViolation):
    '''
    **Beartyped decorator optional parameter default value type-checking
    exception.**

    This exception is raised at decoration time by the :func:`beartype.beartype`
    decorator when decorating a callable accepting an optional parameter whose
    default value violates the type hint annotating that parameter.
    '''

    pass



class BeartypeDecorHintPep484TypeVarViolation(BeartypeDecorHintViolation):
    '''
    **Beartype decorator** :pep:`484`-compliant **type variable type-checking
    violation.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator when decorating a callable annotated
    with one or more :pep:`484`-compliant **type variables** (i.e.,
    :class:`typing.TypeVar` instances) violating a decoration-time type check,
    including:

    * A :pep:`484`- or :pep:`585`-compliant **generic** (i.e.,
      :class:`typing.Generic` subclass):

      * Initially parametrized by a **bounded** or **constrained type variable**
        (i.e., :class:`typing.TypeVar` instance initialized with a child type
        hint constraining the objects matched by that type variable).
      * Subsequently subscripted by a child type hint violating that bounded or
        constrained type variable (e.g., due to being a class that is *not* a
        subclass of that bounds or constraints).

    * A :pep:`695`-compliant **type alias** (i.e., definition of the form
      ``type {alias_name}[{typevar_name}, ...] = ...``), similarly parametrized
      and subscripted.
    '''

    pass

# ....................{ CALL                               }....................
class BeartypeCallException(BeartypeException):
    '''
    Abstract base class of all **beartyped callable exceptions.**

    Instances of subclasses of this exception are raised from wrapper functions
    generated by the :func:`beartype.beartype` decorator, typically when
    failing a runtime type-check at call time.
    '''

    pass


class BeartypeCallUnavailableTypeException(BeartypeCallException):
    '''
    **Beartyped callable unavailable type exceptions.**

    This exception is raised from the :class:`beartype.cave.UnavailableType`
    class when passed to either the :func:`isinstance` or :func:`issubclass`
    builtin functions, typically due to a type defined by the
    :class:`beartype.cave` submodule being conditionally unavailable under the
    active Python interpreter.
    '''

    pass

# ....................{ CALL ~ hint                        }....................
class BeartypeCallHintException(BeartypeCallException):
    '''
    Abstract base class of all **beartype type-checking exceptions.**

    Instances of subclasses of this exception are raised from wrapper functions
    generated by the :func:`beartype.beartype` decorator when failing a runtime
    type-check at callable call time, typically due to either being passed a
    parameter or returning a value violating a type hint annotating that
    parameter or return.
    '''

    pass


class BeartypeCallHintForwardRefException(
    BeartypeCallHintException, _BeartypeHintForwardRefExceptionMixin):
    '''
    **Beartype type-checking forward reference exception.**

    This exception is raised from wrapper functions generated by the
    :func:`beartype.beartype` decorator when a **forward reference type hint**
    (i.e., string whose value is the name of a user-defined class that has yet
    to be defined) erroneously references a module attribute whose value is
    *not* actually a class.
    '''

    pass

# ....................{ CALL ~ hint : violation            }....................
class BeartypeCallHintViolation(BeartypeHintViolation):
    '''
    Abstract base class of all **beartype call-time type-checking violations.**

    Instances of subclasses of this exception are raised at call- rather than
    decoration-time when an object to be type-checked violates the type hint
    annotating that object, including:

    * When a :func:`beartype.beartype`-decorated callable is either passed a
      parameter or returns an object violating the type hint annotating that
      parameter or return.
    * When the :func:`beartype.door.die_if_unbearable` function is passed an
      object violating the passed type hint.
    '''

    pass


class BeartypeCallHintParamViolation(BeartypeCallHintViolation):
    '''
    **Beartyped callable parameter type-checking exception.**

    This exception is raised from a call to a wrapper function generated by the
    :func:`beartype.beartype` decorator type-checking a decorated callable when
    the caller passes that call a parameter violating the type hint annotating
    that parameter of that decorated callable.
    '''

    pass


class BeartypeCallHintReturnViolation(BeartypeCallHintViolation):
    '''
    **Beartyped callable return type-checking exception.**

    This exception is raised from a call to a wrapper function generated by the
    :func:`beartype.beartype` decorator type-checking a decorated callable when
    that call returns an object violating the type hint annotating the return
    of that decorated callable.
    '''

    pass

# ....................{ PEP                                }....................
class BeartypePepException(BeartypeDecorException):
    '''
    Abstract base class of all **beartype Python Enhancement Proposal (PEP)
    exceptions.**

    Instances of subclasses of this exception are raised at both call time and
    decoration time on receiving a callable or class violating a specific PEP.
    '''

    pass


class BeartypePep563Exception(BeartypePepException):
    '''
    **Beartype** :pep:`563` **exception.**

    This exception is raised at both call time of the
    :func:`beartype.peps.resolve_pep563` function and decoration time of the
    :func:`beartype.beartype` decorator on failing to dynamically evaluate a
    postponed annotation of a callable for which :pep:`563` is active.
    '''

    pass

# ....................{ API ~ cave                         }....................
class BeartypeCaveException(BeartypeException):
    '''
    Abstract base class of all **beartype cave exceptions.**

    Instances of subclasses of this exception are raised at usage time from
    various types published by the :func:`beartype.cave` submodule.
    '''

    pass

# ....................{ API ~ cave : nonetypeor            }....................
class BeartypeCaveNoneTypeOrException(BeartypeCaveException):
    '''
    Abstract base class of all **beartype cave** ``None`` **tuple factory
    exceptions.**

    Instances of subclasses of this exception are raised at usage time from
    the :func:`beartype.cave.NoneTypeOr` tuple factory.
    '''

    pass


class BeartypeCaveNoneTypeOrKeyException(BeartypeCaveNoneTypeOrException):
    '''
    **Beartype cave** ``None`` **tuple factory key exception.**

    Instances of this exception are raised when indexing the :func:
    `beartype.cave.NoneTypeOr` dictionary with an invalid key, including:

    * The empty tuple.
    * Arbitrary objects that are neither:

      * **Types** (i.e., :class:`beartype.cave.ClassType` instances).
      * **Tuples of types** (i.e., tuples whose items are all
        :class:`beartype.cave.ClassType` instances).
    '''

    pass


#FIXME: Unsure what this is about. We no longer raise this anywhere. *sigh*
# class BeartypeCaveNoneTypeOrMutabilityException(
#     BeartypeCaveNoneTypeOrException):
#     '''
#     **Beartype cave** ``None`` **tuple factory mutability exception.**
#
#     Instances of this exception are raised when attempting to explicitly set a
#     key on the :func:`beartype.cave.NoneTypeOr` dictionary.
#     '''
#
#     pass

# ....................{ API ~ claw                         }....................
class BeartypeClawException(BeartypeException):
    '''
    Abstract base class of all **beartype import hook exceptions.**

    Instances of subclasses of this exception are raised at call time from the
    callables and classes published by the :mod:`beartype.claw` subpackage.
    '''

    pass

# ....................{ API ~ claw : hook                  }....................
class BeartypeClawHookException(BeartypeClawException):
    '''
    **Beartype import hook-time exception.**

    This exception is raised at **beartype import hook-time** (i.e., the early
    time encompassing the call to a public beartype import hook published by the
    :mod:`beartype.claw` subpackage by a downstream third-party codebase) on
    various fatal errors (e.g., when that codebase calls that hook with invalid
    parameters).
    '''

    pass


class BeartypeClawHookUnpackagedException(BeartypeClawHookException):
    '''
    **Beartype import hook-time unpackaged exception.**

    This exception is raised at **beartype import hook-time** (i.e., the early
    time encompassing the call to a public beartype import hook published by the
    :mod:`beartype.claw` subpackage by a downstream third-party codebase) when
    the :func:`beartype.claw.beartype_this_package` function is called from
    outside any package structure (e.g., top-level module or executable script).
    '''

    pass

# ....................{ API ~ claw : import                }....................
class BeartypeClawImportException(BeartypeClawException):
    '''
    **Beartype import hook import exception.**

    This exception is raised at import time when importing a module erroneously
    transformed by a beartype import hook previously installed by a prior call
    to a public function published by the :mod:`beartype.claw` subpackage.
    '''

    pass


class BeartypeClawImportAstException(BeartypeClawImportException):
    '''
    **Beartype import hook abstract syntax tree (AST) exception.**

    This exception is raised at import time when a **beartype import hook**
    (i.e., previously installed by a prior call to a public function published
    by the :mod:`beartype.claw` subpackage) erroneously transforms a module from
    its original syntactically valid AST into a new syntactically invalid AST.
    '''

    pass


class BeartypeClawImportConfException(BeartypeClawImportException):
    '''
    **Beartype import hook configuration exception.**

    This exception is raised at import time when a **beartype import hook**
    (i.e., previously installed by a prior call to a public function published
    by the :mod:`beartype.claw` subpackage) erroneously attempts to access a
    non-existent beartype configuration.
    '''

    pass

# ....................{ API ~ conf                         }....................
class BeartypeConfException(BeartypeException):
    '''
    Abstract base class of all **beartype configuration exceptions.**

    Instances of subclasses of this exception are raised by the
    :class:`beartype.BeartypeConf` class to inform the user of various fatal
    edge cases concerning beartype configuration.
    '''

    pass


class BeartypeConfParamException(BeartypeConfException):
    '''
    **Beartype configuration parameter exception.**

    Instances of this exception are raised at instantiation time of the
    :class:`beartype.BeartypeConf` class when the caller attempts to erroneously
    instantiate that class with an invalid parameter.
    '''

    pass


class BeartypeConfShellVarException(BeartypeConfException):
    '''
    **Beartype configuration shell environment variable exception.**

    Instances of this exception are raised at instantiation time of the
    :class:`beartype.BeartypeConf` class when the caller erroneously sets a
    shell environment variable recognized by that class (e.g.,
    ``${BEARTYPE_IS_COLOR}``) to an invalid value.
    '''

    pass

# ....................{ API ~ door                         }....................
class BeartypeDoorException(BeartypeException):
    '''
    Abstract base class of all **Decidedly Object-Oriented Runtime-checking
    (DOOR) exceptions.**

    Instances of subclasses of this exception are raised at call time from
    callables and classes published by the :func:`beartype.door` subpackage.
    '''

    pass


class BeartypeDoorHintViolation(BeartypeCallHintViolation):
    '''
    **Beartype object-oriented type-checking exception.**

    This exception is raised at call time by both:

    * The :func:`beartype.door.die_if_unbearable` function when passed an
      object violating the passed type hint.
    * The :meth:`beartype.door.TypeHint.die_if_unbearable` method when passed an
      object violating the current type hint.
    '''

    pass


class BeartypeDoorIsSubhintException(BeartypeDoorException):
    '''
    **Decidedly Object-Oriented Runtime-checking (DOOR) subhint type hint
    exception.**

    This exception is raised at call time from both the
    :func:`beartype.door.is_subhint` function *and* implementations of the
    :meth:`beartype.door.TypeHint.is_subhint` method, typically due to an
    unexpected internal issue (i.e., bug) within the :mod:beartype.door` API.
    Computing the subhint relation between any two type hints is a surprisingly
    non-trivial decision problem. Unsurprisingly, doing so *can* rarely blow up.
    '''

    pass

# ....................{ API ~ door : non-pep               }....................
class BeartypeDoorNonpepException(BeartypeDoorException):
    '''
    **Decidedly Object-Oriented Runtime-checking (DOOR) PEP-noncompliant type
    hint exception.**

    This exception is raised at call time from :func:`beartype.door` callables
    and classes on receiving an **invalid PEP-noncompliant type hint** (i.e.,
    type hint failing to comply with PEP standards currently supported by the
    :mod:`beartype.door` API).
    '''

    pass

# ....................{ API ~ door : pep                   }....................
class BeartypeDoorPepException(BeartypeDoorException):
    '''
    **Decidedly Object-Oriented Runtime-checking (DOOR) PEP-compliant type hint
    exception.**

    This exception is raised at call time from :func:`beartype.door` callables
    and classes on receiving an **invalid PEP-compliant type hint** (i.e.,
    type hint complying with PEP standards currently supported by the
    :mod:`beartype.door` API but otherwise invalid for various reasons).
    '''

    pass


class BeartypeDoorPepArgsLenException(BeartypeDoorException):
    '''
    **Decidedly Object-Oriented Runtime-checking (DOOR) PEP-compliant type hint
    argument length exception.**

    This exception is raised at call time from :func:`beartype.door` callables
    and classes on receiving an **improperly subscripted PEP-compliant type
    hint** (i.e., type hint complying with PEP standards currently supported by
    the :mod:`beartype.door` API but otherwise invalid due to having been
    subscripted by an invalid number of child type hints).
    '''

    pass


class BeartypeDoorPepUnsupportedException(BeartypeDoorPepException):
    '''
    **Decidedly Object-Oriented Runtime-checking (DOOR) unsupported
    PEP-compliant type hint exception.**

    This exception is raised at call time from :func:`beartype.door` callables
    and classes on receiving an **unsupported PEP-compliant type hint** (i.e.,
    type hint complying with PEP standards *not* currently supported by the
    :mod:`beartype.door` API).
    '''

    pass

# ....................{ API ~ kind                         }....................
class BeartypeKindException(BeartypeException):
    '''
    Abstract base class of all **beartype container exceptions.**

    Instances of subclasses of this exception are raised at usage (e.g.,
    instantiation, callable call) time from various class hierarchies
    implementing **beartype containers** (i.e., pure-Python data structures
    defined by :mod:`beartype`).
    '''

    pass

# ....................{ API ~ kind : dict                  }....................
class BeartypeKindFrozenDictException(BeartypeException):
    '''
    **Beartype frozen dictionary exception.**

    This exception is raised from various methods of the private
    :class:`beartype._util.kind.map.utilmapfrozen.FrozenDict` class publicly
    exposed as the :class:`beartype.BeartypeHintOverrides` subclass, typically
    due to external callers erroneously attempting to modify key-value pairs of
    instances of this class.
    '''

    pass


class BeartypeHintOverridesException(BeartypeKindFrozenDictException):
    '''
    **Beartype hint overrides exception.**

    This exception is raised from various methods of the public
    :class:`beartype.BeartypeHintOverrides` class, typically due to external
    callers erroneously attempting to instantiate instances of this class with
    **recursive hint overrides** (e.g.,
    ``BeartypeHintOverrides{str: list[str]})``).
    '''

    pass

# ....................{ API ~ library                      }....................
class BeartypeLibraryException(BeartypeException):
    '''
    Abstract base class of all **beartype library exceptions.**

    Instances of subclasses of this exception are raised from **third-party
    utilities** (i.e., callables and classes interfacing with third-party
    packages and modules outside the control of :mod:`beartype`).
    '''

    pass


class BeartypeLibraryNumpyException(BeartypeLibraryException):
    '''
    **Beartype NumPy exception.**

    This exception is raised from various functions of the private
    :class:`beartype._util.api.external.utilnumpy` submodule internally called by
    various public APIs interfacing with the third-party :mod:`numpy` package
    (e.g., NumPy array type hint inference implemented by the public
    :func:`beartype.door.infer_hint` function).
    '''

    pass

# ....................{ API ~ plug                         }....................
class BeartypePlugException(BeartypeException):
    '''
    Abstract base class of all **beartype plugin exceptions.**

    Instances of subclasses of this exception are raised at various times from
    functionality utilizing :mod:`beartype`-specific plugin APIs standardized by
    the :mod:`beartype.plug` subpackage, typically on detecting invalid usage of
    a :mod:`beartype`-specific plugin API within a third-party Python package or
    module.
    '''

    pass


class BeartypePlugInstancecheckStrException(BeartypePlugException):
    '''
    **Beartype** ``__instancecheck_str__()`` **exception.**

    This exception is raised at various times from functionality utilizing the
    :mod:`beartype`-specific ``__instancecheck_str__()`` plugin API (i.e., a
    :mod:`beartype`-specific dunder method defined on metaclasses of classes to
    return human-readable substrings describing the failure of arbitrary objects
    to satisfy those classes).
    '''

    pass

# ....................{ API ~ vale                         }....................
class BeartypeValeException(BeartypeException):
    '''
    Abstract base class of all **beartype validator exceptions.**

    Instances of subclasses of this exception are raised at usage (e.g.,
    instantiation, callable call) time from the class hierarchy published by
    the :mod:`beartype.vale` subpackage.
    '''

    pass


class BeartypeValeSubscriptionException(BeartypeValeException):
    '''
    **Beartype validator subscription exception.**

    This exception is raised at instantiation time when subscripting (indexing)
    factories published by the :mod:`beartype.vale` subpackage, including
    attempts to:

    * Instantiate *any* of these factories. Like standard type hints, these
      factories are *only* intended to be subscripted (indexed).
    * Apply the ``&`` or ``|`` operators to *any* subscriptions of these
      factories and *any* other objects (e.g.,
      ``beartype.vale.Is[lambda obj: True]] & 'If it seems bad, it is.'``).
    * Subscript the :attr:`beartype.vale.Is` factory by anything other than a
      **validator** (i.e., tester function satisfying the type hint
      ``collections.abc.Callable[[typing.Any,], bool]``).
    '''

    pass


class BeartypeValeValidationException(BeartypeValeException):
    '''
    **Beartype validator validation exception.**

    This exception is raised at validation time (e.g.,, at call time of a
    :func:`beartype.beartype`-decorated callable annotated by a beartype
    validator) when a beartype validator fails to properly validate an object,
    including attempts to:

    * Subscript the :attr:`beartype.vale.Is` factory by a **non-bool-like
      validator** (i.e., tester function returning an object that is neither a
      :class:`bool` *nor* implicitly convertible into a :class:`bool`).
    '''

    pass

# ....................{ PRIVATE ~ door                       }..................
class _BeartypeDoorTextException(BeartypeDoorException):
    '''
    **Decidedly Object-Oriented Runtime-checking (DOOR) text exception.**

    This exception is raised at call time from :func:`beartype.door` callables
    and classes on detecting invalid strings (e.g., on raising an exception
    whose message is *not* prefixed by the expected substring).
    '''

    pass

# ....................{ PRIVATE ~ vale                     }....................
class _BeartypeValeUtilException(BeartypeValeException):
    '''
    **Beartype validator utility exception.**

    This exception is raised from various submodules of the private
    :func:`beartype.vale._util` subpackage.
    '''

    pass

# ....................{ PRIVATE ~ util                     }....................
class _BeartypeUtilException(BeartypeException):
    '''
    Abstract base class of all **beartype private utility exceptions.**

    Instances of subclasses of this exception are raised by *most* (but *not*
    all) private submodules of the private :mod:`beartype._util` subpackage.
    These exceptions denote critical internal issues and should thus *never* be
    raised, let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilExceptionException(_BeartypeUtilException):
    '''
    **Beartype exception utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype.roar._roarexc` subpackage.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : ast                 }..................
class _BeartypeUtilAstException(_BeartypeUtilException):
    '''
    **Beartype abstract syntax tree (AST) utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.ast` subpackage.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : cache               }..................
class _BeartypeUtilCachedException(_BeartypeUtilException):
    '''
    Abstract base class of all **beartype caching utility exceptions.**

    Instances of subclasses of this exception are raised by private submodules
    of the private :mod:`beartype._util.cache` subpackage. These exceptions
    denote critical internal issues and should thus *never* be raised -- let
    alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilCallableCachedException(_BeartypeUtilCachedException):
    '''
    **Beartype memoization exception.**

    This exception is raised by the
    :func:`beartype._util.cache.utilcache.utilcachecall.callable_cached`
    decorator on various fatal errors (e.g., when the signature of the
    decorated callable is unsupported).

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilCacheLruException(_BeartypeUtilCachedException):
    '''
    **Beartype Least Recently Used (LRU) cache exception.**

    This exception is raised by the
    :func:`beartype._util.cache.utilcache.utilcachelru.CacheLruStrong` class
    on various fatal errors (e.g., when the cache capacity is *not* a positive
    integer).

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : cache : pool        }..................
class _BeartypeUtilCachedKeyPoolException(_BeartypeUtilException):
    '''
    **Beartype key pool exception.**

    This exception is raised by private functions of the private
    :mod:`beartype._util.cache.pool.utilcachepool` subpackage on various fatal
    edge cases.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''
    pass


class _BeartypeUtilCachedFixedListException(_BeartypeUtilCachedException):
    '''
    **Beartype decorator fixed list exception.**

    This exception is raised at decoration time from the
    :func:`beartype.beartype` decorator when an internal callable erroneously
    mutates a **fixed list** (i.e., list constrained to a fixed length defined
    at instantiation time), usually by attempting to modify the length of that
    list.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : call                }..................
class _BeartypeCallHintRaiseException(_BeartypeUtilException):
    '''
    Abstract base class of all **beartype human-readable exception raiser
    exceptions.**

    Instances of subclasses of this exception are raised by private utility
    **exception raiser functions** (i.e., functions raising human-readable
    exceptions from wrapper functions when either passed a parameter or
    returning a value annotated by a type hint fails the runtime type-check
    required by that hint) when an unexpected failure occurs.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeCallHintPepRaiseException(_BeartypeCallHintRaiseException):
    '''
    **Beartype PEP-compliant human-readable exception raiser exception.**

    This exception is raised by the
    :func:`beartype._check.error.errget.get_func_pith_violation`
    exception raiser function when an unexpected failure occurs.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeCallHintPepRaiseDesynchronizationException(
    _BeartypeCallHintPepRaiseException):
    '''
    **Beartype human-readable exception raiser desynchronization exception.**

    This exception is raised by the
    :func:`beartype._check.error.errget.get_func_pith_violation` function
    (which raises human-readable exceptions from wrapper functions when either
    passed a parameter or returning a value, referred to as the "pith" for
    brevity, annotated by a PEP-compliant type hint fails the type-check
    required by that hint) when this pith appears to satisfy this type-check, a
    runtime paradox implying either:

    * The parent wrapper function generated by the :mod:`beartype.beartype`
      decorator type-checking this pith triggered a false negative by
      erroneously misdetecting this pith as failing this type check.
    * The
        :func:`beartype._check.error.errget.get_func_pith_violation`
      function re-type-checking this pith triggered a false positive by
      erroneously misdetecting this pith as satisfying this type check when in
      fact this pith fails to do so.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : decor               }..................
class _BeartypeDecorHintSanifyException(_BeartypeUtilException):
    '''
    Abstract base class of all **beartype type hint sanification exceptions.**

    Instances of subclasses of this exception are raised by private utility
    **type hint sanifiers** (i.e., functions reducing otherwise semantically
    useless and possibly PEP-noncompliant hints to semantically useful and fully
    PEP-compliant hints) when an unexpected failure occurs.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : kind                }..................
class _BeartypeUtilCallFrameException(_BeartypeUtilException):
    '''
    **Beartype call stack frame utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.utilfunc` subpackage. This exception denotes a critical
    internal issue and should thus *never* be raised -- let alone allowed to
    percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilMappingException(_BeartypeUtilException):
    '''
    **Beartype mapping utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.kind.map` subpackage. This exception denotes a
    critical internal issue and should thus *never* be raised -- let alone
    allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilModuleException(_BeartypeUtilException):
    '''
    **Beartype module utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.module.utilmodget` subpackage. Notably, this includes:

    * When dynamically importing an unimportable external user-defined module,
      typically due to a **PEP-compliant forward reference type hint** (i.e.,
      string whose value is the name of a user-defined class that has yet to be
      defined) erroneously referencing a non-existent module or module
      attribute.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilPathException(_BeartypeUtilException):
    '''
    **Beartype path utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.path` subpackage on various fatal edge cases. This
    exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilTypeException(_BeartypeUtilException):
    '''
    **Beartype class utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.cls` subpackage. This exception denotes a critical
    internal issue and should thus *never* be raised -- let alone allowed to
    percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : kind : callable     }..................
class _BeartypeUtilCallableException(_BeartypeUtilException):
    '''
    **Beartype callable utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.func` subpackage. This exception denotes a critical
    internal issue and should thus *never* be raised -- let alone allowed to
    percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilCallableScopeException(_BeartypeUtilCallableException):
    '''
    **Beartype callable scope utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.func.utilfuncscope` submodule. This exception denotes a
    critical internal issue and should thus *never* be raised -- let alone
    allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilCallableScopeNotFoundException(
    _BeartypeUtilCallableException):
    '''
    **Beartype callable missing scope utility exception.**

    This exception is raised by the private
    :mod:`beartype._util.func.utilfuncscope.get_func_locals` getter on failing
    to find the lexical scope of the parent callable or class declaring the
    passed nested callable, enabling callers of that getter to identify this
    common edge case. This exception denotes a critical internal issue and
    should thus *never* be raised -- let alone allowed to percolate up the call
    stack to end users.
    '''

    pass


class _BeartypeUtilCallableWrapperException(_BeartypeUtilCallableException):
    '''
    **Beartype callable wrapper utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.func.utilfuncwrap` subpackage. This exception denotes a
    critical internal issue and should thus *never* be raised -- let alone
    allowed to percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : object              }..................
class _BeartypeUtilObjectException(_BeartypeUtilException):
    '''
    Abstract base class of all **beartype object utility exceptions.**

    Instances of subclasses of this exception are raised by private functions
    defined by the private :mod:`beartype._util.utilobject` submodule. These
    exceptions denote critical internal issues and should thus *never* be raised
    -- let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilObjectNameException(_BeartypeUtilObjectException):
    '''
    **Beartype object name exception.**

    This exception is raised by the
    :func:`beartype._util.utilobject.get_object_basename_scoped` getter when
    the passed object is **unnamed** (i.e., fails to declare either the
    ``__name__`` or ``__qualname__`` dunder attributes). This exception denotes
    a critical internal issue and should thus *never* be raised -- let alone
    allowed to percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : python              }..................
class _BeartypeUtilPythonException(_BeartypeUtilException):
    '''
    Abstract base class of all beartype **Python utility exceptions.**

    Instances of subclasses of this exception are raised by private submodules
    of the private :mod:`beartype._util.py` subpackage. These exceptions
    denote critical internal issues and should thus *never* be raised -- let
    alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilPythonInterpreterException(_BeartypeUtilPythonException):
    '''
    Beartype **Python interpreter utility exception.**

    This exception is raised by private functions of the private
    :mod:`beartype._util.py.utilpyinterpreter` submodule on fatal edge cases.
    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilPythonWeakrefException(_BeartypeUtilPythonException):
    '''
    Beartype **Python weak reference utility exception.**

    This exception is raised by private functions of the private
    :mod:`beartype._util.py.utilpyweakref` submodule on fatal edge cases. This
    exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass

# ....................{ PRIVATE ~ util : text                }..................
class _BeartypeUtilTextException(_BeartypeUtilException):
    '''
    Beartype **text utility exception.**

    This exception is raised by various functions of the private
    :mod:`beartype._util.text` subpackage.

    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilTextIdentifierException(_BeartypeUtilTextException):
    '''
    Beartype **Python identifier utility exception.**

    This exception is raised by private functions of the private
    :mod:`beartype._util.text.utiltextidentifier` submodule on fatal edge cases.
    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass


class _BeartypeUtilTextVersionException(_BeartypeUtilTextException):
    '''
    Beartype **Python version utility exception.**

    This exception is raised by private functions of the private
    :mod:`beartype._util.text.utiltextversion` submodule on fatal edge cases.
    This exception denotes a critical internal issue and should thus *never* be
    raised -- let alone allowed to percolate up the call stack to end users.
    '''

    pass
