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

[zoldalma999]

Fixes #1196 by documenting the behavior of pygame.event.peek if nothing is passed in.

Also marks event.type and event.dict readonly in the stubs, adds runtime docs to them, and makes the pump argument more accurate in the stubs.

[bilhox]

LGTM, thanks for the PR!
Worth to mention that @gresm also proposed a fix for this issue in his latest PR.
Otherwise, I left little changes.

[ankith26]

If this is becoming public, a test or two for it would also be good

[ankith26]

The return value probably needs to be updated here to be consistent with the docs.

Also, the reason it was typed as Any in the first place is because almost any object in python is acceptable as a bool, as you probably already know

[zoldalma999]

If this is becoming public, a test or two for it would also be good

Wanted to write one for it, but got a segfault with this code:

import pygame

pygame.init()
pygame.event.clear()

e = pygame.Event(pygame.KEYDOWN, key=pygame.K_SPACE)
pygame.event.post(e)

print("1")
assert e == pygame.event.peek(pump=False)
print("2")
assert e == pygame.event.peek(None, False)
print("3") # This one never gets printed

Debugging it a bit more, seems like the dict proxy on this line is already freed

pygame-ce/src_c/event.c

Line 930 in ddc900e

pgEventDictProxy *dict_proxy = (pgEventDictProxy *)event->user.data1;

[ankith26]

After giving it a bit of thought, my current opinion is that we should remove this functionality all together now.

• If it is segfaulting right now and no one has reported it yet, no one knows or cares about this behaviour.
• For whatever reason if we want to document it down the line, it can be readded and fixed then.