Separate exceptions/warnings from utils (#2292)

Author: einarf

arcade/exceptions.py

@@ -0,0 +1,141 @@
+"""
+Custom arcade errors, exceptions, and warnings.
+"""
+
+import functools
+import warnings
+from typing import Type, TypeVar
+
+__all__ = [
+    "OutsideRangeError",
+    "IntOutsideRangeError",
+    "FloatOutsideRangeError",
+    "ByteRangeError",
+    "NormalizedRangeError",
+    "PerformanceWarning",
+    "ReplacementWarning",
+    "warning",
+]
+
+# Since this module forbids importing from the rest of
+# Arcade, we make our own local type variables.
+_TType = TypeVar("_TType", bound=Type)
+_CT = TypeVar("_CT")  # Comparable type, ie supports the <= operator
+
+
+class OutsideRangeError(ValueError):
+    """
+    Raised when a value is outside and expected range
+
+    This class and its subclasses are intended to be arcade-internal
+    helpers to clearly signal exactly what went wrong. Each helps
+    type annotate and template a string describing exactly what went
+    wrong.
+
+    Args:
+        var_name: The name of the variable or argument
+        value: The value that fell outside the expected range
+        lower: The lower bound, inclusive, of the range
+        upper: The upper bound, inclusive, of the range
+    """
+
+    def __init__(self, var_name: str, value: _CT, lower: _CT, upper: _CT) -> None:
+        super().__init__(f"{var_name} must be between {lower} and {upper}, inclusive, not {value}")
+        self.var_name = var_name
+        self.value = value
+        self.lower = lower
+        self.upper = upper
+
+
+class IntOutsideRangeError(OutsideRangeError):
+    """
+    An integer was outside an expected range
+
+    This class was originally intended to assist deserialization from
+    data packed into ints, such as :py:class:`~arcade.types.Color`.
+
+    Args:
+        var_name: The name of the variable or argument
+        value: The value that fell outside the expected range
+        lower: The lower bound, inclusive, of the range
+        upper: The upper bound, inclusive, of the range
+    """
+
+    def __init__(self, var_name: str, value: int, lower: int, upper: int) -> None:
+        super().__init__(var_name, value, lower, upper)
+
+
+class FloatOutsideRangeError(OutsideRangeError):
+    """
+    A float value was outside an expected range
+
+    Args:
+        var_name: The name of the variable or argument
+        value: The value that fell outside the expected range
+        lower: The lower bound, inclusive, of the range
+        upper: The upper bound, inclusive, of the range
+    """
+
+    def __init__(self, var_name: str, value: float, lower: float, upper: float) -> None:
+        super().__init__(var_name, value, lower, upper)
+
+
+class ByteRangeError(IntOutsideRangeError):
+    """
+    An int was outside the range of 0 to 255 inclusive
+
+    :param var_name: the name of the variable or argument
+    :param value: the value to fall outside the expected range
+    """
+
+    def __init__(self, var_name: str, value: int) -> None:
+        super().__init__(var_name, value, 0, 255)
+
+
+class NormalizedRangeError(FloatOutsideRangeError):
+    """
+    A float was not between 0.0 and 1.0, inclusive
+
+    Note that normalized floats should not normally be bound-checked as
+    before drawing as this is taken care of on the GPU side.
+
+    The exceptions to this are when processing data on the Python side,
+    especially when it is cheaper to bound check two floats than call
+    clamping functions.
+
+    :param var_name: the name of the variable or argument
+    :param value: the value to fall outside the expected range
+    """
+
+    def __init__(self, var_name: str, value: float) -> None:
+        super().__init__(var_name, value, 0.0, 1.0)
+
+
+class PerformanceWarning(Warning):
+    """Issuing performance warnings on slow paths."""
+
+    pass
+
+
+class ReplacementWarning(Warning):
+    """Issuing warnings about naming and functionality changes."""
+
+    pass
+
+
+def warning(warning_type: type[Warning], message: str = "", **kwargs):
+    """Warning decorator"""
+
+    def actual_warning_decorator(func):
+        nonlocal message
+        if warning_type == ReplacementWarning and not message:
+            message = f"{func.__name__} is deprecated. Use {kwargs.get('new_name', '')} instead."
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.warn(message, warning_type)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return actual_warning_decorator

arcade/resources/__init__.py

@@ -2,7 +2,7 @@
 
 from pathlib import Path
 from typing import Sequence
-from arcade.utils import warning, ReplacementWarning
+from arcade.exceptions import warning, ReplacementWarning
 
 #: The absolute path to this directory
 RESOURCE_DIR = Path(__file__).parent.resolve()

arcade/sprite/base.py

@@ -6,10 +6,11 @@
 
 import arcade
 from arcade.color import BLACK, WHITE
+from arcade.exceptions import ReplacementWarning, warning
 from arcade.hitbox import HitBox
 from arcade.texture import Texture
 from arcade.types import LRBT, RGBA255, AsFloat, Color, Point, Point2, PointList, Rect, RGBOrA255
-from arcade.utils import ReplacementWarning, copy_dunders_unimplemented, warning
+from arcade.utils import copy_dunders_unimplemented
 
 if TYPE_CHECKING:
     from arcade.sprite_list import SpriteList

arcade/text.py

@@ -10,10 +10,10 @@
 import pyglet
 
 import arcade
+from arcade.exceptions import PerformanceWarning, warning
 from arcade.resources import resolve
 from arcade.texture_atlas import TextureAtlasBase
 from arcade.types import Color, Point, RGBOrA255
-from arcade.utils import PerformanceWarning, warning
 
 __all__ = ["load_font", "Text", "create_text_sprite", "draw_text"]
 

arcade/types/color.py

@@ -25,7 +25,7 @@
 
 from typing_extensions import Final, Self
 
-from arcade.utils import ByteRangeError, IntOutsideRangeError, NormalizedRangeError
+from arcade.exceptions import ByteRangeError, IntOutsideRangeError, NormalizedRangeError
 
 __all__ = (
     "Color",