disdantic.exceptions¶

class AutoPopulationError(DisdanticError, ValueError):
    """Raised when automatic registry population is rejected because
    discovery is disabled.

    Example:
        .. code-block:: python

            from disdantic.exceptions import AutoPopulationError

            try:
                raise AutoPopulationError(
                    "Auto-population rejected: discovery is disabled."
                )
            except AutoPopulationError as error:
                print(error)
    """

class DiscriminatorNotFoundError(DisdanticError, ValueError):
    """Raised when a discriminator token cannot be found in the registry.

    This exception occurs during deserialization or runtime registry lookups when
    a discriminator key or token is provided that does not match any registered
    model. It allows the calling code to inspect the incorrect key and access the
    valid choices for graceful recovery or detailed reporting.

    Example:
        .. code-block:: python

            from disdantic.exceptions import DiscriminatorNotFoundError

            try:
                # Attempt to resolve an unregistered type token
                raise DiscriminatorNotFoundError("unknown", ["a", "b"])
            except DiscriminatorNotFoundError as error:
                print(f"Rejected: {error.rejected_value}")
                print(f"Valid choices: {error.valid_options}")
    """

    rejected_value: str
    valid_options: list[str]

    def __init__(self, rejected_value: str, valid_options: list[str]) -> None:
        """Initialize the exception with the rejected value and list of valid options.

        :param rejected_value: The key or token that was not found in the registry.
        :param valid_options: The list of all registered discriminator tokens.
        :returns: None
        """
        self.rejected_value = rejected_value
        self.valid_options = valid_options
        message = (
            f"Failed to resolve polymorphic configuration layer: "
            f"'{rejected_value}' is not a recognized mapping target. "
            f"Supported valid choices are: {valid_options}."
        )
        super().__init__(message)

class DisdanticError(Exception):
    """Base exception for all anomalies encountered within disdantic.

    This exception serves as the root class for all error states raised by the
    registry system. Catching this base class allows handlers to intercept all
    polymorphic resolving issues or configuration mismatches.

    Example:
        .. code-block:: python

            from disdantic.exceptions import DisdanticError

            try:
                # Intercept any registry configuration anomaly
                pass
            except DisdanticError as error:
                # Handle package-specific issue
                print(f"Disdantic error caught: {error}")
    """

class EmptyRegistryError(DisdanticError, ValueError):
    """Raised when no objects or classes are currently present in a registry.

    Example:
        .. code-block:: python

            from disdantic.exceptions import EmptyRegistryError

            try:
                raise EmptyRegistryError("No classes present in the registry setup.")
            except EmptyRegistryError as error:
                print(error)
    """

class MissingPackagesError(DisdanticError, ValueError):
    """Raised when autodiscovery is triggered but no target packages
    have been configured.

    Example:
        .. code-block:: python

            from disdantic.exceptions import MissingPackagesError

            try:
                raise MissingPackagesError("No packages configured for auto discovery.")
            except MissingPackagesError as error:
                print(error)
    """

class RegistryCollisionError(DisdanticError, KeyError):
    """Raised when an entry mapping path collides with a registered ID.

    This exception is raised during model registration when a developer attempts
    to register multiple models under the same discriminator token, or when a name
    clash occurs in the registry.

    Example:
        .. code-block:: python

            from disdantic.exceptions import RegistryCollisionError

            try:
                # Registering a model under an already registered token
                raise RegistryCollisionError("Duplicate mapping token 'type_a'.")
            except RegistryCollisionError as error:
                print(f"Collision: {error}")
    """