#  Copyright 2025–2026 European Union
#  Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)
#  SPDX-License-Identifier: EUPL-1.2
"""
Module defines MAFw exceptions
"""


class MAFwException(Exception):
    """Base class for MAFwException"""

    pass


class ProcessorParameterError(MAFwException):
    """Error with a processor parameter"""

    pass


class InvalidConfigurationError(MAFwException):
    """Error with the configuration of a processor"""

    pass


class MissingOverloadedMethod(UserWarning):
    """
    Warning issued when the user did not overload a required method.

    It is a warning and not an error because the execution framework might still work, but the results might be
    different from what is expected.
    """

    pass


class MissingSuperCall(UserWarning):
    """
    Warning issued when the user did not invoke the super method for some specific processor methods.

    Those methods (like :meth:`~mafw.processor.Processor.start` and :meth:`~mafw.processor.Processor.finish`) have not
    empty implementation also in the base class, meaning that if the user forgets to call *super* in their overloads,
    then the basic implementation will be gone.

    It is a warning and not an error because the execution framework might sill work, but the results might be
    different from what is expected.
    """

    pass


class AbortProcessorException(MAFwException):
    """Exception raised during the execution of a processor requiring immediate exit."""

    pass


class RunnerNotInitialized(MAFwException):
    """Exception raised when attempting to run a not initialized Runner."""

    pass


class InvalidSteeringFile(MAFwException):
    """Exception raised when validating an invalid steering file"""

    pass


class ValidationIssue(InvalidSteeringFile):
    """Base class for steering validation issues."""

    def __init__(self, message: str) -> None:
        super().__init__(message)


class MissingProcessorsToRunIssue(ValidationIssue):
    """Issue raised when the steering file does not declare ``processors_to_run``."""

    def __init__(self) -> None:
        super().__init__('Missing processors_to_run')


class ProcessorsToRunNotListIssue(ValidationIssue):
    """Issue raised when ``processors_to_run`` is not a list."""

    def __init__(self) -> None:
        super().__init__('processors_to_run must be a list')


class MissingUserInterfaceSectionIssue(ValidationIssue):
    """Issue raised when the ``UserInterface`` section is missing."""

    def __init__(self) -> None:
        super().__init__('Missing UserInterface section')


class UnknownProcessorsToRunEntryIssue(ValidationIssue):
    """Issue raised when a processor reference in ``processors_to_run`` cannot be resolved."""

    def __init__(self, entry: str) -> None:
        super().__init__(f'Processor reference {entry} not defined')


class UnknownGroupMemberIssue(ValidationIssue):
    """Issue raised when a group references an unknown processor or nested group."""

    def __init__(self, group: str, member: str) -> None:
        super().__init__(f"Group '{group}' references unknown processor or group '{member}'")


class DuplicateReplicaIssue(ValidationIssue):
    """Issue raised when a processor declares duplicate replica identifiers."""

    def __init__(self, base: str, replica: str) -> None:
        super().__init__(f"Duplicate replica identifier '{replica}' for processor '{base}'")


class CyclicGroupIssue(ValidationIssue):
    """Issue raised when cyclic dependencies exist within processor groups."""

    def __init__(self, node: str) -> None:
        super().__init__(f"Cyclic group dependency detected at '{node}'")


class InvalidFilterConditionIssue(ValidationIssue):
    """Issue raised when a filter condition is incomplete or invalid."""

    def __init__(
        self,
        processor: str,
        model: str,
        condition: str,
        *,
        field_name: str | None = None,
        reason: str | None = None,
    ) -> None:
        descriptor = f"Condition '{condition}' for model '{model}' in processor '{processor}'"
        if field_name:
            descriptor += f" field '{field_name}'"
        descriptor += ' is invalid'
        if reason:
            descriptor += f': {reason}'
        super().__init__(descriptor)


class InvalidFilterLogicIssue(ValidationIssue):
    """Issue raised when a filter logic expression is invalid."""

    def __init__(self, processor: str, target: str, *, detail: str | None = None) -> None:
        descriptor = f"Logic expression for {target} on processor '{processor}' is invalid"
        if detail:
            descriptor += f': {detail}'
        super().__init__(descriptor)


class UnknownProcessor(MAFwException):
    """Exception raised when an attempt is made to create an unknown processor"""

    pass


class UnknownProcessorGroup(MAFwException):
    """Exception raised when an attempt is made to create an unknown processor group"""

    pass


class UnknownDBEngine(MAFwException):
    """Exception raised when the user provided an unknown db engine"""

    pass


class MissingDatabase(MAFwException):
    """Exception raised when a processor requiring a database connection is being operated without a database"""


class MissingAttribute(MAFwException):
    """Exception raised when an attempt is made to execute a statement without a required parameter/attributes"""


class ParserConfigurationError(MAFwException):
    """Exception raised when an error occurred during the configuration of a filename parser"""


class ParsingError(MAFwException):
    """Exception raised when a regular expression parsing failed"""


class MissingSQLStatement(MAFwException):
    """Exception raised when a Trigger is created without any SQL statements."""


class UnsupportedDatabaseError(Exception):
    """Error raised when a feature is not supported by the database."""


class ModelError(MAFwException):
    """Exception raised when an error in a DB Model class occurs"""


class MissingOptionalDependency(UserWarning):
    """UserWarning raised when an optional dependency is required"""


class PlotterMixinNotInitialized(MAFwException):
    """Exception raised when a plotter mixin has not properly initialized"""
