# Source code for beartype.roar._roarexc

    #!/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 BeartypeDecorHintRecursionException(BeartypeDecorHintException):
        '''
        **Beartype decorator type hint recursion exception.**

        This exception is raised at decoration time from the
        :func:`beartype.beartype` decorator on receiving a callable annotated with
        one or more **infinitely recursive type hints** (i.e., hints that
        erroneously induce infinite recursion on attempting to dynamically generate
        pure-Python code type-checking against these hints).
        '''

        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 BeartypeDecorHintPep560Exception(BeartypeDecorHintPepException):
        '''
        **Beartype decorator** :pep:`560`-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:`560` *or* this
        decorator's implementation of :pep:`560`.
        '''

        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 BeartypeDecorHintPep646692Exception(BeartypeDecorHintPepException):
        '''
        **Beartype decorator** :pep:`646`- or :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 both :pep:`646` and
        :pep:`692` *or* this decorator's implementation of those PEPs.
        '''

        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 BeartypeDecorHintPep649Exception(BeartypeDecorHintPepException):
        '''
        **Beartype decorator** :pep:`649`-compliant **type hint exception.**

        This exception is raised at decoration time from the
        :func:`beartype.beartype` decorator on receiving an object violating
        :pep:`649` (e.g., due to defining neither the ``__annotations__`` dunder
        dictionary nor ``__annotate__()`` dunder method).
        '''

        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 BeartypeDecorHintPep696Exception(BeartypeDecorHintPepException):
        '''
        **Beartype decorator** :pep:`696`-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:`696` *or* this
        decorator's implementation of :pep:`696`.
        '''

        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

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

        This exception is raised at decoration time from the
        :func:`beartype.beartype` decorator on receiving an object violating
        :pep:`749` (e.g., due to a type hint failing to define a
        :pep:`749`-compliant evaluation function).
        '''

        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 ~ 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 BeartypeCallHintPep557FieldViolation(BeartypeCallHintViolation):
        '''
        **Beartyped dataclass field type-checking exception.**

        This exception is raised by a call to the ``__setattr__()`` dunder method
        bound to a **dataclass** (i.e., type decorated by the :pep:`557`-compliant
        :func:`dataclasses.dataclass` decorator) generated by the
        :func:`beartype.beartype` decorator. This type-checking *only* applies to
        **dataclass fields.** By :pep:`557`, a "dataclass field" is *any* class
        attribute of this dataclass annotated by *any* type hint other than either:

        * A :pep:`557`-compliant ``dataclasses.ClassVar[...]`` type hint.
        * A :pep:`557`-compliant ``dataclasses.InitVar[...]`` type hint.

        :func:`beartype.beartype` safely monkey-patches a new ``__setattr__()``
        dunder method into each decorated dataclass, type-checking that each
        dataclass field satisfies the type hint annotating that field on both:

        * **Dataclass object initialization** (i.e., at early ``__init__()`` time).
        * **Dataclass field assignment** (i.e., when each field is subsequently
          assigned to with an assignment statement).
        '''

        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 : ast                   }....................
    class BeartypeClawAstException(BeartypeClawException):
        '''
        Abstract base class of all **beartype import hook abstract syntax tree (AST)
        exceptions.**

        Instances of subclasses of this exception from various submodules of the
        private :func:`beartype.claw._ast` subpackage.
        '''

        pass

    class BeartypeClawAstImportException(BeartypeClawAstException):
        '''
        **Beartype import hook abstract syntax tree (AST) import exceptions.**

        This exception is raised at **AST transformation time** (i.e., the early
        time encompassing the automatic injection of runtime type-checking into an
        imported third-party module registered by a beartype import hook published
        by the :mod:`beartype.claw` subpackage in a downstream third-party codebase)
        on failing to parse an ``import`` statement in user-defined code.
        '''

        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 public
        :class:`beartype._util.kind.maplike.utilmapfrozen.FrozenDict` class publicly
        exposed as the :class:`beartype.FrozenDict` subclass, typically due to
        external attempts to erroneously modify the contents of a frozen dictionary.
        '''

        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.bite.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 ~ claw                       }..................
    class _BeartypeClawAstNodeScopesException(BeartypeClawAstException):
        '''
        **Beartype import hook abstract syntax tree (ast) node scopes exception.**

        This exception is raised at :mod:`beartype.claw` import hook time from the
        :class:`beartype.claw._ast._scope.clawastscope.BeartypeNodeScopes` class on
        detecting an invalid AST node scope.

        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 ~ 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).

        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 ~ 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

    class _BeartypeUtilCacheObjectAttributeException(_BeartypeUtilCachedException):
        '''
        **Beartype memoized object attribute exception.**

        This exception is raised by the :mod:`beartype._util.cache.utilcacheobjattr`
        submodule on various fatal errors (e.g., when the passed object *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.errmain.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.errmain.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.errmain.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 : 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 : 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.maplike` 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 _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 : module              }..................
    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 _BeartypeUtilModulePep328Exception(_BeartypeUtilModuleException):
        '''
        **Beartype module** :pep:`3119`-compliant **exception.**

        This exception is raised by various functions of the private
        :mod:`beartype._util.module.pep.modpep328` 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

    # ....................{ 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 : path                }..................
    class _BeartypeUtilPathException(_BeartypeUtilException):
        '''
        Abstract base class of all **beartype path utility exceptions.**

        Instances of subclasses of this exception type are raised by private
        submodules of the private :mod:`beartype._util.path` 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 _BeartypeUtilPathDirException(_BeartypeUtilPathException):
        '''
        **Beartype directory utility exception.**

        This exception is raised by private submodules of the
        private :mod:`beartype._util.path` subpackage pertaining to
        directory-handling. 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 _BeartypeUtilPathFileException(_BeartypeUtilPathException):
        '''
        **Beartype file utility exception.**

        This exception is raised by private submodules of the
        private :mod:`beartype._util.path` subpackage pertaining to file-handling.
        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 type 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