Skip to content

Exceptions

Module: terminaltexteffects.utils.exceptions

Every TTE exception derives from TerminalTextEffectsError, so catch it to handle any engine error. The specific exceptions are importable from terminaltexteffects.utils.exceptions and are grouped below by the module that defines them. Import the base class from terminaltexteffects.utils.exceptions.base_terminaltexteffects_exception.

Base Exception

Base class for exceptions in the terminaltexteffects package.

TerminalTextEffectsError

Bases: Exception

Base class for exceptions in the terminaltexteffects package.

Source code in terminaltexteffects/utils/exceptions/base_terminaltexteffects_exception.py 
4
5
class TerminalTextEffectsError(Exception):
    """Base class for exceptions in the terminaltexteffects package."""

Animation Exceptions

Custom exceptions for handling errors related to animations in the terminaltexteffects package.

Classes:

Name Description
FrameDurationError

Raised when a frame is added to a Scene with an invalid duration.
ActivateEmptySceneError

Raised when a Scene without any frames is activated.
AnimationSceneError

Generic Scene/animation error with a provided message.
DuplicateSceneIDError

Raised when a Scene is initialized with an existing ID.

ActivateEmptySceneError

Bases: TerminalTextEffectsError

Raised when a Scene is without any frames is activated.

A Scene must have at least one frame to be activated.

Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class ActivateEmptySceneError(TerminalTextEffectsError):
    """Raised when a Scene is without any frames is activated.

    A Scene must have at least one frame to be activated.

    """

    def __init__(self, scene: Scene) -> None:
        """Initialize an ActivateEmptySceneError.

        Args:
            scene (Scene): The Scene that was activated.

        """
        self.scene = scene
        self.message = f"Scene `{scene.scene_id}` has no frames. A Scene must have at least one frame to be activated."
        super().__init__(self.message)

__init__(scene)

Initialize an ActivateEmptySceneError.

Parameters:

Name Type Description Default
scene Scene

The Scene that was activated.

 required
Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
48
49
50
51
52
53
54
55
56
57
def __init__(self, scene: Scene) -> None:
    """Initialize an ActivateEmptySceneError.

    Args:
        scene (Scene): The Scene that was activated.

    """
    self.scene = scene
    self.message = f"Scene `{scene.scene_id}` has no frames. A Scene must have at least one frame to be activated."
    super().__init__(self.message)

AnimationSceneError

Bases: TerminalTextEffectsError

Generic Scene/animation error with a provided message.

Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
60
61
62
63
64
65
66
67
68
69
70
71
class AnimationSceneError(TerminalTextEffectsError):
    """Generic Scene/animation error with a provided message."""

    def __init__(self, message: str) -> None:
        """Initialize an AnimationSceneError.

        Args:
            message (str): The message to display.

        """
        self.message = message
        super().__init__(message)

__init__(message)

Initialize an AnimationSceneError.

Parameters:

Name Type Description Default
message str

The message to display.

 required
Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
63
64
65
66
67
68
69
70
71
def __init__(self, message: str) -> None:
    """Initialize an AnimationSceneError.

    Args:
        message (str): The message to display.

    """
    self.message = message
    super().__init__(message)

DuplicateSceneIDError

Bases: TerminalTextEffectsError

Raised when a Scene is initialized with a duplicate ID.

Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
class DuplicateSceneIDError(TerminalTextEffectsError):
    """Raised when a Scene is initialized with a duplicate ID."""

    def __init__(self, scene_id: str) -> None:
        """Initialize a DuplicateSceneIDError.

        Args:
            scene_id (str): The ID already used by a Scene in the Animation.

        """
        self.scene_id = scene_id
        self.message = f"Scene ID `{scene_id}` has already been used."
        super().__init__(self.message)

__init__(scene_id)

Initialize a DuplicateSceneIDError.

Parameters:

Name Type Description Default
scene_id str

The ID already used by a Scene in the Animation.

 required
Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
77
78
79
80
81
82
83
84
85
86
def __init__(self, scene_id: str) -> None:
    """Initialize a DuplicateSceneIDError.

    Args:
        scene_id (str): The ID already used by a Scene in the Animation.

    """
    self.scene_id = scene_id
    self.message = f"Scene ID `{scene_id}` has already been used."
    super().__init__(self.message)

FrameDurationError

Bases: TerminalTextEffectsError

Raised when a frame is added to a Scene with an invalid duration.

A frame duration must be a positive integer. This error is raised when a frame is added to a Scene with a duration that is not a positive integer.

Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
class FrameDurationError(TerminalTextEffectsError):
    """Raised when a frame is added to a Scene with an invalid duration.

    A frame duration must be a positive integer. This error is raised when a frame is added to a Scene with a duration
    that is not a positive integer.

    """

    def __init__(self, duration: int) -> None:
        """Initialize a FrameDurationError.

        Args:
            duration (int): The duration provided to the frame.

        """
        self.duration = duration
        self.message = f"Frame duration must be a positive integer. Received: `{duration}`."
        super().__init__(self.message)

__init__(duration)

Initialize a FrameDurationError.

Parameters:

Name Type Description Default
duration int

The duration provided to the frame.

 required
Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
29
30
31
32
33
34
35
36
37
38
def __init__(self, duration: int) -> None:
    """Initialize a FrameDurationError.

    Args:
        duration (int): The duration provided to the frame.

    """
    self.duration = duration
    self.message = f"Frame duration must be a positive integer. Received: `{duration}`."
    super().__init__(self.message)

SceneNotFoundError

Bases: TerminalTextEffectsError

Raised when query_scene is called with a scene_id that does not exist.

Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
class SceneNotFoundError(TerminalTextEffectsError):
    """Raised when `query_scene` is called with a scene_id that does not exist."""

    def __init__(self, scene_id: str) -> None:
        """Initialize a SceneNotFoundError.

        Args:
            scene_id (str): The scene_id that was not found.

        """
        self.scene_id = scene_id
        self.message = f"Scene with scene_id `{scene_id}` not found."
        super().__init__(self.message)

__init__(scene_id)

Initialize a SceneNotFoundError.

Parameters:

Name Type Description Default
scene_id str

The scene_id that was not found.

 required
Source code in terminaltexteffects/utils/exceptions/animation_exceptions.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def __init__(self, scene_id: str) -> None:
    """Initialize a SceneNotFoundError.

    Args:
        scene_id (str): The scene_id that was not found.

    """
    self.scene_id = scene_id
    self.message = f"Scene with scene_id `{scene_id}` not found."
    super().__init__(self.message)

Character Exceptions

Custom exceptions for handling errors related to EffectCharacters in the terminaltexteffects package.

DuplicateEventRegistrationError

Bases: TerminalTextEffectsError

Raised when attempting to register a duplicate event-action combination.

This error is raised when trying to register the same event-caller-action-target combination that has already been registered. Each unique combination can only be registered once to prevent duplicate event handling.

Source code in terminaltexteffects/utils/exceptions/base_character_exceptions.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
class DuplicateEventRegistrationError(TerminalTextEffectsError):
    """Raised when attempting to register a duplicate event-action combination.

    This error is raised when trying to register the same event-caller-action-target combination
    that has already been registered. Each unique combination can only be registered once to prevent
    duplicate event handling.

    """

    def __init__(
        self,
        event: EventHandler.Event,
        caller: Scene | Waypoint | Path | Mount,
        action: EventHandler.Action,
        target: Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None,
    ) -> None:
        """Initialize a DuplicateEventRegistrationError.

        Args:
            event (EventHandler.Event): The event that was already registered.
            caller (Scene | Waypoint | Path | Mount): The caller object that was already registered.
            action (EventHandler.Action): The action that was already registered.
            target (Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None): The target that was
                already registered.

        """
        self.event = event
        self.caller = caller
        self.action = action
        self.target = target
        self.message = (
            f"Duplicate event registration: Event `{event.name}` with caller `{caller.__class__.__name__}`, "
            f"action `{action.name}`, and target `{target.__class__.__name__ if target is not None else 'None'}` "
            f"has already been registered."
        )
        super().__init__(self.message)

__init__(event, caller, action, target)

Initialize a DuplicateEventRegistrationError.

Parameters:

Name Type Description Default
event Event

The event that was already registered.

 required
caller Scene | Waypoint | Path | Mount

The caller object that was already registered.

 required
action Action

The action that was already registered.

 required
target Scene | Path | Mount | int | Coord | Callback | str | None

The target that was already registered.

 required
Source code in terminaltexteffects/utils/exceptions/base_character_exceptions.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def __init__(
    self,
    event: EventHandler.Event,
    caller: Scene | Waypoint | Path | Mount,
    action: EventHandler.Action,
    target: Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None,
) -> None:
    """Initialize a DuplicateEventRegistrationError.

    Args:
        event (EventHandler.Event): The event that was already registered.
        caller (Scene | Waypoint | Path | Mount): The caller object that was already registered.
        action (EventHandler.Action): The action that was already registered.
        target (Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None): The target that was
            already registered.

    """
    self.event = event
    self.caller = caller
    self.action = action
    self.target = target
    self.message = (
        f"Duplicate event registration: Event `{event.name}` with caller `{caller.__class__.__name__}`, "
        f"action `{action.name}`, and target `{target.__class__.__name__ if target is not None else 'None'}` "
        f"has already been registered."
    )
    super().__init__(self.message)

EventRegistrationCallerError

Bases: TerminalTextEffectsError

Raised when an event is registered with an invalid event -> caller relationship.

Each event can only be registered with a related caller type. This error is raised when an event is registered with a caller that is not of the required type. For example, a Scene will never trigger a Path related event, and vice versa.

The following are the valid caller types for each event:

Event -> Caller

- SEGMENT_* -> Path
- PATH_*    -> Path
- SCENE_*   -> Scene
- MOUNT_*   -> Mount
Source code in terminaltexteffects/utils/exceptions/base_character_exceptions.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
class EventRegistrationCallerError(TerminalTextEffectsError):
    """Raised when an event is registered with an invalid event -> caller relationship.

    Each event can only be registered with a related caller type. This error is raised when an event is registered with
    a caller that is not of the required type. For example, a Scene will never trigger a Path related event,
    and vice versa.

    The following are the valid caller types for each event:

    Event -> Caller

        - SEGMENT_* -> Path
        - PATH_*    -> Path
        - SCENE_*   -> Scene
        - MOUNT_*   -> Mount
    """

    def __init__(
        self,
        event: EventHandler.Event,
        caller: Scene | Waypoint | Path | Mount | str,
        required: type[Scene | Waypoint | Path | Mount],
    ) -> None:
        """Initialize an EventRegistrationCallerError.

        Args:
            event (EventHandler.Event): The event that was registered.
            caller (Scene | Waypoint | Path | Mount | str): The object provided to trigger the event.
            required (Scene | Waypoint | Path | Mount): The valid caller types for the event.

        """
        self.event = event
        self.caller = caller
        self.required = required
        self.message = (
            f"Event `{event.name}` registered with caller type `{caller.__class__.__name__}`. Event `{event.name}` "
            f"requires caller type `{required.__name__}`."
        )
        super().__init__(self.message)

__init__(event, caller, required)

Initialize an EventRegistrationCallerError.

Parameters:

Name Type Description Default
event Event

The event that was registered.

 required
caller Scene | Waypoint | Path | Mount | str

The object provided to trigger the event.

 required
required Scene | Waypoint | Path | Mount

The valid caller types for the event.

 required
Source code in terminaltexteffects/utils/exceptions/base_character_exceptions.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def __init__(
    self,
    event: EventHandler.Event,
    caller: Scene | Waypoint | Path | Mount | str,
    required: type[Scene | Waypoint | Path | Mount],
) -> None:
    """Initialize an EventRegistrationCallerError.

    Args:
        event (EventHandler.Event): The event that was registered.
        caller (Scene | Waypoint | Path | Mount | str): The object provided to trigger the event.
        required (Scene | Waypoint | Path | Mount): The valid caller types for the event.

    """
    self.event = event
    self.caller = caller
    self.required = required
    self.message = (
        f"Event `{event.name}` registered with caller type `{caller.__class__.__name__}`. Event `{event.name}` "
        f"requires caller type `{required.__name__}`."
    )
    super().__init__(self.message)

EventRegistrationTargetError

Bases: TerminalTextEffectsError

Raised when an event is registered with an invalid action -> target relationship.

Each event action can only be registered with a related target type. This error is raised when an event action is registered with a target that is not of the required type. For example, an ACTIVATE_SCENE action will can not activate on a Path target.

The following are the valid target types for each action:

Action -> Target

- *_SCENE          -> Scene
- *_PATH           -> Path
- SET_LAYER        -> Int
- SET_COORDINATE   -> Coord
- CALLBACK         -> EventHandler.Callback
- RESET_APPEARANCE -> None
- MOUNT, UNMOUNT   -> Mount
Source code in terminaltexteffects/utils/exceptions/base_character_exceptions.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
class EventRegistrationTargetError(TerminalTextEffectsError):
    """Raised when an event is registered with an invalid action -> target relationship.

    Each event action can only be registered with a related target type. This error is raised when an event action
    is registered with a target that is not of the required type. For example, an ACTIVATE_SCENE action
    will can not activate on a Path target.

    The following are the valid target types for each action:

    Action -> Target

        - *_SCENE          -> Scene
        - *_PATH           -> Path
        - SET_LAYER        -> Int
        - SET_COORDINATE   -> Coord
        - CALLBACK         -> EventHandler.Callback
        - RESET_APPEARANCE -> None
        - MOUNT, UNMOUNT   -> Mount
    """

    def __init__(
        self,
        action: EventHandler.Action,
        target: Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None,
        required: type[Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None],
    ) -> None:
        """Initialize an EventRegistrationTargetError.

        Args:
            action (EventHandler.Action): The action that was registered.
            target (Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None): The target provided to
                the action.
            required (type[Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None]): The valid
                target types.

        """
        self.action = action
        self.target = target
        self.required = required
        self.message = (
            f"Event action `{action.name}` registered with target type `{target.__class__.__name__}`. "
            f"Action `{action.name}` requires target type `{required.__name__}`."
        )
        super().__init__(self.message)

__init__(action, target, required)

Initialize an EventRegistrationTargetError.

Parameters:

Name Type Description Default
action Action

The action that was registered.

 required
target Scene | Path | Mount | int | Coord | Callback | str | None

The target provided to the action.

 required
required type[Scene | Path | Mount | int | Coord | Callback | str | None]

The valid target types.

 required
Source code in terminaltexteffects/utils/exceptions/base_character_exceptions.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def __init__(
    self,
    action: EventHandler.Action,
    target: Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None,
    required: type[Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None],
) -> None:
    """Initialize an EventRegistrationTargetError.

    Args:
        action (EventHandler.Action): The action that was registered.
        target (Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None): The target provided to
            the action.
        required (type[Scene | Path | Mount | int | Coord | EventHandler.Callback | str | None]): The valid
            target types.

    """
    self.action = action
    self.target = target
    self.required = required
    self.message = (
        f"Event action `{action.name}` registered with target type `{target.__class__.__name__}`. "
        f"Action `{action.name}` requires target type `{required.__name__}`."
    )
    super().__init__(self.message)

InvalidSymbolError

Bases: TerminalTextEffectsError

Raised when a character or visual symbol violates the display-cell contract.

Source code in terminaltexteffects/utils/exceptions/base_character_exceptions.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class InvalidSymbolError(TerminalTextEffectsError):
    """Raised when a character or visual symbol violates the display-cell contract."""

    def __init__(self, symbol: str) -> None:
        """Initialize an `InvalidSymbolError`.

        Args:
            symbol (str): Invalid symbol supplied by the caller or input stream.

        """
        self.symbol = symbol
        self.message = (
            "Symbols must contain exactly one printable Unicode code point with a terminal width of one or two cells. "
            f"Received: {symbol!r}."
        )
        super().__init__(self.message)

__init__(symbol)

Initialize an InvalidSymbolError.

Parameters:

Name Type Description Default
symbol str

Invalid symbol supplied by the caller or input stream.

 required
Source code in terminaltexteffects/utils/exceptions/base_character_exceptions.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
def __init__(self, symbol: str) -> None:
    """Initialize an `InvalidSymbolError`.

    Args:
        symbol (str): Invalid symbol supplied by the caller or input stream.

    """
    self.symbol = symbol
    self.message = (
        "Symbols must contain exactly one printable Unicode code point with a terminal width of one or two cells. "
        f"Received: {symbol!r}."
    )
    super().__init__(self.message)

Motion Exceptions

Custom exceptions for handling errors related to motion in the terminaltexteffects package.

ActivateEmptyPathError

Bases: TerminalTextEffectsError

Raised when attempting to activate an empty Path.

An ActivateEmptyPathError is raised when attempting to activate a Path that has no Waypoints.

Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
class ActivateEmptyPathError(TerminalTextEffectsError):
    """Raised when attempting to activate an empty Path.

    An ActivateEmptyPathError is raised when attempting to activate a Path that has no Waypoints.

    """

    def __init__(self, path_id: str) -> None:
        """Initialize an ActivateEmptyPathError.

        Args:
            path_id (str): The ID of the Path that is empty.

        """
        self.path_id = path_id
        self.message = f"Cannot activate an empty Path `{path_id}`."
        super().__init__(self.message)

__init__(path_id)

Initialize an ActivateEmptyPathError.

Parameters:

Name Type Description Default
path_id str

The ID of the Path that is empty.

 required
Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
73
74
75
76
77
78
79
80
81
82
def __init__(self, path_id: str) -> None:
    """Initialize an ActivateEmptyPathError.

    Args:
        path_id (str): The ID of the Path that is empty.

    """
    self.path_id = path_id
    self.message = f"Cannot activate an empty Path `{path_id}`."
    super().__init__(self.message)

DuplicatePathIDError

Bases: TerminalTextEffectsError

Raised when a Path is initialized with a duplicate ID.

A DuplicatePathIDError is raised when a Path is initialized with an ID that has already been used.

Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
class DuplicatePathIDError(TerminalTextEffectsError):
    """Raised when a Path is initialized with a duplicate ID.

    A DuplicatePathIDError is raised when a Path is initialized with an ID that has already been used.

    """

    def __init__(self, path_id: str) -> None:
        """Initialize a DuplicatePathIDError.

        Args:
            path_id (str): The ID provided to the Path.

        """
        self.path_id = path_id
        self.message = f"Path ID `{path_id}` has already been used."
        super().__init__(self.message)

__init__(path_id)

Initialize a DuplicatePathIDError.

Parameters:

Name Type Description Default
path_id str

The ID provided to the Path.

 required
Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def __init__(self, path_id: str) -> None:
    """Initialize a DuplicatePathIDError.

    Args:
        path_id (str): The ID provided to the Path.

    """
    self.path_id = path_id
    self.message = f"Path ID `{path_id}` has already been used."
    super().__init__(self.message)

DuplicateWaypointIDError

Bases: TerminalTextEffectsError

Raised when a Waypoint is initialized with a duplicate ID.

A DuplicateWaypointIDError is raised when a Waypoint is initialized with an ID that has already been used in the Path.

Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
class DuplicateWaypointIDError(TerminalTextEffectsError):
    """Raised when a Waypoint is initialized with a duplicate ID.

    A DuplicateWaypointIDError is raised when a Waypoint is initialized with an ID that has already been used
    in the Path.

    """

    def __init__(self, waypoint_id: str) -> None:
        """Initialize a DuplicateWaypointIDError.

        Args:
            waypoint_id (str): The ID provided to the Waypoint.

        """
        self.waypoint_id = waypoint_id
        self.message = f"Waypoint ID `{waypoint_id}` has already been used."
        super().__init__(self.message)

__init__(waypoint_id)

Initialize a DuplicateWaypointIDError.

Parameters:

Name Type Description Default
waypoint_id str

The ID provided to the Waypoint.

 required
Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
112
113
114
115
116
117
118
119
120
121
def __init__(self, waypoint_id: str) -> None:
    """Initialize a DuplicateWaypointIDError.

    Args:
        waypoint_id (str): The ID provided to the Waypoint.

    """
    self.waypoint_id = waypoint_id
    self.message = f"Waypoint ID `{waypoint_id}` has already been used."
    super().__init__(self.message)

PathInvalidSpeedError

Bases: TerminalTextEffectsError

Raised when a Path is initialized with an invalid speed.

A Path must be initialized with a speed that is a positive float. This error is raised when a Path is initialized with a speed that is not a positive float.

Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class PathInvalidSpeedError(TerminalTextEffectsError):
    """Raised when a Path is initialized with an invalid speed.

    A Path must be initialized with a speed that is a positive float. This error is raised when a Path is initialized
    with a speed that is not a positive float.

    """

    def __init__(self, speed: float) -> None:
        """Initialize a PathInvalidSpeedError.

        Args:
            speed (float): The speed provided to the Path.

        """
        self.speed = speed
        self.message = f"Path speed must be a positive float. Received: `{speed}`."
        super().__init__(self.message)

__init__(speed)

Initialize a PathInvalidSpeedError.

Parameters:

Name Type Description Default
speed float

The speed provided to the Path.

 required
Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
16
17
18
19
20
21
22
23
24
25
def __init__(self, speed: float) -> None:
    """Initialize a PathInvalidSpeedError.

    Args:
        speed (float): The speed provided to the Path.

    """
    self.speed = speed
    self.message = f"Path speed must be a positive float. Received: `{speed}`."
    super().__init__(self.message)

PathNotFoundError

Bases: TerminalTextEffectsError

Raised when a Path is not found.

A PathNotFoundError is raised when a Path with the given ID is not found.

Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
class PathNotFoundError(TerminalTextEffectsError):
    """Raised when a Path is not found.

    A PathNotFoundError is raised when a Path with the given ID is not found.

    """

    def __init__(self, path_id: str) -> None:
        """Initialize a PathNotFoundError.

        Args:
            path_id (str): The path ID queried.

        """
        self.path_id = path_id
        self.message = f"Path `{path_id}` not found."
        super().__init__(self.message)

__init__(path_id)

Initialize a PathNotFoundError.

Parameters:

Name Type Description Default
path_id str

The path ID queried.

 required
Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
54
55
56
57
58
59
60
61
62
63
def __init__(self, path_id: str) -> None:
    """Initialize a PathNotFoundError.

    Args:
        path_id (str): The path ID queried.

    """
    self.path_id = path_id
    self.message = f"Path `{path_id}` not found."
    super().__init__(self.message)

WaypointNotFoundError

Bases: TerminalTextEffectsError

Raised when a Waypoint is not found in a Path.

A WaypointNotFoundError is raised when a Waypoint with the given ID is not found in a Path.

Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
class WaypointNotFoundError(TerminalTextEffectsError):
    """Raised when a Waypoint is not found in a Path.

    A WaypointNotFoundError is raised when a Waypoint with the given ID is not found in a Path.

    """

    def __init__(self, waypoint_id: str) -> None:
        """Initialize a WaypointNotFoundError.

        Args:
            waypoint_id (str): The waypoint ID queried.

        """
        self.waypoint_id = waypoint_id
        self.message = f"Waypoint `{waypoint_id}` not found in Path."
        super().__init__(self.message)

__init__(waypoint_id)

Initialize a WaypointNotFoundError.

Parameters:

Name Type Description Default
waypoint_id str

The waypoint ID queried.

 required
Source code in terminaltexteffects/utils/exceptions/motion_exceptions.py 
35
36
37
38
39
40
41
42
43
44
def __init__(self, waypoint_id: str) -> None:
    """Initialize a WaypointNotFoundError.

    Args:
        waypoint_id (str): The waypoint ID queried.

    """
    self.waypoint_id = waypoint_id
    self.message = f"Waypoint `{waypoint_id}` not found in Path."
    super().__init__(self.message)

Terminal Exceptions

Custom exceptions for handling errors related to the Terminal in the terminaltexteffects package.

EmptyInputError

Bases: TerminalTextEffectsError

Raised when an effect has no visible input characters to render.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
160
161
162
163
164
165
166
class EmptyInputError(TerminalTextEffectsError):
    """Raised when an effect has no visible input characters to render."""

    def __init__(self) -> None:
        """Initialize an EmptyInputError."""
        self.message = "Input contains no visible characters within the configured canvas."
        super().__init__(self.message)

__init__()

Initialize an EmptyInputError.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
163
164
165
166
def __init__(self) -> None:
    """Initialize an EmptyInputError."""
    self.message = "Input contains no visible characters within the configured canvas."
    super().__init__(self.message)

InvalidCharacterCoordinateError

Bases: TerminalTextEffectsError

Raised when an added character is given an invalid coordinate.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class InvalidCharacterCoordinateError(TerminalTextEffectsError):
    """Raised when an added character is given an invalid coordinate."""

    def __init__(self, coord: object) -> None:
        """Initialize an `InvalidCharacterCoordinateError`.

        Args:
            coord (Coord | object): Coordinate supplied to the terminal.

        """
        self.coord = coord
        self.message = (
            f"Character coordinates must be a Coord containing integer column and row values. Received: {coord!r}."
        )
        super().__init__(self.message)

__init__(coord)

Initialize an InvalidCharacterCoordinateError.

Parameters:

Name Type Description Default
coord Coord | object

Coordinate supplied to the terminal.

 required
Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
46
47
48
49
50
51
52
53
54
55
56
57
def __init__(self, coord: object) -> None:
    """Initialize an `InvalidCharacterCoordinateError`.

    Args:
        coord (Coord | object): Coordinate supplied to the terminal.

    """
    self.coord = coord
    self.message = (
        f"Character coordinates must be a Coord containing integer column and row values. Received: {coord!r}."
    )
    super().__init__(self.message)

InvalidCharacterError

Bases: TerminalTextEffectsError

Raised when a character is not owned by the receiving terminal.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
class InvalidCharacterError(TerminalTextEffectsError):
    """Raised when a character is not owned by the receiving terminal."""

    def __init__(self, character: object) -> None:
        """Initialize an `InvalidCharacterError`.

        Args:
            character (object): Character supplied to the terminal.

        """
        self.character = character
        self.message = f"Character is not owned by this Terminal: {character!r}."
        super().__init__(self.message)

__init__(character)

Initialize an InvalidCharacterError.

Parameters:

Name Type Description Default
character object

Character supplied to the terminal.

 required
Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
16
17
18
19
20
21
22
23
24
25
def __init__(self, character: object) -> None:
    """Initialize an `InvalidCharacterError`.

    Args:
        character (object): Character supplied to the terminal.

    """
    self.character = character
    self.message = f"Character is not owned by this Terminal: {character!r}."
    super().__init__(self.message)

InvalidCharacterGroupError

Bases: TerminalTextEffectsError

Raised when an invalid character group is provided to a Terminal method.

An InvalidCharacterGroupError is raised when a character group is provided to a Terminal method that is not a valid character group.

Ref CharacterGroup.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class InvalidCharacterGroupError(TerminalTextEffectsError):
    """Raised when an invalid character group is provided to a Terminal method.

    An InvalidCharacterGroupError is raised when a character group is provided to a Terminal method that is not a
    valid character group.

    Ref CharacterGroup.

    """

    def __init__(self, character_group: CharacterGroup | str) -> None:
        """Initialize an InvalidCharacterGroupError.

        Args:
            character_group (CharacterGroup | str): The character group provided to the Terminal method.

        """
        self.character_group = character_group
        self.message = f"Invalid character group provided: `{character_group}`. Ref CharacterGroup."
        super().__init__(self.message)

__init__(character_group)

Initialize an InvalidCharacterGroupError.

Parameters:

Name Type Description Default
character_group CharacterGroup | str

The character group provided to the Terminal method.

 required
Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
104
105
106
107
108
109
110
111
112
113
def __init__(self, character_group: CharacterGroup | str) -> None:
    """Initialize an InvalidCharacterGroupError.

    Args:
        character_group (CharacterGroup | str): The character group provided to the Terminal method.

    """
    self.character_group = character_group
    self.message = f"Invalid character group provided: `{character_group}`. Ref CharacterGroup."
    super().__init__(self.message)

InvalidCharacterOrderError

Bases: TerminalTextEffectsError

Raised when a terminal receives an invalid character order.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
84
85
86
87
88
89
90
91
class InvalidCharacterOrderError(TerminalTextEffectsError):
    """Raised when a terminal receives an invalid character order."""

    def __init__(self, character_order: object) -> None:
        """Store the invalid `character_order` and describe the expected type."""
        self.character_order = character_order
        self.message = f"Invalid character order provided: {character_order!r}. Ref CharacterOrder."
        super().__init__(self.message)

__init__(character_order)

Store the invalid character_order and describe the expected type.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
87
88
89
90
91
def __init__(self, character_order: object) -> None:
    """Store the invalid `character_order` and describe the expected type."""
    self.character_order = character_order
    self.message = f"Invalid character order provided: {character_order!r}. Ref CharacterOrder."
    super().__init__(self.message)

InvalidCharacterSortError

Bases: TerminalTextEffectsError

Raised when an invalid character sort is provided to a Terminal method.

An InvalidCharacterSortError is raised when a character sort is provided to a Terminal method that is not a valid character sort.

Ref CharacterSort.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
class InvalidCharacterSortError(TerminalTextEffectsError):
    """Raised when an invalid character sort is provided to a Terminal method.

    An InvalidCharacterSortError is raised when a character sort is provided to a Terminal method that is not a
    valid character sort.

    Ref CharacterSort.

    """

    def __init__(self, character_sort: CharacterSort | str) -> None:
        """Initialize an InvalidCharacterSortError.

        Args:
            character_sort (CharacterSort | str): The character sort provided to the Terminal method.

        """
        self.character_sort = character_sort
        self.message = f"Invalid character sort provided: `{character_sort}`. Ref CharacterSort."
        super().__init__(self.message)

__init__(character_sort)

Initialize an InvalidCharacterSortError.

Parameters:

Name Type Description Default
character_sort CharacterSort | str

The character sort provided to the Terminal method.

 required
Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
126
127
128
129
130
131
132
133
134
135
def __init__(self, character_sort: CharacterSort | str) -> None:
    """Initialize an InvalidCharacterSortError.

    Args:
        character_sort (CharacterSort | str): The character sort provided to the Terminal method.

    """
    self.character_sort = character_sort
    self.message = f"Invalid character sort provided: `{character_sort}`. Ref CharacterSort."
    super().__init__(self.message)

InvalidCharacterVisibilityError

Bases: TerminalTextEffectsError

Raised when a character visibility value is not a boolean.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
class InvalidCharacterVisibilityError(TerminalTextEffectsError):
    """Raised when a character visibility value is not a boolean."""

    def __init__(self, visibility: object) -> None:
        """Initialize an `InvalidCharacterVisibilityError`.

        Args:
            visibility (object): Visibility value supplied to the terminal.

        """
        self.visibility = visibility
        self.message = f"Character visibility must be a bool. Received: {visibility!r}."
        super().__init__(self.message)

__init__(visibility)

Initialize an InvalidCharacterVisibilityError.

Parameters:

Name Type Description Default
visibility object

Visibility value supplied to the terminal.

 required
Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
31
32
33
34
35
36
37
38
39
40
def __init__(self, visibility: object) -> None:
    """Initialize an `InvalidCharacterVisibilityError`.

    Args:
        visibility (object): Visibility value supplied to the terminal.

    """
    self.visibility = visibility
    self.message = f"Character visibility must be a bool. Received: {visibility!r}."
    super().__init__(self.message)

InvalidColorSortError

Bases: TerminalTextEffectsError

Raised when an invalid color sort is provided to a Terminal method.

An InvalidColorSortError is raised when a color sort is provided to a Terminal method that is not a valid color sort.

Ref ColorSort.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
class InvalidColorSortError(TerminalTextEffectsError):
    """Raised when an invalid color sort is provided to a Terminal method.

    An InvalidColorSortError is raised when a color sort is provided to a Terminal method that is not a
    valid color sort.

    Ref ColorSort.

    """

    def __init__(self, color_sort: ColorSort) -> None:
        """Initialize an InvalidColorSortError.

        Args:
            color_sort (ColorSort): The color sort provided to the Terminal method.

        """
        self.color_sort = color_sort
        self.message = f"Invalid color sort provided: `{color_sort}`. Ref ColorSort."
        super().__init__(self.message)

__init__(color_sort)

Initialize an InvalidColorSortError.

Parameters:

Name Type Description Default
color_sort ColorSort

The color sort provided to the Terminal method.

 required
Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
148
149
150
151
152
153
154
155
156
157
def __init__(self, color_sort: ColorSort) -> None:
    """Initialize an InvalidColorSortError.

    Args:
        color_sort (ColorSort): The color sort provided to the Terminal method.

    """
    self.color_sort = color_sort
    self.message = f"Invalid color sort provided: `{color_sort}`. Ref ColorSort."
    super().__init__(self.message)

TerminalOutputActiveError

Bases: TerminalTextEffectsError

Raised when a second terminal attempts to use the global saved cursor position.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
75
76
77
78
79
80
81
class TerminalOutputActiveError(TerminalTextEffectsError):
    """Raised when a second terminal attempts to use the global saved cursor position."""

    def __init__(self) -> None:
        """Initialize a `TerminalOutputActiveError`."""
        self.message = "Another Terminal already owns the active stdout cursor lifecycle."
        super().__init__(self.message)

__init__()

Initialize a TerminalOutputActiveError.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
78
79
80
81
def __init__(self) -> None:
    """Initialize a `TerminalOutputActiveError`."""
    self.message = "Another Terminal already owns the active stdout cursor lifecycle."
    super().__init__(self.message)

TerminalOutputNotPreparedError

Bases: TerminalTextEffectsError

Raised when cursor-relative output is attempted before canvas preparation.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
class TerminalOutputNotPreparedError(TerminalTextEffectsError):
    """Raised when cursor-relative output is attempted before canvas preparation."""

    def __init__(self, operation: str) -> None:
        """Initialize a `TerminalOutputNotPreparedError`.

        Args:
            operation (str): Output operation attempted before preparation.

        """
        self.operation = operation
        self.message = f"Terminal output must be prepared before calling `{operation}()`."
        super().__init__(self.message)

__init__(operation)

Initialize a TerminalOutputNotPreparedError.

Parameters:

Name Type Description Default
operation str

Output operation attempted before preparation.

 required
Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
63
64
65
66
67
68
69
70
71
72
def __init__(self, operation: str) -> None:
    """Initialize a `TerminalOutputNotPreparedError`.

    Args:
        operation (str): Output operation attempted before preparation.

    """
    self.operation = operation
    self.message = f"Terminal output must be prepared before calling `{operation}()`."
    super().__init__(self.message)

UnsupportedAnsiSequenceError

Bases: TerminalTextEffectsError

Raised when terminal input contains ANSI/control sequences TTE does not support.

Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
class UnsupportedAnsiSequenceError(TerminalTextEffectsError):
    """Raised when terminal input contains ANSI/control sequences TTE does not support."""

    def __init__(self, sequence: str) -> None:
        """Initialize an UnsupportedAnsiSequenceError.

        Args:
            sequence (str): The unsupported ANSI/control sequence found in the input.

        """
        self.sequence = sequence
        self.message = (
            f"Unsupported ANSI/control sequence in input: {sequence!r}. "
            "TerminalTextEffects supports common SGR foreground/background color sequences, fetch-style CSI cursor "
            "movement, and selected DEC private mode toggles."
        )
        super().__init__(self.message)

__init__(sequence)

Initialize an UnsupportedAnsiSequenceError.

Parameters:

Name Type Description Default
sequence str

The unsupported ANSI/control sequence found in the input.

 required
Source code in terminaltexteffects/utils/exceptions/terminal_exceptions.py 
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def __init__(self, sequence: str) -> None:
    """Initialize an UnsupportedAnsiSequenceError.

    Args:
        sequence (str): The unsupported ANSI/control sequence found in the input.

    """
    self.sequence = sequence
    self.message = (
        f"Unsupported ANSI/control sequence in input: {sequence!r}. "
        "TerminalTextEffects supports common SGR foreground/background color sequences, fetch-style CSI cursor "
        "movement, and selected DEC private mode toggles."
    )
    super().__init__(self.message)