Simplify c-side of events sub-module. (Part 2)

buildconfig/Setup.Android.SDL2.in

@@ -43,7 +43,7 @@ base src_c/base.c $(SDL) $(DEBUG)
 color src_c/color.c $(SDL) $(DEBUG)
 constants src_c/constants.c $(SDL) $(DEBUG)
 display src_c/display.c $(SDL) $(DEBUG)
-event src_c/event.c $(SDL) $(DEBUG)
+_event src_c/_event.c $(SDL) $(DEBUG)
 key src_c/key.c $(SDL) $(DEBUG)
 mouse src_c/mouse.c $(SDL) $(DEBUG)
 rect src_c/rect.c src_c/pgcompat_rect.c $(SDL) $(DEBUG)

buildconfig/Setup.Emscripten.SDL2.in

@@ -47,7 +47,7 @@ controller src_c/void.c
 controller_old src_c/void.c
 display src_c/void.c
 draw src_c/void.c
-event src_c/void.c
+_event src_c/void.c
 font src_c/void.c
 gfxdraw  src_c/void.c
 joystick src_c/void.c

buildconfig/Setup.SDL2.in

@@ -54,7 +54,7 @@ base src_c/base.c $(SDL) $(DEBUG)
 color src_c/color.c $(SDL) $(DEBUG)
 constants src_c/constants.c $(SDL) $(DEBUG)
 display src_c/display.c $(SDL) $(DEBUG)
-event src_c/event.c $(SDL) $(DEBUG)
+_event src_c/_event.c $(SDL) $(DEBUG)
 key src_c/key.c $(SDL) $(DEBUG)
 mouse src_c/mouse.c $(SDL) $(DEBUG)
 rect src_c/rect.c src_c/pgcompat_rect.c $(SDL) $(DEBUG)

buildconfig/stubs/pygame/_event.pyi

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from .typing import SequenceLike, EventLike
+
+_EventTypes = int | SequenceLike[int]
+
+def pump(dopump: bool, /) -> None: ...
+def _get(type: int, /) -> EventLike | None: ...
+def _peek(type: int, /) -> bool: ...
+def _proxify_event_type(type: int, /) -> int: ...
+def video_check() -> None: ...
+def poll() -> EventLike: ...
+def wait(timeout: int = 0) -> EventLike: ...
+def set_grab(grab: bool, /) -> None: ...
+def get_grab() -> bool: ...
+def allowed_get(type: int, /) -> bool: ...
+def allowed_set(type: int, val: bool, /) -> None: ...
+def post(event: EventLike, /) -> bool: ...
+def register_event_class(cls: type[EventLike]) -> None: ...
+def _internal_mod_init() -> None: ...
+def _internal_mod_quit() -> None: ...

buildconfig/stubs/pygame/event.pyi

@@ -1,27 +1,19 @@
-from typing import (
-    Any,
-    Dict,
-    List,
-    Optional,
-    Union,
-    final,
-)
+from typing import Any, Union, Optional, Dict
 
-from pygame.typing import SequenceLike
+from pygame.typing import SequenceLike, EventLike
 
-@final
-class Event:
-    type: int
-    dict: Dict[str, Any]
-    __dict__: Dict[str, Any]
-    __hash__: None  # type: ignore
+
+class Event(EventLike):
     def __init__(
-        self, type: int, dict: Dict[str, Any] = ..., **kwargs: Any
+        self, type: int, dict: Optional[Dict[str, Any]] = None, **kwargs: Any
     ) -> None: ...
+    def __new__(cls, *args: Any, **kwargs: Any) -> "Event": ...
     def __getattribute__(self, name: str) -> Any: ...
     def __setattr__(self, name: str, value: Any) -> None: ...
     def __delattr__(self, name: str) -> None: ...
+    def __int__(self) -> int: ...
     def __bool__(self) -> bool: ...
+    def __eq__(self, other: Any) -> bool: ...
 
 _EventTypes = Union[int, SequenceLike[int]]
 
@@ -30,18 +22,20 @@ def get(
     eventtype: Optional[_EventTypes] = None,
     pump: Any = True,
     exclude: Optional[_EventTypes] = None,
-) -> List[Event]: ...
-def poll() -> Event: ...
-def wait(timeout: int = 0) -> Event: ...
-def peek(eventtype: Optional[_EventTypes] = None, pump: Any = True) -> bool: ...
+) -> list[EventLike]: ...
+def poll() -> EventLike: ...
+def wait(timeout: int = 0) -> EventLike: ...
+def peek(eventtype: Optional[_EventTypes] = None, pump: Any = True) -> Union[bool, EventLike]: ...
 def clear(eventtype: Optional[_EventTypes] = None, pump: Any = True) -> None: ...
-def event_name(type: int, /) -> str: ...
-def set_blocked(type: Optional[_EventTypes], /) -> None: ...
-def set_allowed(type: Optional[_EventTypes], /) -> None: ...
-def get_blocked(type: _EventTypes, /) -> bool: ...
+def event_name(type: int) -> str: ...
+def set_blocked(type: Optional[_EventTypes], *args: int) -> None: ...
+def set_allowed(type: Optional[_EventTypes], *args: int) -> None: ...
+def get_blocked(type: _EventTypes, *args: int) -> bool: ...
 def set_grab(grab: bool, /) -> None: ...
 def get_grab() -> bool: ...
-def post(event: Event, /) -> bool: ...
+def post(event: EventLike, /) -> bool: ...
 def custom_type() -> int: ...
+def init() -> None: ...
+def quit() -> None: ...
 
 EventType = Event

buildconfig/stubs/pygame/typing.pyi

@@ -14,7 +14,18 @@ __all__ = [
 
 import sys
 from abc import abstractmethod
-from typing import IO, Callable, Tuple, Union, TypeVar, Protocol
+from typing import (
+    IO,
+    Callable,
+    Tuple,
+    Dict,
+    Union,
+    Optional,
+    TypeVar,
+    Protocol,
+    Any,
+    Iterable,
+)
 
 from pygame.color import Color
 from pygame.rect import Rect, FRect
@@ -40,13 +51,14 @@ _T_co = TypeVar("_T_co", covariant=True)
 
 class SequenceLike(Protocol[_T_co]):
     """
-    Variant of the standard `Sequence` ABC that only requires `__getitem__` and `__len__`.
+    Variant of the standard `Sequence` ABC that only requires `__getitem__`.
     """
 
     @abstractmethod
     def __getitem__(self, index: int, /) -> _T_co: ...
-    @abstractmethod
-    def __len__(self) -> int: ...
+
+
+IterableLike = Union[SequenceLike[_T_co], Iterable[_T_co]]
 
 
 # Modify typehints when it is possible to annotate sizes
@@ -72,6 +84,16 @@ RectLike = Union[
 ]
 
 
+class EventLike(Protocol):
+    def __init__(self, type: int, /, **kwargs: Any) -> None: ...
+    def __new__(cls, *args: Any, **kwargs: Any) -> "EventLike": ...
+
+    @property
+    def type(self) -> int: ...
+    @property
+    def dict(self) -> Dict[str, Any]: ...
+
+
 # cleanup namespace
 del (
     sys,
@@ -82,7 +104,10 @@ del (
     IO,
     Callable,
     Tuple,
+    Dict,
     Union,
+    Optional,
     TypeVar,
     Protocol,
+    Any,
 )

docs/reST/c_api/event.rst

@@ -13,32 +13,42 @@ The extension module :py:mod:`pygame.event`.
 
 Header file: src_c/include/pygame.h
 
+.. c:function:: PyObject* pgEvent_GetType(void)
 
-.. c:type:: pgEventObject
+   Return a python class that is currently set to be the event class
 
-   The :py:class:`pygame.event.EventType` object C struct.
-
-   .. c:member:: int type
-
-      The event type code.
-
-.. c:type:: pgEvent_Type
-
-   The pygame event object type :py:class:`pygame.event.EventType`.
+   If the class is not known at the time (called before ``pygame._event.register_event_class``)
+   this function will return NULL and set the error.
 
 .. c:function:: int pgEvent_Check(PyObject *x)
 
    Return true if *x* is a pygame event instance
 
    Will return false if *x* is a subclass of event.
-   This is a macro. No check is made that *x* is not ``NULL``.
+   Will return -1 if python error is set while checking.
+   No check is made that *x* is not ``NULL``.
 
 .. c:function:: PyObject* pgEvent_New(SDL_Event *event)
 
    Return a new pygame event instance for the SDL *event*.
    If *event* is ``NULL`` then create an empty event object.
    On failure raise a Python exception and return ``NULL``.
 
+   .. note::
+      This is a destructive operation, so don't use passed SDL_Event afterwards.
+
+.. c:function:: PyObject* pgEvent_FromTypeAndDict(int e_type, PyObject *dict)
+
+   Instantiates a new Event object created from the given event type and a dict.
+
+   On error returns NULL and sets python exception.
+
+.. c:function:: int pgEvent_GetEventType(PyObject *)
+
+   Returns an event type extracted from the python object.
+
+   On error this retuns -1.
+
 .. c:function:: char* pgEvent_GetKeyDownInfo(void)
 
    Return an array of bools (using char) of length SDL_NUM_SCANCODES
@@ -59,23 +69,19 @@ Header file: src_c/include/pygame.h
    Return an array of bools (using char) of length 5
    with the most recent button releases.
 
-.. c:function:: int pg_post_event(Uint32 type, PyObject *dict)
+.. c:function:: int pg_post_event(Uint32 type, PyObject *obj)
 
    Posts a pygame event that is an ``SDL_USEREVENT`` on the SDL side. This
-   function takes a python dict, which can be NULL too.
-   This function does not need GIL to be held if dict is NULL, but needs GIL
+   function takes a python dict or Event instance, which can be NULL too.
+   This function does not need GIL to be held if obj is NULL, but needs GIL
    otherwise. Just like the SDL ``SDL_PushEvent`` function, returns 1 on
    success, 0 if the event was not posted due to it being blocked, and -1 on
    failure.
 
-.. c:function:: int pg_post_event_dictproxy(Uint32 type, pgEventDictProxy *dict_proxy)
-
-   Posts a pygame event that is an ``SDL_USEREVENT`` on the SDL side, can also
-   optionally take a dictproxy instance. Using this dictproxy API is especially
-   useful when multiple events that need to be posted share the same dict
-   attribute, like in the case of event timers. This way, the number of python
-   increfs and decrefs are reduced, and callers of this function don't need to
-   hold GIL for every event posted, the GIL only needs to be held during the
-   creation of the dictproxy instance, and when it is freed.
-   Just like the SDL ``SDL_PushEvent`` function, returns 1 on success, 0 if the
-   event was not posted due to it being blocked, and -1 on failure.
+   .. ## pg_post_event ##
+
+.. c:function:: int pg_post_event_steal(Uint32 type, PyObject *obj)
+
+   Nearly the same as :c:func:`pg_post_event`, but with two differences.
+   1) This doesn't need GIL held at all when called.
+   2) This steals the reference to obj, instead of borrowing it.

docs/reST/ref/event.rst

@@ -317,15 +317,21 @@ On Android, the following events can be generated
 .. function:: peek
 
    | :sl:`test if event types are waiting on the queue`
-   | :sg:`peek(eventtype=None) -> bool`
-   | :sg:`peek(eventtype=None, pump=True) -> bool`
+   | :sg:`peek() -> Event instance`
+   | :sg:`peek(eventtype) -> bool`
+   | :sg:`peek(eventtype, pump=True) -> bool`
 
    Returns ``True`` if there are any events of the given type waiting on the
    queue. If a sequence of event types is passed, this will return ``True`` if
    any of those events are on the queue.
 
    If ``pump`` is ``True`` (the default), then :func:`pygame.event.pump()` will be called.
 
+   If ``eventtype`` is unspecified, or ``None``, then this function will return the top-most event instead.
+
+   .. note::
+      There is no guarantee that the event got with :func:`pygame.event.get()` immediately after calling this function will be the same.
+
    .. versionchangedold:: 1.9.5 Added ``pump`` argument
 
    .. ## pygame.event.peek ##

docs/reST/ref/typing.rst

@@ -76,4 +76,18 @@ type aliases for proper typehint annotations.
         * Any object with a ``.rect`` attribute which is a ``RectLike`` or a function
           returning a ``RectLike``
 
+   .. data:: EventLike
+
+      A protocol representing an event that is undestood by pygame-ce.
+
+         * ``pygame.Event(type, dict, arg=val)``
+         * A python class that implements EventLike protocol:
+
+         ::
+
+            class MyEvent:
+               def __init__(self, type: int, **kwargs):
+                  self.type = type
+                  self.dict = kwargs
+
 .. ## pygame.typing ##