pygame.event.peek docs missing a detail (2329)

[GalacticEmperor1]

Issue №2329 opened by ankith26 at 2020-11-15 09:27:16

According to pygame event.peek docs, the function is supposed to return a Boolean on whether a particular event is present in the queue or not. What it misses out, is that if you pass None or do not pass any argument, it returns the peeked event itself (I don’t know why, but that’s what the code is doing) https://www.pygame.org/docs/ref/event.html# pygame.event.peek

We must either mention this behaviour in the docs, or have this weird behaviour removed

Side note: this is the last event function I’m working on. Hopefully after this, event refactor PR coming soon :)

---

Comments

# # MyreMylar commented at 2020-11-15 09:48:59

I think I would expect this function to return True is there were any events in the queue if the type was unspecified, and False if the queue was empty.

---

# # MyreMylar commented at 2020-11-15 09:50:37

Likely worth searching github for usages though to see if changing this would break something. The current behaviour is likely based off what happens with a standard stack/queue data structure when you call .peek() on it.

---

# # ankith26 commented at 2020-11-15 10:30:16

Did do a github search, and it turns out that a lot of people include the local venv folder while uploading their projects to github (so most of results are from pygames unit tests)

---

# # ankith26 commented at 2020-12-20 05:40:36

@illume what’s your vote on this. Should we get rid of this weird behavior, or should we document this one.

AFAIK, The function has been in that state since years. And this has not been documented since many years too, so I don’t think many people know that this even exists. So it might be safe to remove it.

Either way, I would do this along with event-refactor PR

---

# # illume commented at 2020-12-20 08:35:58

I'd vote with leaving the behaviour as it is for backwards compatibility, but leave it undocumented still.

If someone comes along later who wants to do more research on usages of this, and then fix it either way... then there is this issue here for them to work on it.

---

# # ankith26 commented at 2020-12-20 13:06:34

I did quite a good amount of research on this. By going through a github search of all usages.
And found that nobody uses this feature. IMHO, it might be a good idea to remove this behavior

I did find a few rare cases where the function was called without arguments. But all those were testing it in an if condition to test whether any events were waiting in the queue or not.
So if we take MyreMylars suggestion, given above, we would still be good to go

[bilhox]

Not sure to understand why this shouldn't be documented ? Anything to say about it @ankith26 ?

[ankith26]

I'm fine with it being documented for the purposes of closing this issue