Polish stubs with deprecated decorator (pygame-community#2984)

* Remove deprecated features from the stubs

* Remove a few more functions

* Allow missing stub files in stubcheck.py

* Fix allowed stubs

* Use regex to avoid repetition

* Add back the functions with deprecation docstrings

* Forgot one comment

* Forgot one import

* Use deprecated decorator

* Make messages clearer

* Forgot about window.pyi

* Remove line and add one deprecation

* Add decorator to set_system_cursor

buildconfig/stubs/pygame/color.pyi

@@ -1,5 +1,6 @@
 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
 
@@ -79,6 +80,7 @@ class Color(Collection[int]):
     def from_normalized(cls, r: float, g: float, b: float, a: float, /) -> Color: ...
     def normalize(self) -> Tuple[float, float, float, float]: ...
     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 premul_alpha(self) -> Color: ...

buildconfig/stubs/pygame/display.pyi

@@ -1,4 +1,5 @@
 from typing import Dict, List, Optional, Tuple, Union, overload, Literal
+from typing_extensions import deprecated # added in 3.13
 
 from pygame.constants import FULLSCREEN
 from pygame.surface import Surface
@@ -72,7 +73,9 @@ def gl_set_attribute(flag: int, value: int, /) -> None: ...
 def get_active() -> bool: ...
 def iconify() -> bool: ...
 def toggle_fullscreen() -> int: ...
+@deprecated("since 2.1.4. Removed in SDL3")
 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], /
 ) -> int: ...

buildconfig/stubs/pygame/freetype.pyi

@@ -1,4 +1,5 @@
 from typing import Any, Callable, Iterable, List, Optional, Tuple, Union
+from typing_extensions import deprecated # added in 3.13
 
 from pygame.color import Color
 from pygame.rect import Rect
@@ -11,6 +12,7 @@ def get_version(linked: bool = True) -> Tuple[int, int, int]: ...
 def init(cache_size: int = 64, resolution: int = 72) -> None: ...
 def quit() -> None: ...
 def get_init() -> bool: ...
+@deprecated("Use `pygame.freetype.get_init` instead")
 def was_init() -> bool: ...
 def get_cache_size() -> int: ...
 def get_default_resolution() -> int: ...

buildconfig/stubs/pygame/image.pyi

@@ -1,47 +1,48 @@
 from typing import Literal, Optional, Tuple, Union
+from typing_extensions import deprecated # added in 3.13
 
 from pygame.bufferproxy import BufferProxy
 from pygame.surface import Surface
 
 from ._common import FileArg, IntCoordinate, Coordinate
 
 _BufferStyle = Union[BufferProxy, bytes, bytearray, memoryview]
-_to_string_format = Literal[
+_to_bytes_format = Literal[
     "P", "RGB", "RGBX", "RGBA", "ARGB", "BGRA", "ABGR", "RGBA_PREMULT", "ARGB_PREMULT"
 ]
 _from_buffer_format = Literal["P", "RGB", "BGR", "BGRA", "RGBX", "RGBA", "ARGB"]
-_from_string_format = Literal["P", "RGB", "RGBX", "RGBA", "ARGB", "BGRA", "ABGR"]
+_from_bytes_format = Literal["P", "RGB", "RGBX", "RGBA", "ARGB", "BGRA", "ABGR"]
 
 def load(file: FileArg, namehint: str = "") -> Surface: ...
 def load_sized_svg(file: FileArg, size: Coordinate) -> Surface: ...
 def save(surface: Surface, file: FileArg, namehint: str = "") -> None: ...
 def get_sdl_image_version(linked: bool = True) -> Optional[Tuple[int, int, int]]: ...
 def get_extended() -> bool: ...
+@deprecated("since 2.3.0. Use `pygame.image.tobytes` instead")
 def tostring(
     surface: Surface,
-    format: _to_string_format,
+    format: _to_bytes_format,
     flipped: bool = False,
     pitch: int = -1,
 ) -> bytes: ...
+@deprecated("since 2.3.0. Use `pygame.image.frombytes` instead")
 def fromstring(
     bytes: bytes,
     size: IntCoordinate,
-    format: _from_string_format,
+    format: _from_bytes_format,
     flipped: bool = False,
     pitch: int = -1,
 ) -> Surface: ...
-
-# the use of tobytes/frombytes is preferred over tostring/fromstring
 def tobytes(
     surface: Surface,
-    format: _to_string_format,
+    format: _to_bytes_format,
     flipped: bool = False,
     pitch: int = -1,
 ) -> bytes: ...
 def frombytes(
     bytes: bytes,
     size: IntCoordinate,
-    format: _from_string_format,
+    format: _from_bytes_format,
     flipped: bool = False,
     pitch: int = -1,
 ) -> Surface: ...

buildconfig/stubs/pygame/joystick.pyi

@@ -1,4 +1,5 @@
 from typing import Tuple, final
+from typing_extensions import deprecated # added in 3.13
 
 def init() -> None: ...
 def quit() -> None: ...
@@ -7,9 +8,11 @@ def get_count() -> int: ...
 @final
 class JoystickType:
     def __init__(self, id: int) -> None: ...
+    @deprecated("since 2.0.0. Multiple initializations are not supported anymore")
     def init(self) -> None: ...
     def quit(self) -> None: ...
     def get_init(self) -> bool: ...
+    @deprecated("since 2.0.0. Use `pygame.Joystick.get_instance_id` instead")
     def get_id(self) -> int: ...
     def get_instance_id(self) -> int: ...
     def get_guid(self) -> str: ...

buildconfig/stubs/pygame/math.pyi

@@ -14,6 +14,7 @@ from typing import (
     overload,
     Optional
 )
+from typing_extensions import deprecated # added in 3.13
 
 if sys.version_info >= (3, 9):
     from collections.abc import Collection
@@ -232,6 +233,7 @@ class Vector2(_GenericVector):
     def rotate_rad(self: _TVec, angle: float, /) -> _TVec: ...
     def rotate_ip(self, angle: float, /) -> None: ...
     def rotate_rad_ip(self, angle: float, /) -> None: ...
+    @deprecated("since 2.1.1. Use `pygame.Vector2.rotate_rad_ip` instead")
     def rotate_ip_rad(self, angle: float, /) -> None: ...
     def cross(self: _TVec, other: Union[Sequence[float], _TVec], /) -> float: ...
     def as_polar(self) -> Tuple[float, float]: ...
@@ -305,23 +307,27 @@ class Vector3(_GenericVector):
     def rotate_rad_ip(
         self: _TVec, angle: float, axis: Union[Sequence[float], _TVec], /
     ) -> None: ...
+    @deprecated("since 2.1.1. Use `pygame.Vector3.rotate_rad_ip` instead")
     def rotate_ip_rad(
         self: _TVec, angle: float, axis: Union[Sequence[float], _TVec], /
     ) -> None: ...
     def rotate_x(self: _TVec, angle: float, /) -> _TVec: ...
     def rotate_x_rad(self: _TVec, angle: float, /) -> _TVec: ...
     def rotate_x_ip(self, angle: float, /) -> None: ...
     def rotate_x_rad_ip(self, angle: float, /) -> None: ...
+    @deprecated("since 2.1.1. Use `pygame.Vector3.rotate_x_rad_ip` instead")
     def rotate_x_ip_rad(self, angle: float, /) -> None: ...
     def rotate_y(self: _TVec, angle: float, /) -> _TVec: ...
     def rotate_y_rad(self: _TVec, angle: float, /) -> _TVec: ...
     def rotate_y_ip(self, angle: float, /) -> None: ...
     def rotate_y_rad_ip(self, angle: float, /) -> None: ...
+    @deprecated("since 2.1.1. Use `pygame.Vector3.rotate_y_rad_ip` instead")
     def rotate_y_ip_rad(self, angle: float, /) -> None: ...
     def rotate_z(self: _TVec, angle: float, /) -> _TVec: ...
     def rotate_z_rad(self: _TVec, angle: float, /) -> _TVec: ...
     def rotate_z_ip(self, angle: float, /) -> None: ...
     def rotate_z_rad_ip(self, angle: float, /) -> None: ...
+    @deprecated("since 2.1.1. Use `pygame.Vector3.rotate_z_rad_ip` instead")
     def rotate_z_ip_rad(self, angle: float, /) -> None: ...
     def as_spherical(self) -> Tuple[float, float, float]: ...
     def from_spherical(self, spherical: Tuple[float, float, float], /) -> None: ...
@@ -339,7 +345,7 @@ def invlerp(a: float, b: float, value: float, /) -> float: ...
 def remap(i_min: float, i_max: float, o_min: float, o_max: float, value: float, /) -> float: ...
 def smoothstep(a: float, b: float, weight: float, /) -> float: ...
 
-
-# typehints for deprecated functions, to be removed in a future version
+@deprecated("Functionality is removed")
 def enable_swizzling() -> None: ...
+@deprecated("Functionality is removed")
 def disable_swizzling() -> None: ...

buildconfig/stubs/pygame/mouse.pyi

@@ -1,4 +1,6 @@
 from typing import Literal, Tuple, overload
+from typing_extensions import deprecated # added in 3.13
+
 from pygame.cursors import Cursor
 from pygame.surface import Surface
 
@@ -33,6 +35,7 @@ def set_cursor(
 @overload
 def set_cursor(hotspot: IntCoordinate, surface: Surface) -> None: ...
 def get_cursor() -> Cursor: ...
+@deprecated("since 2.2.0. Use `pygame.mouse.set_cursor` instead")
 def set_system_cursor(cursor: int, /) -> None: ...
 def get_relative_mode() -> bool: ...
 def set_relative_mode(enable: bool, /) -> None: ...

buildconfig/stubs/pygame/scrap.pyi

@@ -1,13 +1,22 @@
 from typing import List, Optional
+from typing_extensions import deprecated # added in 3.13
 from collections.abc import ByteString
 
+@deprecated("since 2.2.0. Use the new API instead, which only requires display init")
 def init() -> None: ...
+@deprecated("since 2.2.0. Use the new API instead, which doesn't require scrap init")
 def get_init() -> bool: ...
+@deprecated("since 2.2.0. Use the new API instead: `pygame.scrap.get_text`")
 def get(data_type: str, /) -> Optional[bytes]: ...
+@deprecated("since 2.2.0. Use the new API instead, which only supports strings")
 def get_types() -> List[str]: ...
+@deprecated("since 2.2.0. Use the new API instead: `pygame.scrap.put_text`")
 def put(data_type: str, data: ByteString, /) -> None: ...
+@deprecated("since 2.2.0. Use the new API instead: `pygame.scrap.has_text`")
 def contains(data_type: str, /) -> bool: ...
+@deprecated("since 2.2.0. Use the new API instead, which uses system clipboard")
 def lost() -> bool: ...
+@deprecated("since 2.2.0. Use the new API instead, which only supports strings")
 def set_mode(mode: int, /) -> None: ...
 def put_text(text: str, /) -> None: ...
 def get_text() -> str: ...

buildconfig/stubs/pygame/sndarray.pyi

@@ -1,4 +1,5 @@
 from typing import Tuple
+from typing_extensions import deprecated # added in 3.13
 
 import numpy
 
@@ -7,6 +8,9 @@ from pygame.mixer import Sound
 def array(sound: Sound) -> numpy.ndarray: ...
 def samples(sound: Sound) -> numpy.ndarray: ...
 def make_sound(array: numpy.ndarray) -> Sound: ...
+@deprecated("Only numpy is supported")
 def use_arraytype(arraytype: str) -> Sound: ...
+@deprecated("Only numpy is supported")
 def get_arraytype() -> str: ...
+@deprecated("Only numpy is supported")
 def get_arraytypes() -> Tuple[str]: ...

buildconfig/stubs/pygame/sprite.pyi

@@ -13,6 +13,7 @@ from typing import (
     TypeVar,
     Union,
 )
+from typing_extensions import deprecated # added in 3.13
 
 from pygame.rect import FRect, Rect
 from pygame.surface import Surface
@@ -180,12 +181,15 @@ class Group(AbstractGroup[_TSprite]):
     def __init__(
         self, *sprites: Union[_TSprite, AbstractGroup[_TSprite], Iterable[_TSprite]]
     ) -> None: ...
-
+    
 # these are aliased in the code too
-RenderPlain = Group
-RenderClear = Group
+@deprecated("Use `pygame.sprite.Group` instead")
+class RenderPlain(Group): ...
+@deprecated("Use `pygame.sprite.Group` instead")
+class RenderClear(Group): ...
 
 class RenderUpdates(Group[_TSprite]): ...
+@deprecated("Use `pygame.sprite.RenderUpdates` instead")
 class OrderedUpdates(RenderUpdates[_TSprite]): ...
 
 class LayeredUpdates(AbstractGroup[_TSprite]):
@@ -234,8 +238,10 @@ class LayeredDirty(LayeredUpdates[_TDirtySprite]):
     def set_timing_threshold(
         self, time_ms: SupportsFloat
     ) -> None: ...  # This actually accept any value
-    # deprecated alias
-    set_timing_treshold = set_timing_threshold
+    @deprecated("since 2.1.1. Use `pygame.sprite.LayeredDirty.set_timing_threshold` instead")
+    def set_timing_treshold(
+        self, time_ms: SupportsFloat
+    ) -> None: ...
 
 class GroupSingle(AbstractGroup[_TSprite]):
     sprite: _TSprite

buildconfig/stubs/pygame/surface.pyi

@@ -1,4 +1,5 @@
 from typing import Any, Iterable, List, Literal, Optional, Tuple, Union, overload
+from typing_extensions import deprecated # added in 3.13
 
 from pygame.bufferproxy import BufferProxy
 from pygame.color import Color
@@ -152,8 +153,10 @@ class Surface:
     def get_flags(self) -> int: ...
     def get_pitch(self) -> int: ...
     def get_masks(self) -> RGBAOutput: ...
+    @deprecated("since 2.0.0. Immutable in SDL2")
     def set_masks(self, color: ColorValue, /) -> None: ...
     def get_shifts(self) -> RGBAOutput: ...
+    @deprecated("since 2.0.0. Immutable in SDL2")
     def set_shifts(self, color: ColorValue, /) -> None: ...
     def get_losses(self) -> RGBAOutput: ...
     def get_bounding_rect(self, min_alpha: int = 1) -> Rect: ...

buildconfig/stubs/pygame/surfarray.pyi

@@ -1,4 +1,5 @@
 from typing import Tuple
+from typing_extensions import deprecated # added in 3.13
 
 import numpy
 
@@ -26,6 +27,9 @@ def array_colorkey(surface: Surface) -> numpy.ndarray: ...
 def make_surface(array: numpy.ndarray) -> Surface: ...
 def blit_array(surface: Surface, array: numpy.ndarray) -> None: ...
 def map_array(surface: Surface, array: numpy.ndarray) -> numpy.ndarray: ...
+@deprecated("Only numpy is supported")
 def use_arraytype(arraytype: str) -> None: ...
+@deprecated("Only numpy is supported")
 def get_arraytype() -> str: ...
+@deprecated("Only numpy is supported")
 def get_arraytypes() -> Tuple[str]: ...

buildconfig/stubs/pygame/window.pyi

@@ -1,4 +1,5 @@
-from typing import Optional, Tuple, Union, final
+from typing import Optional, Tuple, Union
+from typing_extensions import deprecated # added in 3.13
 
 from pygame._common import Coordinate, RectValue
 from pygame.locals import WINDOWPOS_UNDEFINED
@@ -67,4 +68,5 @@ class Window:
     @property
     def opengl(self) -> bool: ...
     @classmethod
+    @deprecated("since 2.4.0. Use either the display module or the Window class with get_surface and flip. Try not to mix display and Window")
     def from_display_module(cls) -> Window: ...