From 5d6efb68e11ba90224d80db575e0869310a9a6aa Mon Sep 17 00:00:00 2001 From: zoldalma <46655437+zoldalma999@users.noreply.github.com> Date: Wed, 25 Sep 2024 19:38:27 +0200 Subject: [PATCH 1/2] Document event.peek behaviour, minor doc and stub fixes --- buildconfig/stubs/pygame/event.pyi | 12 +++++++----- docs/reST/ref/event.rst | 8 ++++++-- src_c/doc/event_doc.h | 2 +- src_c/event.c | 6 +++--- 4 files changed, 17 insertions(+), 11 deletions(-) diff --git a/buildconfig/stubs/pygame/event.pyi b/buildconfig/stubs/pygame/event.pyi index 1987f96de9..b86299d903 100644 --- a/buildconfig/stubs/pygame/event.pyi +++ b/buildconfig/stubs/pygame/event.pyi @@ -11,8 +11,10 @@ from pygame.typing import SequenceLike @final class Event: - type: int - dict: Dict[str, Any] + @property + def type(self) -> int: ... + @property + def dict(self) -> Dict[str, Any]: ... __dict__: Dict[str, Any] __hash__: None # type: ignore def __init__( @@ -28,13 +30,13 @@ _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: Optional[_EventTypes] = None, 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: ... diff --git a/docs/reST/ref/event.rst b/docs/reST/ref/event.rst index b6c8349948..02d66d7c36 100644 --- a/docs/reST/ref/event.rst +++ b/docs/reST/ref/event.rst @@ -317,10 +317,14 @@ On Android, the following events can be generated .. function:: peek | :sl:`test if event types are waiting on the queue` + | :sg:`peek() -> Event` | :sg:`peek(eventtype=None) -> bool` | :sg:`peek(eventtype=None, pump=True) -> bool` - Returns ``True`` if there are any events of the given type waiting on the + If the ``eventtype`` argument is not passed or is ``None`` (the default), returns + the next event on the queue. + + Otherwise it returns whether there's 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. @@ -491,7 +495,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``. diff --git a/src_c/doc/event_doc.h b/src_c/doc/event_doc.h index 16b6f1b0a1..f91e32cc66 100644 --- a/src_c/doc/event_doc.h +++ b/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() -> Event\npeek(eventtype=None) -> bool\npeek(eventtype=None, 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" diff --git a/src_c/event.c b/src_c/event.c index 59132e3330..13c9ee4331 100644 --- a/src_c/event.c +++ b/src_c/event.c @@ -1420,9 +1420,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 */ }; From ead9e3d0fd1a5b4212b6bd4d0bbffc3a51bc3766 Mon Sep 17 00:00:00 2001 From: zoldalma <46655437+zoldalma999@users.noreply.github.com> Date: Tue, 3 Dec 2024 19:15:24 +0100 Subject: [PATCH 2/2] Make the eventtype argument required in event.peek --- buildconfig/stubs/pygame/event.pyi | 2 +- docs/reST/ref/event.rst | 11 ++---- src_c/doc/event_doc.h | 2 +- src_c/event.c | 60 +++++++++++++----------------- test/event_test.py | 16 +------- 5 files changed, 34 insertions(+), 57 deletions(-) diff --git a/buildconfig/stubs/pygame/event.pyi b/buildconfig/stubs/pygame/event.pyi index 1ad71ac57a..67f4bb8895 100644 --- a/buildconfig/stubs/pygame/event.pyi +++ b/buildconfig/stubs/pygame/event.pyi @@ -31,7 +31,7 @@ def get( ) -> list[Event]: ... def poll() -> Event: ... def wait(timeout: int = 0) -> Event: ... -def peek(eventtype: Optional[_EventTypes] = None, pump: bool = True) -> bool: ... +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: ... diff --git a/docs/reST/ref/event.rst b/docs/reST/ref/event.rst index 7c1358e5a6..98520e9f8a 100644 --- a/docs/reST/ref/event.rst +++ b/docs/reST/ref/event.rst @@ -317,14 +317,9 @@ On Android, the following events can be generated .. function:: peek | :sl:`test if event types are waiting on the queue` - | :sg:`peek() -> Event` - | :sg:`peek(eventtype=None) -> bool` - | :sg:`peek(eventtype=None, pump=True) -> bool` + | :sg:`peek(eventtype, pump=True) -> bool` - If the ``eventtype`` argument is not passed or is ``None`` (the default), returns - the next event on the queue. - - Otherwise it returns whether there's any events of the given type waiting on the + 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. @@ -332,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 diff --git a/src_c/doc/event_doc.h b/src_c/doc/event_doc.h index f91e32cc66..7b23ea78d6 100644 --- a/src_c/doc/event_doc.h +++ b/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() -> Event\npeek(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" diff --git a/src_c/event.c b/src_c/event.c index 2d269f5899..68e6ee11e7 100644 --- a/src_c/event.c +++ b/src_c/event.c @@ -2250,7 +2250,7 @@ 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; @@ -2258,44 +2258,36 @@ pg_event_peek(PyObject *self, PyObject *args, PyObject *kwargs) _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 diff --git a/test/event_test.py b/test/event_test.py index 43e4783eee..ec5d6790ce 100644 --- a/test/event_test.py +++ b/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"""