Introduce SpriteSequence, a covariant supertype of SpriteList.

This is done by analogy to `collections.abc.Sequence`, which is a
covariant supertype of `list`.

Before this commit, many parts of the codebase used `SpriteList`s
without type arguments (defaulting to `Unknown`). That was the only
way to allow reasonable usages of the given methods and attributes.
However, doing so results in weaker typing.

Using `SpriteSequence`, we can add correct type arguments to almost
all of the references that were using `SpriteList`s before.

The only missing pieces are `Scene` and `TileMap`. Unfortunately,
their APIs are fundamentally unsound wrt. the type arguments of
their `SpriteList`s. We cannot make it sound without breaking their
APIs, so we do not change them.

As a bonus, we can now create lists of `SpriteList`s with varying
type arguments, and generically call `draw` or `update` on them.
Previously, the only common supertype of `SpriteList[A]` and
`SpriteList[B]` was `object`, which meant it was not possible to
call those methods on them.

In a sense, that ability mostly subsumes the convenience provided
by `Scene`. A `list[SpriteSequence[BasicSprite]]` is almost as
convenient, while being type-safe.

Author: sjrd

CHANGELOG.md

@@ -9,6 +9,9 @@ Arcade [PyPi Release History](https://pypi.org/project/arcade/#history) page.
   - Fix `UIScrollArea.add` always returning None
   - Support `layer` in `UIView.add_widget()`
 - Text objects are now lazy and can be created before the window
+- Introduce `arcade.SpriteSequence[T]` as a covariant supertype of `arcade.SpriteList[T]`
+  (this is similar to Python's `Sequence[T]`, which is a supertype of `list[T]`)
+  and various improvements to the typing of the API that leverage it
 
 ## Version 3.1.0
 

arcade/__init__.py

@@ -168,6 +168,7 @@ def configure_logging(level: int | None = None):
 from .sprite import PyMunk
 from .sprite import PymunkMixin
 from .sprite import SpriteType
+from .sprite import SpriteType_co
 from .sprite import Sprite
 from .sprite import BasicSprite
 
@@ -176,6 +177,7 @@ def configure_logging(level: int | None = None):
 from .sprite import SpriteSolidColor
 
 from .sprite_list import SpriteList
+from .sprite_list import SpriteSequence
 from .sprite_list import check_for_collision
 from .sprite_list import check_for_collision_with_list
 from .sprite_list import check_for_collision_with_lists
@@ -283,9 +285,11 @@ def configure_logging(level: int | None = None):
     "BasicSprite",
     "Sprite",
     "SpriteType",
+    "SpriteType_co",
     "PymunkMixin",
     "SpriteCircle",
     "SpriteList",
+    "SpriteSequence",
     "SpriteSolidColor",
     "Text",
     "Texture",

arcade/future/input/input_manager_example.py

@@ -26,7 +26,7 @@ class Player(arcade.Sprite):
     def __init__(
         self,
         texture,
-        walls: arcade.SpriteList[arcade.Sprite],
+        walls: arcade.SpriteSequence[arcade.BasicSprite],
         input_manager_template: InputManager,
         controller: pyglet.input.Controller | None = None,
         center_x: float = 0.0,

arcade/paths.py

@@ -4,14 +4,22 @@
 
 import math
 
-from arcade import Sprite, SpriteList, check_for_collision_with_list, get_sprites_at_point
+from arcade import (
+    BasicSprite,
+    Sprite,
+    SpriteSequence,
+    check_for_collision_with_list,
+    get_sprites_at_point,
+)
 from arcade.math import get_distance, lerp_2d
 from arcade.types import Point2
 
 __all__ = ["AStarBarrierList", "astar_calculate_path", "has_line_of_sight"]
 
 
-def _spot_is_blocked(position: Point2, moving_sprite: Sprite, blocking_sprites: SpriteList) -> bool:
+def _spot_is_blocked(
+    position: Point2, moving_sprite: Sprite, blocking_sprites: SpriteSequence[BasicSprite]
+) -> bool:
     """
     Return if position is blocked
 
@@ -275,7 +283,7 @@ class AStarBarrierList:
     def __init__(
         self,
         moving_sprite: Sprite,
-        blocking_sprites: SpriteList,
+        blocking_sprites: SpriteSequence[BasicSprite],
         grid_size: int,
         left: int,
         right: int,
@@ -372,7 +380,7 @@ def astar_calculate_path(
 def has_line_of_sight(
     observer: Point2,
     target: Point2,
-    walls: SpriteList,
+    walls: SpriteSequence[BasicSprite],
     max_distance: float = float("inf"),
     check_resolution: int = 2,
 ) -> bool:

arcade/physics_engines.py

@@ -8,7 +8,7 @@
 from arcade import (
     BasicSprite,
     Sprite,
-    SpriteList,
+    SpriteSequence,
     SpriteType,
     check_for_collision,
     check_for_collision_with_lists,
@@ -20,7 +20,7 @@
 from arcade.utils import Chain, copy_dunders_unimplemented
 
 
-def _wiggle_until_free(colliding: Sprite, walls: Iterable[SpriteList]) -> None:
+def _wiggle_until_free(colliding: Sprite, walls: Iterable[SpriteSequence[BasicSprite]]) -> None:
     """Kludge to 'guess' a colliding sprite out of a collision.
 
     It works by iterating over increasing wiggle sizes of 8 points
@@ -80,7 +80,7 @@ def _wiggle_until_free(colliding: Sprite, walls: Iterable[SpriteList]) -> None:
 
 
 def _move_sprite(
-    moving_sprite: Sprite, can_collide: Iterable[SpriteList[SpriteType]], ramp_up: bool
+    moving_sprite: Sprite, can_collide: Iterable[SpriteSequence[SpriteType]], ramp_up: bool
 ) -> list[SpriteType]:
     """Update a sprite's angle and position, returning a list of collisions.
 
@@ -273,11 +273,14 @@ def _move_sprite(
     return complete_hit_list
 
 
-def _add_to_list(dest: list[SpriteList], source: SpriteList | Iterable[SpriteList] | None) -> None:
-    """Helper function to add a SpriteList or list of SpriteLists to a list."""
+def _add_to_list(
+    dest: list[SpriteSequence[SpriteType]],
+    source: SpriteSequence[SpriteType] | Iterable[SpriteSequence[SpriteType]] | None,
+) -> None:
+    """Helper function to add a SpriteSequence or list of SpriteSequences to a list."""
     if not source:
         return
-    elif isinstance(source, SpriteList):
+    elif isinstance(source, SpriteSequence):
         dest.append(source)
     else:
         dest.extend(source)
@@ -310,17 +313,17 @@ class PhysicsEngineSimple:
     def __init__(
         self,
         player_sprite: Sprite,
-        walls: SpriteList | Iterable[SpriteList] | None = None,
+        walls: SpriteSequence[BasicSprite] | Iterable[SpriteSequence[BasicSprite]] | None = None,
     ) -> None:
         self.player_sprite: Sprite = player_sprite
         """The player-controlled :py:class:`.Sprite`."""
-        self._walls: list[SpriteList] = []
+        self._walls: list[SpriteSequence[BasicSprite]] = []
 
         if walls:
             _add_to_list(self._walls, walls)
 
     @property
-    def walls(self) -> list[SpriteList]:
+    def walls(self) -> list[SpriteSequence[BasicSprite]]:
         """Which :py:class:`.SpriteList` instances block player movement.
 
         .. important:: Avoid moving sprites in these lists!
@@ -334,7 +337,10 @@ def walls(self) -> list[SpriteList]:
         return self._walls
 
     @walls.setter
-    def walls(self, walls: SpriteList | Iterable[SpriteList] | None = None) -> None:
+    def walls(
+        self,
+        walls: SpriteSequence[BasicSprite] | Iterable[SpriteSequence[BasicSprite]] | None = None,
+    ) -> None:
         if walls:
             _add_to_list(self._walls, walls)
         else:
@@ -429,17 +435,17 @@ class PhysicsEnginePlatformer:
     def __init__(
         self,
         player_sprite: Sprite,
-        platforms: SpriteList | Iterable[SpriteList] | None = None,
+        platforms: SpriteSequence[Sprite] | Iterable[SpriteSequence[Sprite]] | None = None,
         gravity_constant: float = 0.5,
-        ladders: SpriteList | Iterable[SpriteList] | None = None,
-        walls: SpriteList | Iterable[SpriteList] | None = None,
+        ladders: SpriteSequence[BasicSprite] | Iterable[SpriteSequence[BasicSprite]] | None = None,
+        walls: SpriteSequence[BasicSprite] | Iterable[SpriteSequence[BasicSprite]] | None = None,
     ) -> None:
         if not isinstance(player_sprite, Sprite):
             raise TypeError("player_sprite must be a Sprite, not a basic_sprite!")
 
-        self._ladders: list[SpriteList] = []
-        self._platforms: list[SpriteList] = []
-        self._walls: list[SpriteList] = []
+        self._ladders: list[SpriteSequence[BasicSprite]] = []
+        self._platforms: list[SpriteSequence[Sprite]] = []
+        self._walls: list[SpriteSequence[BasicSprite]] = []
         self._all_obstacles = Chain(self._walls, self._platforms)
 
         _add_to_list(self._ladders, ladders)
@@ -517,7 +523,7 @@ def __init__(
     # TODO: figure out what do do with 15_ladders_moving_platforms.py
     # It's no longer used by any example or tutorial file
     @property
-    def ladders(self) -> list[SpriteList]:
+    def ladders(self) -> list[SpriteSequence[BasicSprite]]:
         """Ladders turn off gravity while touched by the player.
 
         This means that whenever the :py:attr:`player_sprite` collides
@@ -533,7 +539,10 @@ def ladders(self) -> list[SpriteList]:
         return self._ladders
 
     @ladders.setter
-    def ladders(self, ladders: SpriteList | Iterable[SpriteList] | None = None) -> None:
+    def ladders(
+        self,
+        ladders: SpriteSequence[BasicSprite] | Iterable[SpriteSequence[BasicSprite]] | None = None,
+    ) -> None:
         if ladders:
             _add_to_list(self._ladders, ladders)
         else:
@@ -544,7 +553,7 @@ def ladders(self) -> None:
         self._ladders.clear()
 
     @property
-    def platforms(self) -> list[SpriteList]:
+    def platforms(self) -> list[SpriteSequence[Sprite]]:
         """:py:class:`~arcade.sprite_list.sprite_list.SpriteList` instances containing platforms.
 
         .. important:: For best performance, put non-moving terrain in
@@ -575,7 +584,9 @@ def platforms(self) -> list[SpriteList]:
         return self._platforms
 
     @platforms.setter
-    def platforms(self, platforms: SpriteList | Iterable[SpriteList] | None = None) -> None:
+    def platforms(
+        self, platforms: SpriteSequence[Sprite] | Iterable[SpriteSequence[Sprite]] | None = None
+    ) -> None:
         if platforms:
             _add_to_list(self._platforms, platforms)
         else:
@@ -586,7 +597,7 @@ def platforms(self) -> None:
         self._platforms.clear()
 
     @property
-    def walls(self) -> list[SpriteList]:
+    def walls(self) -> list[SpriteSequence[BasicSprite]]:
         """Exposes the :py:class:`SpriteList` instances use as terrain.
 
         .. important:: For best performance, only add non-moving sprites!
@@ -611,7 +622,10 @@ def walls(self) -> list[SpriteList]:
         return self._walls
 
     @walls.setter
-    def walls(self, walls: SpriteList | Iterable[SpriteList] | None = None) -> None:
+    def walls(
+        self,
+        walls: SpriteSequence[BasicSprite] | Iterable[SpriteSequence[BasicSprite]] | None = None,
+    ) -> None:
         if walls:
             _add_to_list(self._walls, walls)
         else:

arcade/sprite/__init__.py

@@ -4,7 +4,7 @@
 
 from arcade.texture import Texture
 from arcade.resources import resolve
-from .base import BasicSprite, SpriteType
+from .base import BasicSprite, SpriteType, SpriteType_co
 from .sprite import Sprite
 from .mixins import PymunkMixin, PyMunk
 from .animated import (
@@ -69,6 +69,7 @@ def load_animated_gif(resource_name: str | Path) -> TextureAnimationSprite:
 
 __all__ = [
     "SpriteType",
+    "SpriteType_co",
     "BasicSprite",
     "Sprite",
     "PyMunk",

arcade/sprite/base.py

@@ -16,6 +16,9 @@
 # Type from sprite that can be any BasicSprite or any subclass of BasicSprite
 SpriteType = TypeVar("SpriteType", bound="BasicSprite")
 
+# Same as SpriteType, for covariant type parameters
+SpriteType_co = TypeVar("SpriteType_co", bound="BasicSprite", covariant=True)
+
 
 @copy_dunders_unimplemented  # See https://github.com/pythonarcade/arcade/issues/2074
 class BasicSprite:

arcade/sprite_list/__init__.py

@@ -1,4 +1,4 @@
-from .sprite_list import SpriteList
+from .sprite_list import SpriteList, SpriteSequence
 from .spatial_hash import SpatialHash
 from .collision import (
     get_distance_between_sprites,
@@ -14,6 +14,7 @@
 
 __all__ = [
     "SpriteList",
+    "SpriteSequence",
     "SpatialHash",
     "get_distance_between_sprites",
     "get_closest_sprite",