From c4dc3e9949bb074deb57bf121c759502e9a45e4d Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 14 Aug 2026 15:31:10 +0300 Subject: [PATCH 1/6] gh-155787: Harmonize parameter names in the time module documentation and docstrings Use "seconds" and "time_tuple" in both the documentation and the docstrings, and mark the optional arguments of ctime() and strptime() as optional in the docstrings. --- Doc/library/time.rst | 54 +++++++++++++++++++++++--------------------- Modules/timemodule.c | 14 ++++++------ 2 files changed, 35 insertions(+), 33 deletions(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index a931134331f0a5c..9458211e3d8f420 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -122,7 +122,7 @@ An explanation of some terminology and conventions is in order. Functions --------- -.. function:: asctime([t]) +.. function:: asctime([time_tuple]) Convert a tuple or :class:`struct_time` representing a time as returned by :func:`gmtime` or :func:`localtime` to a string of the following @@ -130,8 +130,9 @@ Functions and is space padded if the day is a single digit, e.g.: ``'Wed Jun 9 04:26:40 1993'``. - If *t* is not provided, the current time as returned by :func:`localtime` - is used. Locale information is not used by :func:`asctime`. + If *time_tuple* is not provided, the current time as returned by + :func:`localtime` is used. Locale information is not used by + :func:`asctime`. .. note:: @@ -214,16 +215,16 @@ Functions .. versionadded:: 3.7 -.. function:: ctime([secs]) +.. function:: ctime([seconds]) Convert a time expressed in seconds since the epoch_ to a string of a form: ``'Sun Jun 20 23:21:05 1993'`` representing local time. The day field is two characters long and is space padded if the day is a single digit, e.g.: ``'Wed Jun 9 04:26:40 1993'``. - If *secs* is not provided or :const:`None`, the current time as - returned by :func:`.time` is used. ``ctime(secs)`` is equivalent to - ``asctime(localtime(secs))``. Locale information is not used by + If *seconds* is not provided or :const:`None`, the current time as + returned by :func:`.time` is used. ``ctime(seconds)`` is equivalent to + ``asctime(localtime(seconds))``. Locale information is not used by :func:`ctime`. .. versionchanged:: 3.15 @@ -255,10 +256,10 @@ Functions .. versionadded:: 3.3 -.. function:: gmtime([secs]) +.. function:: gmtime([seconds]) Convert a time expressed in seconds since the epoch_ to a :class:`struct_time` in - UTC in which the dst flag is always zero. If *secs* is not provided or + UTC in which the dst flag is always zero. If *seconds* is not provided or :const:`None`, the current time as returned by :func:`.time` is used. Fractions of a second are ignored. See above for a description of the :class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this @@ -268,11 +269,11 @@ Functions Accepts any real number, not only integer or float. -.. function:: localtime([secs]) +.. function:: localtime([seconds]) - Like :func:`gmtime` but converts to local time. If *secs* is not provided or - :const:`None`, the current time as returned by :func:`.time` is used. The dst - flag is set to ``1`` when DST applies to the given time. + Like :func:`gmtime` but converts to local time. If *seconds* is not + provided or :const:`None`, the current time as returned by :func:`.time` + is used. The dst flag is set to ``1`` when DST applies to the given time. :func:`localtime` may raise :exc:`OverflowError`, if the timestamp is outside the range of values supported by the platform C :c:func:`localtime` @@ -284,7 +285,7 @@ Functions Accepts any real number, not only integer or float. -.. function:: mktime(t) +.. function:: mktime(time_tuple) This is the inverse function of :func:`localtime`. Its argument is the :class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1`` @@ -391,7 +392,7 @@ Functions .. versionadded:: 3.7 -.. function:: sleep(secs) +.. function:: sleep(seconds) Suspend execution of the calling thread for the given number of seconds. The argument may be a non-integer to indicate a more precise sleep time. @@ -404,13 +405,14 @@ Functions .. rubric:: Windows implementation - On Windows, if *secs* is zero, the thread relinquishes the remainder of its - time slice to any other thread that is ready to run. If there are no other - threads ready to run, the function returns immediately, and the thread + On Windows, if *seconds* is zero, the thread relinquishes the remainder of + its time slice to any other thread that is ready to run. If there are no + other threads ready to run, the function returns immediately, and the thread continues execution. On Windows 10 and newer the implementation uses a `high-resolution timer `_ - which provides resolution of 100 nanoseconds. If *secs* is zero, ``Sleep(0)`` is used. + which provides resolution of 100 nanoseconds. If *seconds* is zero, + ``Sleep(0)`` is used. .. rubric:: Unix implementation @@ -425,12 +427,12 @@ Functions To voluntarily relinquish the CPU, specify a real-time :ref:`scheduling policy ` and use :func:`os.sched_yield` instead. - .. audit-event:: time.sleep secs + .. audit-event:: time.sleep seconds .. versionchanged:: 3.5 - The function now sleeps at least *secs* even if the sleep is interrupted - by a signal, except if the signal handler raises an exception (see - :pep:`475` for the rationale). + The function now sleeps at least *seconds* even if the sleep is + interrupted by a signal, except if the signal handler raises an + exception (see :pep:`475` for the rationale). .. versionchanged:: 3.11 On Unix, the ``clock_nanosleep()`` and ``nanosleep()`` functions are now @@ -445,13 +447,13 @@ Functions .. index:: single: % (percent); datetime format -.. function:: strftime(format[, t]) +.. function:: strftime(format[, time_tuple]) Convert a tuple or :class:`struct_time` representing a time as returned by :func:`gmtime` or :func:`localtime` to a string as specified by the *format* - argument. If *t* is not provided, the current time as returned by + argument. If *time_tuple* is not provided, the current time as returned by :func:`localtime` is used. *format* must be a string. :exc:`ValueError` is - raised if any field in *t* is outside of the allowed range. + raised if any field in *time_tuple* is outside of the allowed range. 0 is a legal argument for any position in the time tuple; if it is normally illegal the value is forced to a correct one. diff --git a/Modules/timemodule.c b/Modules/timemodule.c index 70d7e1b3713687a..0005974b52499ce 100644 --- a/Modules/timemodule.c +++ b/Modules/timemodule.c @@ -978,7 +978,7 @@ time_strftime(PyObject *module, PyObject *args) #undef time_char #undef format_time PyDoc_STRVAR(strftime_doc, -"strftime(format[, tuple]) -> string\n\ +"strftime(format[, time_tuple]) -> string\n\ \n\ Convert a time tuple to a string according to a format specification.\n\ See the library reference manual for formatting codes. When the time tuple\n\ @@ -1003,7 +1003,7 @@ time_strptime(PyObject *self, PyObject *args) PyDoc_STRVAR(strptime_doc, -"strptime(string, format) -> struct_time\n\ +"strptime(string[, format]) -> struct_time\n\ \n\ Parse a string to a time tuple according to a format specification.\n\ See the library reference manual for formatting codes (same as\n\ @@ -1056,7 +1056,7 @@ time_asctime(PyObject *module, PyObject *args) } PyDoc_STRVAR(asctime_doc, -"asctime([tuple]) -> string\n\ +"asctime([time_tuple]) -> string\n\ \n\ Convert a time tuple to a string, e.g. 'Sat Jun 06 16:26:11 1998'.\n\ When the time tuple is not present, current time as returned by localtime()\n\ @@ -1075,11 +1075,11 @@ time_ctime(PyObject *self, PyObject *args) } PyDoc_STRVAR(ctime_doc, -"ctime(seconds) -> string\n\ +"ctime([seconds]) -> string\n\ \n\ Convert a time in seconds since the Epoch to a string in local time.\n\ -This is equivalent to asctime(localtime(seconds)). When the time tuple is\n\ -not present, current time as returned by localtime() is used."); +This is equivalent to asctime(localtime(seconds)). When 'seconds' is not\n\ +passed in, convert the current time instead."); #ifdef HAVE_MKTIME static PyObject * @@ -1153,7 +1153,7 @@ time_mktime(PyObject *module, PyObject *tm_tuple) } PyDoc_STRVAR(mktime_doc, -"mktime(tuple) -> floating-point number\n\ +"mktime(time_tuple) -> floating-point number\n\ \n\ Convert a time tuple in local time to seconds since the Epoch.\n\ Note that mktime(gmtime(0)) will not generally return zero for most\n\ From 6ae6b0426b5f9221278279c6ddfde1e51be73f89 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 14 Aug 2026 15:43:08 +0300 Subject: [PATCH 2/6] Use the positional-only notation in signatures --- Doc/library/time.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 9458211e3d8f420..397e2432d9f32ac 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -215,7 +215,7 @@ Functions .. versionadded:: 3.7 -.. function:: ctime([seconds]) +.. function:: ctime(seconds=None, /) Convert a time expressed in seconds since the epoch_ to a string of a form: ``'Sun Jun 20 23:21:05 1993'`` representing local time. The day field @@ -256,7 +256,7 @@ Functions .. versionadded:: 3.3 -.. function:: gmtime([seconds]) +.. function:: gmtime(seconds=None, /) Convert a time expressed in seconds since the epoch_ to a :class:`struct_time` in UTC in which the dst flag is always zero. If *seconds* is not provided or @@ -269,7 +269,7 @@ Functions Accepts any real number, not only integer or float. -.. function:: localtime([seconds]) +.. function:: localtime(seconds=None, /) Like :func:`gmtime` but converts to local time. If *seconds* is not provided or :const:`None`, the current time as returned by :func:`.time` @@ -285,7 +285,7 @@ Functions Accepts any real number, not only integer or float. -.. function:: mktime(time_tuple) +.. function:: mktime(time_tuple, /) This is the inverse function of :func:`localtime`. Its argument is the :class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1`` @@ -392,7 +392,7 @@ Functions .. versionadded:: 3.7 -.. function:: sleep(seconds) +.. function:: sleep(seconds, /) Suspend execution of the calling thread for the given number of seconds. The argument may be a non-integer to indicate a more precise sleep time. From 14cd3f14d861860f716fbbc5361798e127848f4e Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 14 Aug 2026 16:38:00 +0300 Subject: [PATCH 3/6] Apply suggestion from @StanFromIreland Co-authored-by: Stan Ulbrych --- Doc/library/time.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 397e2432d9f32ac..b803369ac9bda27 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -220,7 +220,7 @@ Functions Convert a time expressed in seconds since the epoch_ to a string of a form: ``'Sun Jun 20 23:21:05 1993'`` representing local time. The day field is two characters long and is space padded if the day is a single digit, - e.g.: ``'Wed Jun 9 04:26:40 1993'``. + for example: ``'Wed Jun 9 04:26:40 1993'``. If *seconds* is not provided or :const:`None`, the current time as returned by :func:`.time` is used. ``ctime(seconds)`` is equivalent to From 1a3a6a8fb6b119a4c137ea8b1e13299670dd2ef0 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 14 Aug 2026 16:42:24 +0300 Subject: [PATCH 4/6] Mark positional-only parameters in other functions --- Doc/library/time.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index b803369ac9bda27..84d86470aacf98c 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -139,7 +139,7 @@ Functions Unlike the C function of the same name, :func:`asctime` does not add a trailing newline. -.. function:: pthread_getcpuclockid(thread_id) +.. function:: pthread_getcpuclockid(thread_id, /) Return the *clk_id* of the thread-specific CPU-time clock for the specified *thread_id*. @@ -158,7 +158,7 @@ Functions .. versionadded:: 3.7 -.. function:: clock_getres(clk_id) +.. function:: clock_getres(clk_id, /) Return the resolution (precision) of the specified clock *clk_id*. Refer to :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*. @@ -168,7 +168,7 @@ Functions .. versionadded:: 3.3 -.. function:: clock_gettime(clk_id) -> float +.. function:: clock_gettime(clk_id, /) -> float Return the time of the specified clock *clk_id*. Refer to :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*. @@ -181,7 +181,7 @@ Functions .. versionadded:: 3.3 -.. function:: clock_gettime_ns(clk_id) -> int +.. function:: clock_gettime_ns(clk_id, /) -> int Similar to :func:`clock_gettime` but return time as nanoseconds. @@ -190,7 +190,7 @@ Functions .. versionadded:: 3.7 -.. function:: clock_settime(clk_id, time) +.. function:: clock_settime(clk_id, time, /) Set the time of the specified clock *clk_id*. Currently, :data:`CLOCK_REALTIME` is the only accepted value for *clk_id*. @@ -206,7 +206,7 @@ Functions Accepts any real number as *time*, not only integer or float. -.. function:: clock_settime_ns(clk_id, time: int) +.. function:: clock_settime_ns(clk_id, time: int, /) Similar to :func:`clock_settime` but set time with nanoseconds. @@ -231,7 +231,7 @@ Functions Accepts any real number, not only integer or float. -.. function:: get_clock_info(name) +.. function:: get_clock_info(name, /) Get information on the specified clock as a namespace object. Supported clock names and the corresponding functions to read their value From cc9aa285d2ccdd4264081a161a3ac0ae971a5167 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 14 Aug 2026 16:47:00 +0300 Subject: [PATCH 5/6] Use semantic line breaks in reflown paragraphs --- Doc/library/time.rst | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 84d86470aacf98c..8b7d0a7c103dddc 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -130,9 +130,9 @@ Functions and is space padded if the day is a single digit, e.g.: ``'Wed Jun 9 04:26:40 1993'``. - If *time_tuple* is not provided, the current time as returned by - :func:`localtime` is used. Locale information is not used by - :func:`asctime`. + If *time_tuple* is not provided, + the current time as returned by :func:`localtime` is used. + Locale information is not used by :func:`asctime`. .. note:: @@ -271,9 +271,10 @@ Functions .. function:: localtime(seconds=None, /) - Like :func:`gmtime` but converts to local time. If *seconds* is not - provided or :const:`None`, the current time as returned by :func:`.time` - is used. The dst flag is set to ``1`` when DST applies to the given time. + Like :func:`gmtime` but converts to local time. + If *seconds* is not provided or :const:`None`, + the current time as returned by :func:`.time` is used. + The dst flag is set to ``1`` when DST applies to the given time. :func:`localtime` may raise :exc:`OverflowError`, if the timestamp is outside the range of values supported by the platform C :c:func:`localtime` @@ -405,14 +406,16 @@ Functions .. rubric:: Windows implementation - On Windows, if *seconds* is zero, the thread relinquishes the remainder of - its time slice to any other thread that is ready to run. If there are no - other threads ready to run, the function returns immediately, and the thread - continues execution. On Windows 10 and newer the implementation uses + On Windows, if *seconds* is zero, + the thread relinquishes the remainder of its time slice + to any other thread that is ready to run. + If there are no other threads ready to run, + the function returns immediately, and the thread continues execution. + On Windows 10 and newer the implementation uses a `high-resolution timer `_ - which provides resolution of 100 nanoseconds. If *seconds* is zero, - ``Sleep(0)`` is used. + which provides resolution of 100 nanoseconds. + If *seconds* is zero, ``Sleep(0)`` is used. .. rubric:: Unix implementation @@ -430,9 +433,10 @@ Functions .. audit-event:: time.sleep seconds .. versionchanged:: 3.5 - The function now sleeps at least *seconds* even if the sleep is - interrupted by a signal, except if the signal handler raises an - exception (see :pep:`475` for the rationale). + The function now sleeps at least *seconds* + even if the sleep is interrupted by a signal, + except if the signal handler raises an exception + (see :pep:`475` for the rationale). .. versionchanged:: 3.11 On Unix, the ``clock_nanosleep()`` and ``nanosleep()`` functions are now From 2f79e7862ccdae1f1801b6a99cfa0e5934aaa5c9 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 14 Aug 2026 18:49:44 +0100 Subject: [PATCH 6/6] Convert one more 'e.g.' --- Doc/library/time.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 8b7d0a7c103dddc..d7ca0628c662ea0 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -128,7 +128,7 @@ Functions :func:`gmtime` or :func:`localtime` to a string of the following form: ``'Sun Jun 20 23:21:05 1993'``. The day field is two characters long and is space padded if the day is a single digit, - e.g.: ``'Wed Jun 9 04:26:40 1993'``. + for example: ``'Wed Jun 9 04:26:40 1993'``. If *time_tuple* is not provided, the current time as returned by :func:`localtime` is used.