Merge pull request #3300 from pygame-community/ankith26-sdl2-stubs

Fix/improve _sdl2 stubs

Author: damusss

buildconfig/stubs/pygame/_sdl2/controller.pyi

@@ -23,9 +23,9 @@ class Controller:
     def as_joystick(self) -> JoystickType: ...
     def get_axis(self, axis: int) -> int: ...
     def get_button(self, button: int) -> bool: ...
-    def get_mapping(self) -> dict: ...
-    def set_mapping(self, mapping: dict) -> int: ...
-    def rumble(self, ___) -> bool: ...
-    def stop_rumble(
+    def get_mapping(self) -> dict[str, str]: ...
+    def set_mapping(self, mapping: dict[str, str]) -> int: ...
+    def rumble(
         self, low_frequency: float, high_frequency: float, duration: int
     ) -> bool: ...
+    def stop_rumble(self) -> None: ...

buildconfig/stubs/pygame/_sdl2/touch.pyi

@@ -1,6 +1,6 @@
-from typing import Union
+from typing import Union, Optional
 
 def get_num_devices() -> int: ...
-def get_device(index: int) -> int: ...
-def get_num_fingers(device_id: int) -> int: ...
-def get_finger(touchid: int, index: int) -> dict[str, Union[int, float]]: ...
+def get_device(index: int, /) -> int: ...
+def get_num_fingers(device_id: int, /) -> int: ...
+def get_finger(touchid: int, index: int) -> Optional[dict[str, Union[int, float]]]: ...

docs/reST/ref/touch.rst

@@ -44,14 +44,15 @@
 .. function:: get_finger
 
    | :sl:`get information about an active finger`
-   | :sg:`get_finger(touchid, index) -> int`
+   | :sg:`get_finger(touchid, index) -> dict | None`
 
    :param int touchid: The touch device id.
    :param int index: The index of the finger to return
                      information about, between 0 and the
                      :func:`number of active fingers <pygame._sdl2.touch.get_num_fingers()>`.
 
-   Return a dict for the finger ``index`` active on ``touchid``.
+   Return a dict for the finger ``index`` active on ``touchid``, or ``None`` if the
+   object does not exist.
    The dict contains these keys:
 
    ::

src_c/doc/touch_doc.h

@@ -3,4 +3,4 @@
 #define DOC_SDL2_TOUCH_GETNUMDEVICES "get_num_devices() -> int\nget the number of touch devices"
 #define DOC_SDL2_TOUCH_GETDEVICE "get_device(index) -> touchid\nget the a touch device id for a given index"
 #define DOC_SDL2_TOUCH_GETNUMFINGERS "get_num_fingers(touchid) -> int\nthe number of active fingers for a given touch device"
-#define DOC_SDL2_TOUCH_GETFINGER "get_finger(touchid, index) -> int\nget information about an active finger"
+#define DOC_SDL2_TOUCH_GETFINGER "get_finger(touchid, index) -> dict | None\nget information about an active finger"