Merge pull request #2292 from pygame-community/ankith26-new-typing

Introduce new custom 'Sequence' ABC, fix issues

Author: oddbookworm

buildconfig/stubs/pygame/_common.pyi

@@ -1,40 +1,104 @@
 from os import PathLike
-from typing import IO, Callable, Sequence, Tuple, Union
+from typing import IO, Callable, Tuple, Union, TypeVar
 
-from typing_extensions import Literal as Literal
+from typing_extensions import Literal as Literal, SupportsIndex as SupportsIndex
 from typing_extensions import Protocol
 
-from pygame.color import Color
-from pygame.math import Vector2
-from pygame.rect import Rect, FRect
-
 # For functions that take a file name
 AnyPath = Union[str, bytes, PathLike[str], PathLike[bytes]]
 
 # Most pygame functions that take a file argument should be able to handle
 # a FileArg type
 FileArg = Union[AnyPath, IO[bytes], IO[str]]
 
-Coordinate = Union[Tuple[float, float], Sequence[float], Vector2]
+_T = TypeVar("_T", covariant=True)
+
+class Sequence(Protocol[_T]):
+    """
+    This is different from the standard python 'Sequence' abc. This is used in places
+    where only __getitem__ and __len__ is actually needed (basically almost all places
+    where a sequence is used). The standard 'Sequence' abc has some extra methods.
+    """
+    def __getitem__(self, __i: SupportsIndex) -> _T: ...
+    def __len__(self) -> int: ...
+
+# Right now, it isn't possible to annotate sizes (popular tools don't support it) but
+# when it is, the below types should be appropriately annotated
+
+# Yes, float. The reason being, pygame handles float without erroring in a lot of places
+# where a coordinate is expected (usually by rounding to int).
+# Also, 'Union[int, float] == float'
+Coordinate = Sequence[float]
+
+# This is used in places where ints are strictly required
+IntCoordinate = Sequence[int]
 
-# This typehint is used when a function would return an RGBA tuble
+# This typehint is used when a function would return an RGBA tuple
 RGBAOutput = Tuple[int, int, int, int]
-ColorValue = Union[Color, int, str, Tuple[int, int, int], RGBAOutput, Sequence[int]]
-
-_CanBeRect = Union[
-    Rect,
-    FRect,
-    Tuple[int, int, int, int],
-    Tuple[float, float, float, float],
-    Tuple[Coordinate, Coordinate],
-    Sequence[int],
-    Sequence[float],
-    Sequence[Coordinate],
-]
+ColorValue = Union[int, str, Sequence[int]]
+
+_CanBeRect = Sequence[Union[float, Coordinate]]
 
 class _HasRectAttribute(Protocol):
     # An object that has a rect attribute that is either a rect, or a function
     # that returns a rect confirms to the rect protocol
     rect: Union[RectValue, Callable[[], RectValue]]
 
 RectValue = Union[_CanBeRect, _HasRectAttribute]
+
+"""
+# testing code
+def a(b: Coordinate):
+    b[0]
+    b[1]
+    len(b)
+    e1, e2 = b
+    for i in b:
+        i -= 1
+
+
+import numpy
+from pygame import Vector2
+
+class MyAmoger:
+    def __init__(self):
+        pass
+
+    def __getitem__(self, index):
+        if index not in (0, 1):
+            raise IndexError()
+
+        return 42 if index else 69
+
+    def __len__(self):
+        return 2
+
+
+# should pass
+a([1, 2])
+a([4.2, 5.2])
+a((1, 2))
+a((1.4, 2.8))
+a(MyAmoger())
+a(range(2, 4))  # yes, range object is a 'Sequence'
+a(numpy.array([1.3, 2.1]))
+a(b"ab")  # weird but this actually works in code (this represents (97, 98) btw)
+a(bytearray([1, 2]))
+a(Vector2())
+
+print("Done testing the passes!")
+
+# should technically error, but right now we can't annotate sizes so they pass on
+# type testing
+a([1, 2, 3])
+a([4.2, 5.2, 2, 4])
+a((1,))
+a(numpy.array([1.3, 2.1, 4.2]))
+
+# all of the below should always error
+a({})
+a({1: 2})
+a("abc")
+a({1, 2})
+
+"""

buildconfig/stubs/pygame/camera.pyi

@@ -1,5 +1,7 @@
 from abc import ABC, abstractmethod
-from typing import List, Optional, Sequence, Tuple, Union
+from typing import List, Optional, Tuple, Union
+
+from ._common import IntCoordinate
 
 from pygame.surface import Surface
 
@@ -31,7 +33,7 @@ class Camera(AbstractCamera):
     def __init__(
         self,
         device: Union[str, int] = 0,
-        size: Union[Tuple[int, int], Sequence[int]] = (640, 480),
+        size: IntCoordinate = (640, 480),
         format: str = "RGB",
     ) -> None: ...
     def start(self) -> None: ...

buildconfig/stubs/pygame/color.pyi

@@ -1,7 +1,7 @@
 import sys
 from typing import Any, Dict, Iterator, Tuple, Union, overload
 
-from ._common import ColorValue
+from ._common import ColorValue, SupportsIndex
 
 if sys.version_info >= (3, 9):
     from collections.abc import Collection
@@ -28,7 +28,7 @@ class Color(Collection[int]):
     @overload
     def __init__(self, rgbvalue: ColorValue) -> None: ...
     @overload
-    def __getitem__(self, i: int) -> int: ...
+    def __getitem__(self, i: SupportsIndex) -> int: ...
     @overload
     def __getitem__(self, s: slice) -> Tuple[int]: ...
     def __setitem__(self, key: int, value: int) -> None: ...

buildconfig/stubs/pygame/cursors.pyi

@@ -1,8 +1,8 @@
-from typing import Any, Iterator, Sequence, Tuple, Union, overload
+from typing import Any, Iterator, Tuple, Union, overload
 
 from pygame.surface import Surface
 
-from ._common import FileArg, Literal
+from ._common import FileArg, Literal, IntCoordinate, Sequence
 
 _Small_string = Tuple[
     str, str, str, str, str, str, str, str, str, str, str, str, str, str, str, str
@@ -64,15 +64,15 @@ class Cursor:
     @overload
     def __init__(
         self,
-        size: Union[Tuple[int, int], Sequence[int]],
-        hotspot: Union[Tuple[int, int], Sequence[int]],
+        size: IntCoordinate,
+        hotspot: IntCoordinate,
         xormasks: Sequence[int],
         andmasks: Sequence[int],
     ) -> None: ...
     @overload
     def __init__(
         self,
-        hotspot: Union[Tuple[int, int], Sequence[int]],
+        hotspot: IntCoordinate,
         surface: Surface,
     ) -> None: ...
     def __iter__(self) -> Iterator[Any]: ...
@@ -81,11 +81,11 @@ class Cursor:
     def __hash__(self) -> int: ...
     def __getitem__(
         self, index: int
-    ) -> Union[int, Tuple[int, int], Sequence[int], Surface]: ...
+    ) -> Union[int, IntCoordinate, Surface]: ...
     copy = __copy__
     type: Literal["system", "color", "bitmap"]
     data: Union[
         Tuple[int],
         Tuple[Tuple[int, int], Tuple[int, int], Tuple[int, ...], Tuple[int, ...]],
-        Tuple[Union[Tuple[int, int], Sequence[int]], Surface],
+        Tuple[IntCoordinate, Surface],
     ]

buildconfig/stubs/pygame/display.pyi

@@ -1,8 +1,16 @@
-from typing import Union, Tuple, List, Optional, Dict, Sequence, overload
+from typing import Dict, List, Optional, Tuple, Union, overload
 
-from pygame.surface import Surface
 from pygame.constants import FULLSCREEN
-from ._common import Coordinate, RectValue, ColorValue, RGBAOutput
+from pygame.surface import Surface
+
+from ._common import (
+    ColorValue,
+    Coordinate,
+    IntCoordinate,
+    RectValue,
+    RGBAOutput,
+    Sequence,
+)
 
 class _VidInfo:
     hw: int
@@ -51,7 +59,7 @@ def list_modes(
     display: int = 0,
 ) -> List[Tuple[int, int]]: ...
 def mode_ok(
-    size: Union[Sequence[int], Tuple[int, int]],
+    size: IntCoordinate,
     flags: int = 0,
     depth: int = 0,
     display: int = 0,

buildconfig/stubs/pygame/draw.pyi

@@ -1,9 +1,7 @@
-from typing import Optional, Sequence
-
 from pygame.rect import Rect
 from pygame.surface import Surface
 
-from ._common import ColorValue, Coordinate, RectValue
+from ._common import ColorValue, Coordinate, RectValue, Sequence
 
 def rect(
     surface: Surface,

buildconfig/stubs/pygame/event.pyi

@@ -3,14 +3,12 @@ from typing import (
     Dict,
     List,
     Optional,
-    Sequence,
-    SupportsInt,
-    Tuple,
     Union,
     final,
-    overload,
 )
 
+from ._common import Sequence
+
 @final
 class Event:
     type: int
@@ -25,7 +23,7 @@ class Event:
     def __delattr__(self, name: str) -> None: ...
     def __bool__(self) -> bool: ...
 
-_EventTypes = Union[SupportsInt, Tuple[SupportsInt, ...], Sequence[SupportsInt]]
+_EventTypes = Union[int, Sequence[int]]
 
 def pump() -> None: ...
 def get(

buildconfig/stubs/pygame/font.pyi

@@ -20,7 +20,7 @@ def match_font(
     italic: Hashable = False,
 ) -> str: ...
 def SysFont(
-    name: Union[str, bytes, Iterable[Union[str, bytes]]],
+    name: Union[str, bytes, Iterable[Union[str, bytes]], None],
     size: int,
     bold: Hashable = False,
     italic: Hashable = False,

buildconfig/stubs/pygame/freetype.pyi

@@ -16,7 +16,7 @@ def get_cache_size() -> int: ...
 def get_default_resolution() -> int: ...
 def set_default_resolution(resolution: int) -> None: ...
 def SysFont(
-    name: Union[str, bytes, Iterable[Union[str, bytes]]],
+    name: Union[str, bytes, Iterable[Union[str, bytes]], None],
     size: int,
     bold: int = False,
     italic: int = False,

buildconfig/stubs/pygame/gfxdraw.pyi

@@ -1,8 +1,6 @@
-from typing import Sequence
-
 from pygame.surface import Surface
 
-from ._common import ColorValue, Coordinate, RectValue
+from ._common import ColorValue, Coordinate, RectValue, Sequence
 
 def pixel(surface: Surface, x: int, y: int, color: ColorValue) -> None: ...
 def hline(surface: Surface, x1: int, x2: int, y: int, color: ColorValue) -> None: ...