Address review comments.

Notably, make ReadOnlySpriteHash inherit Protocol.

Author: sjrd

arcade/sprite_list/spatial_hash.py

@@ -1,24 +1,33 @@
 from abc import abstractmethod
+from collections.abc import Set
 from math import trunc
-from typing import Generic
+from typing import Protocol
 
 from arcade.sprite import SpriteType, SpriteType_co
 from arcade.sprite.base import BasicSprite
 from arcade.types import IPoint, Point
 from arcade.types.rect import Rect
 
 
-class ReadOnlySpatialHash(Generic[SpriteType_co]):
-    """
-    Read-only view of a SpatialHash.
+class ReadOnlySpatialHash(Protocol[SpriteType_co]):
+    """A read-only view of a :py:class:`.SpatialHash` which helps preserve safety.
+
+    This works like the read-only views of Python's built-in :py:class:`dict`
+    and other types. As an every-day user, it means that the underlying
+    `SpatialHash` may contain subclasses of the annotated type, but not
+    superclasses.
 
-    This is useful when the SpriteType is in covariant position.
+    This ensures predicable behavior via type safety in cases where:
 
-    See SpatialHash for more details.
+    #. A spatial hash is annotated with a specific type
+    #. It is then manipulated outside the original context with a broader type
+
+    Advanced users who want more information on the specifics should see the
+    comments of :py:class:`~arcade.sprite_list.SpriteList`.
     """
 
     @abstractmethod
-    def get_sprites_near_sprite(self, sprite: BasicSprite) -> set[SpriteType_co]:
+    def get_sprites_near_sprite(self, sprite: BasicSprite) -> Set[SpriteType_co]:
         """
         Get all the sprites that are in the same buckets as the given sprite.
 
@@ -28,7 +37,7 @@ def get_sprites_near_sprite(self, sprite: BasicSprite) -> set[SpriteType_co]:
         ...
 
     @abstractmethod
-    def get_sprites_near_point(self, point: Point) -> set[SpriteType_co]:
+    def get_sprites_near_point(self, point: Point) -> Set[SpriteType_co]:
         """
         Return sprites in the same bucket as the given point.
 
@@ -38,12 +47,17 @@ def get_sprites_near_point(self, point: Point) -> set[SpriteType_co]:
         ...
 
     @abstractmethod
-    def get_sprites_near_rect(self, rect: Rect) -> set[SpriteType_co]:
+    def get_sprites_near_rect(self, rect: Rect) -> Set[SpriteType_co]:
         """
         Return sprites in the same buckets as the given rectangle.
 
+        .. tip:: Use :py:mod:`arcade.types.rect`'s helper functions to create
+          rectangle objects!
+
         Args:
-            rect: The rectangle to check (left, right, bottom, top)
+            rect:
+                The rectangle to check as a :py:class:`~arcade.types.rect.Rect`
+                object.
         """
         ...
 

arcade/sprite_list/sprite_list.py

@@ -41,14 +41,13 @@
 
 
 class SpriteSequence(Collection[SpriteType_co]):
-    """
-    A read-only view of a SpriteList.
+    """A read-only view of a :py:class:`.SpriteList`.
 
-    Like collections.abc.Sequence, a SpriteSequence is covariant in its sprite
-    type. This is useful when you want to manipulate a collection of
-    SpriteLists of different sprite types.
+    Like other read-only generics such as :py:class:`collections.abc.Sequence`,
+    a `SpriteSequence` requires sprites be of a covariant type relative to their
+    annotated type.
 
-    See SpriteList for more details.
+    See :py:class:`.SpriteList` for more details.
     """
 
     from ..sprite_list import spatial_hash as sh