Skip to content

Commit ba4bc00

Browse files
zoldalma999zoldalma999
committed
Move time docs to stubs, minor fix
1 parent 9258b19 commit ba4bc00

File tree

4 files changed

+153
-191
lines changed

4 files changed

+153
-191
lines changed

‎buildconfig/stubs/pygame/time.pyi‎

Lines changed: 137 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,143 @@
1+
"""Pygame module for monitoring time.
2+
3+
Times in pygame are represented in milliseconds (1/1000 seconds). Most
4+
platforms have a limited time resolution of around 10 milliseconds. This
5+
resolution, in milliseconds, is given in the ``TIMER_RESOLUTION`` constant.
6+
"""
7+
18
from typing import Union, final
29

310
from pygame.event import Event
411

5-
def get_ticks() -> int: ...
6-
def wait(milliseconds: int, /) -> int: ...
7-
def delay(milliseconds: int, /) -> int: ...
8-
def set_timer(event: Union[int, Event], millis: int, loops: int = 0) -> None: ...
12+
def get_ticks() -> int:
13+
"""Get the time in milliseconds.
14+
15+
Return the number of milliseconds since ``pygame.init()`` was called. Before
16+
pygame is initialized this will always be 0.
17+
"""
18+
19+
def wait(milliseconds: int, /) -> int:
20+
"""Pause the program for an amount of time.
21+
22+
Will pause for a given number of milliseconds. This function sleeps the
23+
process to share the processor with other programs. A program that waits for
24+
even a few milliseconds will consume very little processor time. It is
25+
slightly less accurate than the ``pygame.time.delay()`` function.
26+
27+
This returns the actual number of milliseconds used.
28+
"""
29+
30+
def delay(milliseconds: int, /) -> int:
31+
"""Pause the program for an amount of time.
32+
33+
Will pause for a given number of milliseconds. This function will use the
34+
processor (rather than sleeping) in order to make the delay more accurate
35+
than ``pygame.time.wait()``.
36+
37+
This returns the actual number of milliseconds used.
38+
"""
39+
40+
def set_timer(event: Union[int, Event], millis: int, loops: int = 0) -> None:
41+
"""Repeatedly create an event on the event queue.
42+
43+
Set an event to appear on the event queue every given number of milliseconds.
44+
The first event will not appear until the amount of time has passed.
45+
46+
The ``event`` attribute can be a ``pygame.event.Event`` object or an integer
47+
type that denotes an event.
48+
49+
``loops`` is an integer that denotes the number of events posted. If 0 (default)
50+
then the events will keep getting posted, unless explicitly stopped.
51+
52+
To disable the timer for such an event, call the function again with the same
53+
event argument with ``millis`` argument set to 0.
54+
55+
It is also worth mentioning that a particular event type can only be put on a
56+
timer once. In other words, there cannot be two timers for the same event type.
57+
Setting an event timer for a particular event discards the old one for that
58+
event type.
59+
60+
When this function is called with an ``Event`` object, the event(s) received
61+
on the event queue will be a shallow copy; the dict attribute of the event
62+
object passed as an argument and the dict attributes of the event objects
63+
received on timer will be references to the same dict object in memory.
64+
Modifications on one dict can affect another, use deepcopy operations on the
65+
dict object if you don't want this behaviour.
66+
However, calling this function with an integer event type would place event objects
67+
on the queue that don't have a common dict reference.
68+
69+
``loops`` replaces the ``once`` argument, and this does not break backward
70+
compatibility.
71+
72+
.. versionaddedold:: 2.0.0.dev3 once argument added.
73+
.. versionchangedold:: 2.0.1 event argument supports ``pygame.event.Event`` object
74+
.. versionaddedold:: 2.0.1 added loops argument to replace once argument
75+
"""
76+
977
@final
1078
class Clock:
11-
def tick(self, framerate: float = 0, /) -> int: ...
12-
def tick_busy_loop(self, framerate: float = 0, /) -> int: ...
13-
def get_time(self) -> int: ...
14-
def get_rawtime(self) -> int: ...
15-
def get_fps(self) -> float: ...
79+
"""Create an object to help track time.
80+
81+
Creates a new Clock object that can be used to track an amount of time. The
82+
clock also provides several functions to help control a game's framerate.
83+
84+
.. versionchanged:: 2.1.4 This class is also available through the ``pygame.Clock``
85+
alias.
86+
"""
87+
88+
def __new__(cls) -> Clock: ...
89+
def tick(self, framerate: float = 0, /) -> int:
90+
"""Update the clock.
91+
92+
This method should be called once per frame. It will compute how many
93+
milliseconds have passed since the previous call.
94+
95+
If you pass the optional framerate argument the function will delay to
96+
keep the game running slower than the given ticks per second. This can be
97+
used to help limit the runtime speed of a game. By calling
98+
``Clock.tick(40)`` once per frame, the program will never run at more
99+
than 40 frames per second.
100+
101+
Note that this function uses SDL_Delay function which is not accurate on
102+
every platform, but does not use much CPU. Use tick_busy_loop if you want
103+
an accurate timer, and don't mind chewing CPU.
104+
"""
105+
106+
def tick_busy_loop(self, framerate: float = 0, /) -> int:
107+
"""Update the clock.
108+
109+
This method should be called once per frame. It will compute how many
110+
milliseconds have passed since the previous call.
111+
112+
If you pass the optional framerate argument the function will delay to
113+
keep the game running slower than the given ticks per second. This can be
114+
used to help limit the runtime speed of a game. By calling
115+
``Clock.tick_busy_loop(40)`` once per frame, the program will never run at
116+
more than 40 frames per second.
117+
118+
Note that this function uses :func:`pygame.time.delay`, which uses lots
119+
of CPU in a busy loop to make sure that timing is more accurate.
120+
121+
.. versionaddedold:: 1.8
122+
"""
123+
124+
def get_time(self) -> int:
125+
"""Time used in the previous tick.
126+
127+
The number of milliseconds that passed between the previous two calls to
128+
``Clock.tick()``.
129+
"""
130+
131+
def get_rawtime(self) -> int:
132+
"""Actual time used in the previous tick.
133+
134+
Similar to ``Clock.get_time()``, but does not include any time used
135+
while ``Clock.tick()`` was delaying to limit the framerate.
136+
"""
137+
138+
def get_fps(self) -> float:
139+
"""Compute the clock framerate.
140+
141+
Compute your game's framerate (in frames per second). It is computed by
142+
averaging the last ten calls to ``Clock.tick()``.
143+
"""

‎docs/reST/ext/documenters.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ def build_signatures(object):
2020
object = child
2121
break
2222

23-
if object is None:
23+
if object is None or object.obj.get("args", None) is None:
2424
return
2525

2626
sigs = [(object.obj["args"], object.obj["return_annotation"])]

‎docs/reST/ref/time.rst‎

Lines changed: 4 additions & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -3,175 +3,9 @@
33
:mod:`pygame.time`
44
==================
55

6-
.. module:: pygame.time
7-
:synopsis: pygame module for monitoring time
6+
.. autopgmodule:: pygame.time
7+
:members: get_ticks, wait, delay, set_timer
88

9-
| :sl:`pygame module for monitoring time`
9+
.. autopgclass:: Clock
10+
:members: tick, tick_busy_loop, get_time, get_rawtime, get_fps
1011

11-
Times in pygame are represented in milliseconds (1/1000 seconds). Most
12-
platforms have a limited time resolution of around 10 milliseconds. This
13-
resolution, in milliseconds, is given in the ``TIMER_RESOLUTION`` constant.
14-
15-
.. function:: get_ticks
16-
17-
| :sl:`get the time in milliseconds`
18-
| :sg:`get_ticks() -> milliseconds`
19-
20-
Return the number of milliseconds since ``pygame.init()`` was called. Before
21-
pygame is initialized this will always be 0.
22-
23-
.. ## pygame.time.get_ticks ##
24-
25-
.. function:: wait
26-
27-
| :sl:`pause the program for an amount of time`
28-
| :sg:`wait(milliseconds, /) -> time`
29-
30-
Will pause for a given number of milliseconds. This function sleeps the
31-
process to share the processor with other programs. A program that waits for
32-
even a few milliseconds will consume very little processor time. It is
33-
slightly less accurate than the ``pygame.time.delay()`` function.
34-
35-
This returns the actual number of milliseconds used.
36-
37-
.. ## pygame.time.wait ##
38-
39-
.. function:: delay
40-
41-
| :sl:`pause the program for an amount of time`
42-
| :sg:`delay(milliseconds, /) -> time`
43-
44-
Will pause for a given number of milliseconds. This function will use the
45-
processor (rather than sleeping) in order to make the delay more accurate
46-
than ``pygame.time.wait()``.
47-
48-
This returns the actual number of milliseconds used.
49-
50-
.. ## pygame.time.delay ##
51-
52-
.. function:: set_timer
53-
54-
| :sl:`repeatedly create an event on the event queue`
55-
| :sg:`set_timer(event, millis) -> None`
56-
| :sg:`set_timer(event, millis, loops=0) -> None`
57-
58-
Set an event to appear on the event queue every given number of milliseconds.
59-
The first event will not appear until the amount of time has passed.
60-
61-
The ``event`` attribute can be a ``pygame.event.Event`` object or an integer
62-
type that denotes an event.
63-
64-
``loops`` is an integer that denotes the number of events posted. If 0 (default)
65-
then the events will keep getting posted, unless explicitly stopped.
66-
67-
To disable the timer for such an event, call the function again with the same
68-
event argument with ``millis`` argument set to 0.
69-
70-
It is also worth mentioning that a particular event type can only be put on a
71-
timer once. In other words, there cannot be two timers for the same event type.
72-
Setting an event timer for a particular event discards the old one for that
73-
event type.
74-
75-
When this function is called with an ``Event`` object, the event(s) received
76-
on the event queue will be a shallow copy; the dict attribute of the event
77-
object passed as an argument and the dict attributes of the event objects
78-
received on timer will be references to the same dict object in memory.
79-
Modifications on one dict can affect another, use deepcopy operations on the
80-
dict object if you don't want this behaviour.
81-
However, calling this function with an integer event type would place event objects
82-
on the queue that don't have a common dict reference.
83-
84-
``loops`` replaces the ``once`` argument, and this does not break backward
85-
compatibility.
86-
87-
.. versionaddedold:: 2.0.0.dev3 once argument added.
88-
.. versionchangedold:: 2.0.1 event argument supports ``pygame.event.Event`` object
89-
.. versionaddedold:: 2.0.1 added loops argument to replace once argument
90-
91-
.. ## pygame.time.set_timer ##
92-
93-
.. class:: Clock
94-
95-
| :sl:`create an object to help track time`
96-
| :sg:`Clock() -> Clock`
97-
98-
Creates a new Clock object that can be used to track an amount of time. The
99-
clock also provides several functions to help control a game's framerate.
100-
101-
.. versionchanged:: 2.1.4 This class is also available through the ``pygame.Clock``
102-
alias.
103-
104-
.. method:: tick
105-
106-
| :sl:`update the clock`
107-
| :sg:`tick(framerate=0, /) -> milliseconds`
108-
109-
This method should be called once per frame. It will compute how many
110-
milliseconds have passed since the previous call.
111-
112-
If you pass the optional framerate argument the function will delay to
113-
keep the game running slower than the given ticks per second. This can be
114-
used to help limit the runtime speed of a game. By calling
115-
``Clock.tick(40)`` once per frame, the program will never run at more
116-
than 40 frames per second.
117-
118-
Note that this function uses SDL_Delay function which is not accurate on
119-
every platform, but does not use much CPU. Use tick_busy_loop if you want
120-
an accurate timer, and don't mind chewing CPU.
121-
122-
.. ## Clock.tick ##
123-
124-
.. method:: tick_busy_loop
125-
126-
| :sl:`update the clock`
127-
| :sg:`tick_busy_loop(framerate=0, /) -> milliseconds`
128-
129-
This method should be called once per frame. It will compute how many
130-
milliseconds have passed since the previous call.
131-
132-
If you pass the optional framerate argument the function will delay to
133-
keep the game running slower than the given ticks per second. This can be
134-
used to help limit the runtime speed of a game. By calling
135-
``Clock.tick_busy_loop(40)`` once per frame, the program will never run at
136-
more than 40 frames per second.
137-
138-
Note that this function uses :func:`pygame.time.delay`, which uses lots
139-
of CPU in a busy loop to make sure that timing is more accurate.
140-
141-
.. versionaddedold:: 1.8
142-
143-
.. ## Clock.tick_busy_loop ##
144-
145-
.. method:: get_time
146-
147-
| :sl:`time used in the previous tick`
148-
| :sg:`get_time() -> milliseconds`
149-
150-
The number of milliseconds that passed between the previous two calls to
151-
``Clock.tick()``.
152-
153-
.. ## Clock.get_time ##
154-
155-
.. method:: get_rawtime
156-
157-
| :sl:`actual time used in the previous tick`
158-
| :sg:`get_rawtime() -> milliseconds`
159-
160-
Similar to ``Clock.get_time()``, but does not include any time used
161-
while ``Clock.tick()`` was delaying to limit the framerate.
162-
163-
.. ## Clock.get_rawtime ##
164-
165-
.. method:: get_fps
166-
167-
| :sl:`compute the clock framerate`
168-
| :sg:`get_fps() -> float`
169-
170-
Compute your game's framerate (in frames per second). It is computed by
171-
averaging the last ten calls to ``Clock.tick()``.
172-
173-
.. ## Clock.get_fps ##
174-
175-
.. ## pygame.time.Clock ##
176-
177-
.. ## pygame.time ##

‎src_c/doc/time_doc.h‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
/* Auto generated file: with make_docs.py . Docs go in docs/reST/ref/ . */
2-
#define DOC_TIME "pygame module for monitoring time"
3-
#define DOC_TIME_GETTICKS "get_ticks() -> milliseconds\nget the time in milliseconds"
4-
#define DOC_TIME_WAIT "wait(milliseconds, /) -> time\npause the program for an amount of time"
5-
#define DOC_TIME_DELAY "delay(milliseconds, /) -> time\npause the program for an amount of time"
6-
#define DOC_TIME_SETTIMER "set_timer(event, millis) -> None\nset_timer(event, millis, loops=0) -> None\nrepeatedly create an event on the event queue"
7-
#define DOC_TIME_CLOCK "Clock() -> Clock\ncreate an object to help track time"
8-
#define DOC_TIME_CLOCK_TICK "tick(framerate=0, /) -> milliseconds\nupdate the clock"
9-
#define DOC_TIME_CLOCK_TICKBUSYLOOP "tick_busy_loop(framerate=0, /) -> milliseconds\nupdate the clock"
10-
#define DOC_TIME_CLOCK_GETTIME "get_time() -> milliseconds\ntime used in the previous tick"
11-
#define DOC_TIME_CLOCK_GETRAWTIME "get_rawtime() -> milliseconds\nactual time used in the previous tick"
12-
#define DOC_TIME_CLOCK_GETFPS "get_fps() -> float\ncompute the clock framerate"
2+
#define DOC_TIME "Pygame module for monitoring time."
3+
#define DOC_TIME_GETTICKS "get_ticks() -> int\nGet the time in milliseconds."
4+
#define DOC_TIME_WAIT "wait(milliseconds, /) -> int\nPause the program for an amount of time."
5+
#define DOC_TIME_DELAY "delay(milliseconds, /) -> int\nPause the program for an amount of time."
6+
#define DOC_TIME_SETTIMER "set_timer(event, millis, loops=0) -> None\nRepeatedly create an event on the event queue."
7+
#define DOC_TIME_CLOCK "Clock() -> Clock\nCreate an object to help track time."
8+
#define DOC_TIME_CLOCK_TICK "tick(framerate=0, /) -> int\nUpdate the clock."
9+
#define DOC_TIME_CLOCK_TICKBUSYLOOP "tick_busy_loop(framerate=0, /) -> int\nUpdate the clock."
10+
#define DOC_TIME_CLOCK_GETTIME "get_time() -> int\nTime used in the previous tick."
11+
#define DOC_TIME_CLOCK_GETRAWTIME "get_rawtime() -> int\nActual time used in the previous tick."
12+
#define DOC_TIME_CLOCK_GETFPS "get_fps() -> float\nCompute the clock framerate."

0 commit comments

Comments
 (0)