Remove event.peek() behavior, minor doc and stub fixes

buildconfig/stubs/pygame/event.pyi

@@ -4,7 +4,8 @@ from pygame.typing import SequenceLike
 
 @final
 class Event:
-    type: int
+    @property
+    def type(self) -> int: ...
     __dict__: dict[str, Any]
     __hash__: None  # type: ignore
     def __init__(
@@ -17,20 +18,21 @@ class Event:
 
     # this is at the bottom because mypy complains if this declaration comes
     # before any uses of the dict[] typehinting because of the same naming
-    dict: dict[str, Any]
+    @property
+    def dict(self) -> dict[str, Any]: ...
 
 _EventTypes = Union[int, SequenceLike[int]]
 
 def pump() -> None: ...
 def get(
     eventtype: Optional[_EventTypes] = None,
-    pump: Any = True,
+    pump: bool = 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: ...
-def clear(eventtype: Optional[_EventTypes] = None, pump: Any = True) -> None: ...
+def peek(eventtype: _EventTypes, pump: bool = True) -> bool: ...
+def clear(eventtype: Optional[_EventTypes] = None, pump: bool = True) -> None: ...
 def event_name(type: int, /) -> str: ...
 def set_blocked(type: Optional[_EventTypes], /) -> None: ...
 def set_allowed(type: Optional[_EventTypes], /) -> None: ...

docs/reST/ref/event.rst

@@ -317,8 +317,7 @@ 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(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
@@ -328,6 +327,8 @@ On Android, the following events can be generated
 
    .. versionchangedold:: 1.9.5 Added ``pump`` argument
 
+   .. versionchanged:: 2.5.3 ``eventtype`` is no longer an optional argument
+
    .. ## pygame.event.peek ##
 
 .. function:: clear
@@ -491,7 +492,7 @@ On Android, the following events can be generated
 
       Read-only. The event type identifier. For user created event
       objects, this is the ``type`` argument passed to
-      :func:`pygame.event.Event()`.
+      :class:`pygame.event.Event()`.
 
       For example, some predefined event identifiers are ``QUIT`` and
       ``MOUSEMOTION``.

src_c/doc/event_doc.h

@@ -4,7 +4,7 @@
 #define DOC_EVENT_GET "get(eventtype=None) -> Eventlist\nget(eventtype=None, pump=True) -> Eventlist\nget(eventtype=None, pump=True, exclude=None) -> Eventlist\nget events from the queue"
 #define DOC_EVENT_POLL "poll() -> Event instance\nget a single event from the queue"
 #define DOC_EVENT_WAIT "wait() -> Event instance\nwait(timeout) -> Event instance\nwait for a single event from the queue"
-#define DOC_EVENT_PEEK "peek(eventtype=None) -> bool\npeek(eventtype=None, pump=True) -> bool\ntest if event types are waiting on the queue"
+#define DOC_EVENT_PEEK "peek(eventtype, pump=True) -> bool\ntest if event types are waiting on the queue"
 #define DOC_EVENT_CLEAR "clear(eventtype=None) -> None\nclear(eventtype=None, pump=True) -> None\nremove all events from the queue"
 #define DOC_EVENT_EVENTNAME "event_name(type, /) -> string\nget the string name from an event id"
 #define DOC_EVENT_SETBLOCKED "set_blocked(type, /) -> None\nset_blocked(typelist, /) -> None\nset_blocked(None) -> None\ncontrol which events are blocked on the queue"

src_c/event.c

@@ -1591,9 +1591,9 @@ static PyTypeObject pgEvent_Type;
 #define OFF(x) offsetof(pgEventObject, x)
 
 static PyMemberDef pg_event_members[] = {
-    {"__dict__", T_OBJECT, OFF(dict), READONLY},
-    {"type", T_INT, OFF(type), READONLY},
-    {"dict", T_OBJECT, OFF(dict), READONLY},
+    {"__dict__", T_OBJECT, OFF(dict), READONLY, DOC_EVENT_EVENT_DICT},
+    {"type", T_INT, OFF(type), READONLY, DOC_EVENT_EVENT_TYPE},
+    {"dict", T_OBJECT, OFF(dict), READONLY, DOC_EVENT_EVENT_DICT},
     {NULL} /* Sentinel */
 };
 
@@ -2250,52 +2250,44 @@ pg_event_peek(PyObject *self, PyObject *args, PyObject *kwargs)
 
     static char *kwids[] = {"eventtype", "pump", NULL};
 
-    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "|Op", kwids, &obj,
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "O|p", kwids, &obj,
                                      &dopump))
         return NULL;
 
     VIDEO_INIT_CHECK();
 
     _pg_event_pump(dopump);
 
-    if (obj == NULL || obj == Py_None) {
-        res = PG_PEEP_EVENT_ALL(&event, 1, SDL_PEEKEVENT);
-        if (res < 0)
-            return RAISE(pgExc_SDLError, SDL_GetError());
-        return pgEvent_New(res ? &event : NULL);
-    }
-    else {
-        seq = _pg_eventtype_as_seq(obj, &len);
-        if (!seq)
-            return NULL;
+    seq = _pg_eventtype_as_seq(obj, &len);
+    if (!seq)
+        return NULL;
 
-        for (loop = 0; loop < len; loop++) {
-            type = _pg_eventtype_from_seq(seq, loop);
-            if (type == -1) {
-                Py_DECREF(seq);
-                return NULL;
-            }
-            res = PG_PEEP_EVENT(&event, 1, SDL_PEEKEVENT, type);
-            if (res) {
-                Py_DECREF(seq);
+    for (loop = 0; loop < len; loop++) {
+        type = _pg_eventtype_from_seq(seq, loop);
+        if (type == -1) {
+            Py_DECREF(seq);
+            return NULL;
+        }
+        res = PG_PEEP_EVENT(&event, 1, SDL_PEEKEVENT, type);
+        if (res) {
+            Py_DECREF(seq);
 
-                if (res < 0)
-                    return RAISE(pgExc_SDLError, SDL_GetError());
-                Py_RETURN_TRUE;
-            }
-            res = PG_PEEP_EVENT(&event, 1, SDL_PEEKEVENT,
-                                _pg_pgevent_proxify(type));
-            if (res) {
-                Py_DECREF(seq);
+            if (res < 0)
+                return RAISE(pgExc_SDLError, SDL_GetError());
+            Py_RETURN_TRUE;
+        }
+        res =
+            PG_PEEP_EVENT(&event, 1, SDL_PEEKEVENT, _pg_pgevent_proxify(type));
+        if (res) {
+            Py_DECREF(seq);
 
-                if (res < 0)
-                    return RAISE(pgExc_SDLError, SDL_GetError());
-                Py_RETURN_TRUE;
-            }
+            if (res < 0)
+                return RAISE(pgExc_SDLError, SDL_GetError());
+            Py_RETURN_TRUE;
         }
-        Py_DECREF(seq);
-        Py_RETURN_FALSE; /* No event type match. */
     }
+    Py_DECREF(seq);
+    Py_RETURN_FALSE; /* No event type match. */
 }
 
 /* You might notice how we do event blocking stuff on proxy events and

test/event_test.py

@@ -250,13 +250,6 @@ def test_clear(self):
         self.assertRaises(TypeError, pygame.event.get, ["a", "b", "c"])
 
     def test_peek(self):
-        pygame.event.peek()
-        pygame.event.peek(None)
-        pygame.event.peek(None, True)
-
-        pygame.event.peek(pump=False)
-        pygame.event.peek(pump=True)
-        pygame.event.peek(eventtype=None)
         pygame.event.peek(eventtype=[pygame.KEYUP, pygame.KEYDOWN])
         pygame.event.peek(eventtype=pygame.USEREVENT, pump=False)
 
@@ -761,11 +754,6 @@ def test_peek__empty_queue(self):
         """Ensure peek() works correctly on an empty queue."""
         pygame.event.clear()
 
-        # Ensure all events can be checked.
-        peeked = pygame.event.peek()
-
-        self.assertFalse(peeked)
-
         # Ensure events can be checked individually.
         for event_type in EVENT_TYPES:
             peeked = pygame.event.peek(event_type)
@@ -821,7 +809,7 @@ def test_pump(self):
 
     @unittest.skipIf(
         os.environ.get("SDL_VIDEODRIVER") == pygame.NULL_VIDEODRIVER,
-        'requires the SDL_VIDEODRIVER to be a non-null value',
+        "requires the SDL_VIDEODRIVER to be a non-null value",
     )
     def test_set_grab__and_get_symmetric(self):
         """Ensure event grabbing can be enabled and disabled.
@@ -889,7 +877,7 @@ def test_get_blocked__event_sequence(self):
 
     @unittest.skipIf(
         os.environ.get("SDL_VIDEODRIVER") == pygame.NULL_VIDEODRIVER,
-        'requires the SDL_VIDEODRIVER to be a non-null value',
+        "requires the SDL_VIDEODRIVER to be a non-null value",
     )
     def test_get_grab(self):
         """Ensure get_grab() works as expected"""