"""
Defines a base exception class and specific custom exceptions raised by the GameAIFoundation classes.

Exported Classes:
    None

Exported Exceptions:
    GameAIError -- Base exception class for all custom exceptions specific to the Game AI foundation classes.
    ExcessiveRepeatActionScheduleError -- Raised when the ActionManger is asked to schedule a GameAction
        and that type of GameAction is already pending or active the maximum number of times.
    ActionCannotAchieveGoalError -- Raised when, while an action is executing, it is determined that the action
        cannot achieve the goal.
    
Exceptions raised:
    None
 
Exported Functions:
    None
"""


class GameAIError(Exception):
    """
    Base exception class for all custom exceptions specific to the Game AI foundation classes.
    """
    pass


class ExcessiveRepeatActionScheduleError(GameAIError):
    """
    Custom exception to be raised when the ActionManger is asked to schedule a GameAction
    and that type of GameAction is already pending or active the maximum number of times.
    This is a safeguard against potential infinite loops in the AI's logic where
    the same action is scheduled and executed repeatedly without progress.
    Arguments expected in **kwargs:
        action_type: What type of GameAction was being scheduled repeatedly.
        num_times: An integer indicating how many times the action is currently pending or active.
    """
    def __init__(self, *args, **kwargs):
        super().__init__(*args)
        self._action_type = kwargs.get('action_type')
        self._num_times = kwargs.get('num_times')


class ActionCannotAchieveGoalError(GameAIError):
    """
    Custom exception to be raised when, while an action is executing, it is determined that the action
    cannot achieve the goal.
    Arguments expected in **kwargs:
        action: The GameAction that was executing.
        parent_action: If the action is a sub-action, the parent GameAction that scheduled it.
    """
    def __init__(self, *args, **kwargs):
        super().__init__(*args)
        self._action = kwargs.get('action')
        self._parent_action = kwargs.get('parent_action', None)  # Optional parent action if this is a sub-action


