"""
This type stub file was generated by pyright.
"""

from abc import ABCMeta, abstractmethod
from typing import Generic, TypeVar

__all__ = ["InvalidSchema", "InvalidAnnotation", "Annotation"]


_T = TypeVar("_T")


class InvalidSchema(Exception):
    """Exception raised when a subclass of :class:`Annotation` is defined with a non-conformant
    :data:`~Annotation.schema`."""
    ...


class InvalidAnnotation(Exception):
    """Exception raised by :meth:`Annotation.validate` when the JSON representation of
    an annotation does not conform to its schema."""
    ...


class Annotation(Generic[_T], metaclass=ABCMeta):
    """Interface annotation.

    Annotations are containers for metadata that can be retrieved from an interface object using
    the :meth:`Signature.annotations <.wiring.Signature.annotations>` method.

    Annotations have a JSON representation whose structure is defined by the `JSON Schema`_
    language.
    """
    schema: dict = ...
    def __init_subclass__(cls, **kwargs) -> None:
        """
        Defining a subclass of :class:`Annotation` causes its :data:`schema` to be validated.

        Raises
        ------
        :exc:`InvalidSchema`
            If :data:`schema` doesn't conform to the `2020-12` draft of `JSON Schema`_.
        :exc:`InvalidSchema`
            If :data:`schema` doesn't have a  `"$id" keyword`_ at its root. This requirement is
            specific to :class:`Annotation` schemas.
        """
        ...
    
    @property
    @abstractmethod
    def origin(self) -> _T:
        """Python object described by this :class:`Annotation` instance.

        Subclasses of :class:`Annotation` must implement this property.
        """
        ...
    
    @abstractmethod
    def as_json(self) -> dict:
        """Convert to a JSON representation.

        Subclasses of :class:`Annotation` must implement this method.

        JSON representation returned by this method must adhere to :data:`schema` and pass
        validation by :meth:`validate`.

        Returns
        -------
        :class:`dict`
            JSON representation of this annotation, expressed in Python primitive types
            (:class:`dict`, :class:`list`, :class:`str`, :class:`int`, :class:`bool`).
        """
        ...
    
    @classmethod
    def validate(cls, instance: dict) -> None:
        """Validate a JSON representation against :attr:`schema`.

        Arguments
        ---------
        instance : :class:`dict`
            JSON representation to validate, either previously returned by :meth:`as_json`
            or retrieved from an external source.

        Raises
        ------
        :exc:`InvalidAnnotation`
            If :py:`instance` doesn't conform to :attr:`schema`.
        """
        ...
    
    def __repr__(self) -> str:
        ...
    


