Skip to content

Commit 52dad32

Browse files
serhiy-storchakaStanFromIreland
authored and
miss-islington
committed
gh-155787: Harmonize parameter names in the time module documentation and docstrings (GH-155790)
(cherry picked from commit bc6749c) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Stan Ulbrych <stan@python.org>
1 parent 042df0a commit 52dad32

2 files changed

Lines changed: 49 additions & 43 deletions

File tree

‎Doc/library/time.rst‎

Lines changed: 42 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -122,23 +122,24 @@ An explanation of some terminology and conventions is in order.
122122
Functions
123123
---------
124124

125-
.. function:: asctime([t])
125+
.. function:: asctime([time_tuple])
126126

127127
Convert a tuple or :class:`struct_time` representing a time as returned by
128128
:func:`gmtime` or :func:`localtime` to a string of the following
129129
form: ``'Sun Jun 20 23:21:05 1993'``. The day field is two characters long
130130
and is space padded if the day is a single digit,
131-
e.g.: ``'Wed Jun 9 04:26:40 1993'``.
131+
for example: ``'Wed Jun 9 04:26:40 1993'``.
132132

133-
If *t* is not provided, the current time as returned by :func:`localtime`
134-
is used. Locale information is not used by :func:`asctime`.
133+
If *time_tuple* is not provided,
134+
the current time as returned by :func:`localtime` is used.
135+
Locale information is not used by :func:`asctime`.
135136

136137
.. note::
137138

138139
Unlike the C function of the same name, :func:`asctime` does not add a
139140
trailing newline.
140141

141-
.. function:: pthread_getcpuclockid(thread_id)
142+
.. function:: pthread_getcpuclockid(thread_id, /)
142143

143144
Return the *clk_id* of the thread-specific CPU-time clock for the specified *thread_id*.
144145

@@ -157,7 +158,7 @@ Functions
157158

158159
.. versionadded:: 3.7
159160

160-
.. function:: clock_getres(clk_id)
161+
.. function:: clock_getres(clk_id, /)
161162

162163
Return the resolution (precision) of the specified clock *clk_id*. Refer to
163164
:ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
@@ -167,7 +168,7 @@ Functions
167168
.. versionadded:: 3.3
168169

169170

170-
.. function:: clock_gettime(clk_id) -> float
171+
.. function:: clock_gettime(clk_id, /) -> float
171172

172173
Return the time of the specified clock *clk_id*. Refer to
173174
:ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
@@ -180,7 +181,7 @@ Functions
180181
.. versionadded:: 3.3
181182

182183

183-
.. function:: clock_gettime_ns(clk_id) -> int
184+
.. function:: clock_gettime_ns(clk_id, /) -> int
184185

185186
Similar to :func:`clock_gettime` but return time as nanoseconds.
186187

@@ -189,7 +190,7 @@ Functions
189190
.. versionadded:: 3.7
190191

191192

192-
.. function:: clock_settime(clk_id, time)
193+
.. function:: clock_settime(clk_id, time, /)
193194

194195
Set the time of the specified clock *clk_id*. Currently,
195196
:data:`CLOCK_REALTIME` is the only accepted value for *clk_id*.
@@ -205,7 +206,7 @@ Functions
205206
Accepts any real number as *time*, not only integer or float.
206207

207208

208-
.. function:: clock_settime_ns(clk_id, time: int)
209+
.. function:: clock_settime_ns(clk_id, time: int, /)
209210

210211
Similar to :func:`clock_settime` but set time with nanoseconds.
211212

@@ -214,23 +215,23 @@ Functions
214215
.. versionadded:: 3.7
215216

216217

217-
.. function:: ctime([secs])
218+
.. function:: ctime(seconds=None, /)
218219

219220
Convert a time expressed in seconds since the epoch_ to a string of a form:
220221
``'Sun Jun 20 23:21:05 1993'`` representing local time. The day field
221222
is two characters long and is space padded if the day is a single digit,
222-
e.g.: ``'Wed Jun 9 04:26:40 1993'``.
223+
for example: ``'Wed Jun 9 04:26:40 1993'``.
223224

224-
If *secs* is not provided or :const:`None`, the current time as
225-
returned by :func:`.time` is used. ``ctime(secs)`` is equivalent to
226-
``asctime(localtime(secs))``. Locale information is not used by
225+
If *seconds* is not provided or :const:`None`, the current time as
226+
returned by :func:`.time` is used. ``ctime(seconds)`` is equivalent to
227+
``asctime(localtime(seconds))``. Locale information is not used by
227228
:func:`ctime`.
228229

229230
.. versionchanged:: 3.15
230231
Accepts any real number, not only integer or float.
231232

232233

233-
.. function:: get_clock_info(name)
234+
.. function:: get_clock_info(name, /)
234235

235236
Get information on the specified clock as a namespace object.
236237
Supported clock names and the corresponding functions to read their value
@@ -255,10 +256,10 @@ Functions
255256
.. versionadded:: 3.3
256257

257258

258-
.. function:: gmtime([secs])
259+
.. function:: gmtime(seconds=None, /)
259260

260261
Convert a time expressed in seconds since the epoch_ to a :class:`struct_time` in
261-
UTC in which the dst flag is always zero. If *secs* is not provided or
262+
UTC in which the dst flag is always zero. If *seconds* is not provided or
262263
:const:`None`, the current time as returned by :func:`.time` is used. Fractions
263264
of a second are ignored. See above for a description of the
264265
:class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this
@@ -268,11 +269,12 @@ Functions
268269
Accepts any real number, not only integer or float.
269270

270271

271-
.. function:: localtime([secs])
272+
.. function:: localtime(seconds=None, /)
272273

273-
Like :func:`gmtime` but converts to local time. If *secs* is not provided or
274-
:const:`None`, the current time as returned by :func:`.time` is used. The dst
275-
flag is set to ``1`` when DST applies to the given time.
274+
Like :func:`gmtime` but converts to local time.
275+
If *seconds* is not provided or :const:`None`,
276+
the current time as returned by :func:`.time` is used.
277+
The dst flag is set to ``1`` when DST applies to the given time.
276278

277279
:func:`localtime` may raise :exc:`OverflowError`, if the timestamp is
278280
outside the range of values supported by the platform C :c:func:`localtime`
@@ -284,7 +286,7 @@ Functions
284286
Accepts any real number, not only integer or float.
285287

286288

287-
.. function:: mktime(t)
289+
.. function:: mktime(time_tuple, /)
288290

289291
This is the inverse function of :func:`localtime`. Its argument is the
290292
:class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1``
@@ -391,7 +393,7 @@ Functions
391393

392394
.. versionadded:: 3.7
393395

394-
.. function:: sleep(secs)
396+
.. function:: sleep(seconds, /)
395397

396398
Suspend execution of the calling thread for the given number of seconds.
397399
The argument may be a non-integer to indicate a more precise sleep time.
@@ -404,13 +406,16 @@ Functions
404406

405407
.. rubric:: Windows implementation
406408

407-
On Windows, if *secs* is zero, the thread relinquishes the remainder of its
408-
time slice to any other thread that is ready to run. If there are no other
409-
threads ready to run, the function returns immediately, and the thread
410-
continues execution. On Windows 10 and newer the implementation uses
409+
On Windows, if *seconds* is zero,
410+
the thread relinquishes the remainder of its time slice
411+
to any other thread that is ready to run.
412+
If there are no other threads ready to run,
413+
the function returns immediately, and the thread continues execution.
414+
On Windows 10 and newer the implementation uses
411415
a `high-resolution timer
412416
<https://learn.microsoft.com/windows/win32/api/synchapi/nf-synchapi-createwaitabletimerexw>`_
413-
which provides resolution of 100 nanoseconds. If *secs* is zero, ``Sleep(0)`` is used.
417+
which provides resolution of 100 nanoseconds.
418+
If *seconds* is zero, ``Sleep(0)`` is used.
414419

415420
.. rubric:: Unix implementation
416421

@@ -425,12 +430,13 @@ Functions
425430
To voluntarily relinquish the CPU, specify a real-time :ref:`scheduling
426431
policy <os-scheduling-policy>` and use :func:`os.sched_yield` instead.
427432

428-
.. audit-event:: time.sleep secs
433+
.. audit-event:: time.sleep seconds
429434

430435
.. versionchanged:: 3.5
431-
The function now sleeps at least *secs* even if the sleep is interrupted
432-
by a signal, except if the signal handler raises an exception (see
433-
:pep:`475` for the rationale).
436+
The function now sleeps at least *seconds*
437+
even if the sleep is interrupted by a signal,
438+
except if the signal handler raises an exception
439+
(see :pep:`475` for the rationale).
434440

435441
.. versionchanged:: 3.11
436442
On Unix, the ``clock_nanosleep()`` and ``nanosleep()`` functions are now
@@ -445,13 +451,13 @@ Functions
445451
.. index::
446452
single: % (percent); datetime format
447453

448-
.. function:: strftime(format[, t])
454+
.. function:: strftime(format[, time_tuple])
449455

450456
Convert a tuple or :class:`struct_time` representing a time as returned by
451457
:func:`gmtime` or :func:`localtime` to a string as specified by the *format*
452-
argument. If *t* is not provided, the current time as returned by
458+
argument. If *time_tuple* is not provided, the current time as returned by
453459
:func:`localtime` is used. *format* must be a string. :exc:`ValueError` is
454-
raised if any field in *t* is outside of the allowed range.
460+
raised if any field in *time_tuple* is outside of the allowed range.
455461

456462
0 is a legal argument for any position in the time tuple; if it is normally
457463
illegal the value is forced to a correct one.

‎Modules/timemodule.c‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -978,7 +978,7 @@ time_strftime(PyObject *module, PyObject *args)
978978
#undef time_char
979979
#undef format_time
980980
PyDoc_STRVAR(strftime_doc,
981-
"strftime(format[, tuple]) -> string\n\
981+
"strftime(format[, time_tuple]) -> string\n\
982982
\n\
983983
Convert a time tuple to a string according to a format specification.\n\
984984
See the library reference manual for formatting codes. When the time tuple\n\
@@ -1003,7 +1003,7 @@ time_strptime(PyObject *self, PyObject *args)
10031003

10041004

10051005
PyDoc_STRVAR(strptime_doc,
1006-
"strptime(string, format) -> struct_time\n\
1006+
"strptime(string[, format]) -> struct_time\n\
10071007
\n\
10081008
Parse a string to a time tuple according to a format specification.\n\
10091009
See the library reference manual for formatting codes (same as\n\
@@ -1056,7 +1056,7 @@ time_asctime(PyObject *module, PyObject *args)
10561056
}
10571057

10581058
PyDoc_STRVAR(asctime_doc,
1059-
"asctime([tuple]) -> string\n\
1059+
"asctime([time_tuple]) -> string\n\
10601060
\n\
10611061
Convert a time tuple to a string, e.g. 'Sat Jun 06 16:26:11 1998'.\n\
10621062
When the time tuple is not present, current time as returned by localtime()\n\
@@ -1075,11 +1075,11 @@ time_ctime(PyObject *self, PyObject *args)
10751075
}
10761076

10771077
PyDoc_STRVAR(ctime_doc,
1078-
"ctime(seconds) -> string\n\
1078+
"ctime([seconds]) -> string\n\
10791079
\n\
10801080
Convert a time in seconds since the Epoch to a string in local time.\n\
1081-
This is equivalent to asctime(localtime(seconds)). When the time tuple is\n\
1082-
not present, current time as returned by localtime() is used.");
1081+
This is equivalent to asctime(localtime(seconds)). When 'seconds' is not\n\
1082+
passed in, convert the current time instead.");
10831083

10841084
#ifdef HAVE_MKTIME
10851085
static PyObject *
@@ -1153,7 +1153,7 @@ time_mktime(PyObject *module, PyObject *tm_tuple)
11531153
}
11541154

11551155
PyDoc_STRVAR(mktime_doc,
1156-
"mktime(tuple) -> floating-point number\n\
1156+
"mktime(time_tuple) -> floating-point number\n\
11571157
\n\
11581158
Convert a time tuple in local time to seconds since the Epoch.\n\
11591159
Note that mktime(gmtime(0)) will not generally return zero for most\n\

0 commit comments

Comments
 (0)