Add pygame.typing module (#3002)

* Add pygame.typing

* Update relative path; add typing to __init__

* add _co to _T as required by the lint checker

* Modify PathProtocol to pass checks

* Add test

* Refactor module, add temporary docs, rename some typehints

* Hold on let me try to say 3, 9

* Fix format

* Cleanup namespace

* Modify version check

* Format

* Format

* Requested changes

* Fix typo

* Documentation refactor

* Use data instead of attrubute

* typo

* Fix docs

buildconfig/stubs/gen_stubs.py

@@ -4,6 +4,7 @@
 """
 
 import pathlib
+import shutil
 from typing import Any
 
 import pygame.constants
@@ -51,6 +52,7 @@
     "system",
     "geometry",
     "window",
+    "typing",
 ]
 
 # pygame classes that are autoimported into main namespace are kept in this dict
@@ -151,3 +153,8 @@ def get_all(mod: Any):
     for element in get_all(pygame.locals):
         constant_type = getattr(pygame.locals, element).__class__.__name__
         f.write(f"{element}: {constant_type}\n")
+
+# copy typing.py to typing.pyi for type checkers
+typing_py_file = pathlib.Path(__file__).parent.parent.parent / "src_py" / "typing.py"
+typing_stub_file = pathlib.Path(__file__).parent / "pygame" / "typing.pyi"
+shutil.copyfile(typing_py_file, typing_stub_file)

buildconfig/stubs/mypy_allow_list.txt

@@ -2,10 +2,6 @@
 # listed here are not checked by the mypy stubtest program
 # This allowlist supports regex
 
-# This is not a real typestub file, it is used only in the typestubs to export
-# a few utility typestub definitions
-pygame\._common
-
 # cython files have this top level dunder
 pygame\._sdl2\..*\.__test__
 

buildconfig/stubs/pygame/__init__.pyi

@@ -38,6 +38,7 @@ from pygame import (
     system as system,
     geometry as geometry,
     window as window,
+    typing as typing,
 )
 
 from .rect import Rect as Rect, FRect as FRect

buildconfig/stubs/pygame/_sdl2/video.pyi

@@ -5,7 +5,7 @@ from pygame.rect import Rect
 from pygame.surface import Surface
 from pygame.window import Window as Window
 
-from .._common import ColorValue, RectValue, Coordinate
+from pygame.typing import ColorLike, RectLike, Coordinate
 
 WINDOWPOS_UNDEFINED: int
 WINDOWPOS_CENTERED: int
@@ -60,13 +60,13 @@ class Texture:
     @property
     def color(self) -> Color: ...
     @color.setter
-    def color(self, value: ColorValue) -> None: ...
+    def color(self, value: ColorLike) -> None: ...
 
     def get_rect(self, **kwargs: Any) -> Rect: ...
     def draw(
         self,
-        srcrect: Optional[RectValue] = None,
-        dstrect: Optional[RectValue] = None,
+        srcrect: Optional[RectLike] = None,
+        dstrect: Optional[RectLike] = None,
         angle: float = 0.0,
         origin: Optional[Iterable[int]] = None,
         flip_x: bool = False,
@@ -99,17 +99,17 @@ class Texture:
         p3_mod: Iterable[int] = (255, 255, 255, 255),
         p4_mod: Iterable[int] = (255, 255, 255, 255),
     ) -> None: ...
-    def update(self, surface: Surface, area: Optional[RectValue] = None) -> None: ...
+    def update(self, surface: Surface, area: Optional[RectLike] = None) -> None: ...
 
 class Image:
     def __init__(
         self,
         texture_or_image: Union[Texture, Image],
-        srcrect: Optional[RectValue] = None,
+        srcrect: Optional[RectLike] = None,
     ) -> None: ...
     def get_rect(self) -> Rect: ...
     def draw(
-        self, srcrect: Optional[RectValue] = None, dstrect: Optional[RectValue] = None
+        self, srcrect: Optional[RectLike] = None, dstrect: Optional[RectLike] = None
     ) -> None: ...
     angle: float
     origin: Optional[Iterable[float]]
@@ -123,7 +123,7 @@ class Image:
     @property
     def color(self) -> Color: ...
     @color.setter
-    def color(self, value: ColorValue) -> None: ...
+    def color(self, value: ColorLike) -> None: ...
 
 class Renderer:
     def __init__(
@@ -140,25 +140,25 @@ class Renderer:
     @property
     def draw_color(self) -> Color: ...
     @draw_color.setter
-    def draw_color(self, value: ColorValue) -> None: ...
+    def draw_color(self, value: ColorLike) -> None: ...
     def clear(self) -> None: ...
     def present(self) -> None: ...
     def get_viewport(self) -> Rect: ...
-    def set_viewport(self, area: Optional[RectValue]) -> None: ...
+    def set_viewport(self, area: Optional[RectLike]) -> None: ...
     logical_size: Iterable[int]
     scale: Iterable[float]
     target: Optional[Texture]
     def blit(
         self,
         source: Union[Texture, Image],
-        dest: Optional[RectValue] = None,
-        area: Optional[RectValue] = None,
+        dest: Optional[RectLike] = None,
+        area: Optional[RectLike] = None,
         special_flags: int = 0,
     ) -> Rect: ...
     def draw_line(self, p1: Coordinate, p2: Coordinate) -> None: ...
     def draw_point(self, point: Coordinate) -> None: ...
-    def draw_rect(self, rect: RectValue) -> None: ...
-    def fill_rect(self, rect: RectValue) -> None: ...
+    def draw_rect(self, rect: RectLike) -> None: ...
+    def fill_rect(self, rect: RectLike) -> None: ...
     def draw_triangle(
         self, p1: Coordinate, p2: Coordinate, p3: Coordinate
     ) -> None: ...
@@ -172,7 +172,7 @@ class Renderer:
         self, p1: Coordinate, p2: Coordinate, p3: Coordinate, p4: Coordinate
     ) -> None: ...
     def to_surface(
-        self, surface: Optional[Surface] = None, area: Optional[RectValue] = None
+        self, surface: Optional[Surface] = None, area: Optional[RectLike] = None
     ) -> Surface: ...
     @staticmethod
     def compose_custom_blend_mode(

buildconfig/stubs/pygame/camera.pyi

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from typing import List, Optional, Tuple, Union, Literal
 
-from ._common import IntCoordinate
+from pygame.typing import IntCoordinate
 
 from pygame.surface import Surface
 

buildconfig/stubs/pygame/color.pyi

@@ -2,7 +2,7 @@ import sys
 from typing import Any, Dict, Iterator, SupportsIndex, Tuple, Union, overload
 from typing_extensions import deprecated # added in 3.13
 
-from ._common import ColorValue
+from pygame.typing import ColorLike
 
 if sys.version_info >= (3, 9):
     from collections.abc import Collection
@@ -28,7 +28,7 @@ class Color(Collection[int]):
     @overload
     def __init__(self, r: int, g: int, b: int, a: int = 255) -> None: ...
     @overload
-    def __init__(self, rgbvalue: ColorValue) -> None: ...
+    def __init__(self, rgbvalue: ColorLike) -> None: ...
     @overload
     def __getitem__(self, i: SupportsIndex) -> int: ...
     @overload
@@ -82,10 +82,10 @@ class Color(Collection[int]):
     def correct_gamma(self, gamma: float, /) -> Color: ...
     @deprecated("since 2.1.3. Use unpacking instead")
     def set_length(self, length: int, /) -> None: ...
-    def lerp(self, color: ColorValue, amount: float) -> Color: ...
+    def lerp(self, color: ColorLike, amount: float) -> Color: ...
     def premul_alpha(self) -> Color: ...
     def grayscale(self) -> Color: ...
     @overload
     def update(self, r: int, g: int, b: int, a: int = 255, /) -> None: ...
     @overload
-    def update(self, rgbvalue: ColorValue, /) -> None: ...
+    def update(self, rgbvalue: ColorLike, /) -> None: ...

buildconfig/stubs/pygame/cursors.pyi

@@ -2,7 +2,7 @@ from typing import Any, Iterator, Literal, Tuple, Union, overload
 
 from pygame.surface import Surface
 
-from ._common import FileArg, IntCoordinate, Sequence
+from pygame.typing import FileLike, IntCoordinate, SequenceLike
 
 _Small_string = Tuple[
     str, str, str, str, str, str, str, str, str, str, str, str, str, str, str, str
@@ -47,13 +47,13 @@ sizer_xy_strings: _Small_string
 textmarker_strings: _Small_string
 
 def compile(
-    strings: Sequence[str],
+    strings: SequenceLike[str],
     black: str = "X",
     white: str = ".",
     xor: str = "o",
 ) -> Tuple[Tuple[int, ...], Tuple[int, ...]]: ...
 def load_xbm(
-    curs: FileArg, mask: FileArg
+    curs: FileLike, mask: FileLike
 ) -> Tuple[Tuple[int, int], Tuple[int, int], Tuple[int, ...], Tuple[int, ...]]: ...
 
 class Cursor:
@@ -66,8 +66,8 @@ class Cursor:
         self,
         size: IntCoordinate,
         hotspot: IntCoordinate,
-        xormasks: Sequence[int],
-        andmasks: Sequence[int],
+        xormasks: SequenceLike[int],
+        andmasks: SequenceLike[int],
     ) -> None: ...
     @overload
     def __init__(

buildconfig/stubs/pygame/display.pyi

@@ -6,13 +6,13 @@ from pygame.surface import Surface
 
 from pygame._sdl2 import Window
 
-from ._common import (
-    ColorValue,
+from pygame.typing import (
+    ColorLike,
     Coordinate,
     IntCoordinate,
-    RectValue,
-    RGBAOutput,
-    Sequence,
+    RectLike,
+    RGBATuple,
+    SequenceLike,
 )
 
 class _VidInfo:
@@ -21,9 +21,9 @@ class _VidInfo:
     video_mem: int
     bitsize: int
     bytesize: int
-    masks: RGBAOutput
-    shifts: RGBAOutput
-    losses: RGBAOutput
+    masks: RGBATuple
+    shifts: RGBATuple
+    losses: RGBATuple
     blit_hw: int
     blit_hw_CC: int
     blit_hw_A: int
@@ -48,7 +48,7 @@ def get_surface() -> Surface: ...
 def flip() -> None: ...
 @overload
 def update(
-    rectangle: Optional[Union[RectValue, Iterable[Optional[RectValue]]]] = None, /
+    rectangle: Optional[Union[RectLike, Iterable[Optional[RectLike]]]] = None, /
 ) -> None: ...
 @overload
 def update(x: int, y: int, w: int, h: int, /) -> None: ...
@@ -77,12 +77,12 @@ def toggle_fullscreen() -> int: ...
 def set_gamma(red: float, green: float = ..., blue: float = ..., /) -> int: ...
 @deprecated("since 2.1.4. Removed in SDL3")
 def set_gamma_ramp(
-    red: Sequence[int], green: Sequence[int], blue: Sequence[int], /
+    red: SequenceLike[int], green: SequenceLike[int], blue: SequenceLike[int], /
 ) -> int: ...
 def set_icon(surface: Surface, /) -> None: ...
 def set_caption(title: str, icontitle: Optional[str] = None, /) -> None: ...
 def get_caption() -> Tuple[str, str]: ...
-def set_palette(palette: Sequence[ColorValue], /) -> None: ...
+def set_palette(palette: SequenceLike[ColorLike], /) -> None: ...
 def get_num_displays() -> int: ...
 def get_window_size() -> Tuple[int, int]: ...
 def get_window_position() -> Tuple[int, int]:...
@@ -99,7 +99,7 @@ def message_box(
     message: Optional[str] = None,
     message_type: Literal["info", "warn", "error"] = "info",
     parent_window: Optional[Window] = None,
-    buttons: Sequence[str] = ("OK",),
+    buttons: SequenceLike[str] = ("OK",),
     return_button: int = 0,
     escape_button: Optional[int] = None,
 ) -> int: ...