From 703ff381ffa946c23e7e25b0ae93a636a2607a40 Mon Sep 17 00:00:00 2001 From: Cheryl Sabella Date: Wed, 11 Oct 2017 09:29:14 -0400 Subject: [PATCH] bpo-28157: Improvements for the time module documentation (GH-928) * Separated functions and constants descriptions in sections. * Added a note about the limitations of timezone constants. * Removed redundant lists from the module docstring. --- Doc/library/time.rst | 202 ++++++++++++++++++++++++------------------- Modules/timemodule.c | 23 +---- 2 files changed, 116 insertions(+), 109 deletions(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 179762ed1c..25a4ab5082 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -118,14 +118,10 @@ An explanation of some terminology and conventions is in order. +-------------------------+-------------------------+-------------------------+ -The module defines the following functions and data items: - -.. data:: altzone - - The offset of the local DST timezone, in seconds west of UTC, if one is defined. - This is negative if the local DST timezone is east of UTC (as in Western Europe, - including the UK). Only use this if ``daylight`` is nonzero. +.. _time-functions: +Functions +--------- .. function:: asctime([t]) @@ -181,7 +177,8 @@ The module defines the following functions and data items: .. function:: clock_getres(clk_id) - Return the resolution (precision) of the specified clock *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*. Availability: Unix. @@ -190,7 +187,8 @@ The module defines the following functions and data items: .. function:: clock_gettime(clk_id) - Return the time of the specified clock *clk_id*. + 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*. Availability: Unix. @@ -199,66 +197,8 @@ The module defines the following functions and data items: .. function:: clock_settime(clk_id, time) - Set the time of the specified clock *clk_id*. - - Availability: Unix. - - .. versionadded:: 3.3 - - -.. data:: CLOCK_HIGHRES - - The Solaris OS has a CLOCK_HIGHRES timer that attempts to use an optimal - hardware source, and may give close to nanosecond resolution. CLOCK_HIGHRES - is the nonadjustable, high-resolution clock. - - Availability: Solaris. - - .. versionadded:: 3.3 - - -.. data:: CLOCK_MONOTONIC - - Clock that cannot be set and represents monotonic time since some unspecified - starting point. - - Availability: Unix. - - .. versionadded:: 3.3 - - -.. data:: CLOCK_MONOTONIC_RAW - - Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw - hardware-based time that is not subject to NTP adjustments. - - Availability: Linux 2.6.28 or later. - - .. versionadded:: 3.3 - - -.. data:: CLOCK_PROCESS_CPUTIME_ID - - High-resolution per-process timer from the CPU. - - Availability: Unix. - - .. versionadded:: 3.3 - - -.. data:: CLOCK_REALTIME - - System-wide real-time clock. Setting this clock requires appropriate - privileges. - - Availability: Unix. - - .. versionadded:: 3.3 - - -.. data:: CLOCK_THREAD_CPUTIME_ID - - Thread-specific CPU-time clock. + Set the time of the specified clock *clk_id*. Currently, + :data:`CLOCK_REALTIME` is the only accepted value for *clk_id*. Availability: Unix. @@ -273,11 +213,6 @@ The module defines the following functions and data items: ``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`. -.. data:: daylight - - Nonzero if a DST timezone is defined. - - .. function:: get_clock_info(name) Get information on the specified clock as a namespace object. @@ -295,7 +230,7 @@ The module defines the following functions and data items: - *adjustable*: ``True`` if the clock can be changed automatically (e.g. by a NTP daemon) or manually by the system administrator, ``False`` otherwise - *implementation*: The name of the underlying C function used to get - the clock value + the clock value. Refer to :ref:`time-clock-id-constants` for possible values. - *monotonic*: ``True`` if the clock cannot go backward, ``False`` otherwise - *resolution*: The resolution of the clock in seconds (:class:`float`) @@ -623,18 +558,6 @@ The module defines the following functions and data items: :class:`struct_time` object is returned, from which the components of the calendar date may be accessed as attributes. -.. data:: timezone - - The offset of the local (non-DST) timezone, in seconds west of UTC (negative in - most of Western Europe, positive in the US, zero in the UK). - - -.. data:: tzname - - A tuple of two strings: the first is the name of the local non-DST timezone, the - second is the name of the local DST timezone. If no DST timezone is defined, - the second string should not be used. - .. function:: tzset() @@ -724,6 +647,111 @@ The module defines the following functions and data items: ('EET', 'EEST') +.. _time-clock-id-constants: + +Clock ID Constants +------------------ + +These constants are used as parameters for :func:`clock_getres` and +:func:`clock_gettime`. + +.. data:: CLOCK_HIGHRES + + The Solaris OS has a ``CLOCK_HIGHRES`` timer that attempts to use an optimal + hardware source, and may give close to nanosecond resolution. + ``CLOCK_HIGHRES`` is the nonadjustable, high-resolution clock. + + Availability: Solaris. + + .. versionadded:: 3.3 + + +.. data:: CLOCK_MONOTONIC + + Clock that cannot be set and represents monotonic time since some unspecified + starting point. + + Availability: Unix. + + .. versionadded:: 3.3 + + +.. data:: CLOCK_MONOTONIC_RAW + + Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw + hardware-based time that is not subject to NTP adjustments. + + Availability: Linux 2.6.28 or later. + + .. versionadded:: 3.3 + + +.. data:: CLOCK_PROCESS_CPUTIME_ID + + High-resolution per-process timer from the CPU. + + Availability: Unix. + + .. versionadded:: 3.3 + + +.. data:: CLOCK_THREAD_CPUTIME_ID + + Thread-specific CPU-time clock. + + Availability: Unix. + + .. versionadded:: 3.3 + + +The following constant is the only parameter that can be sent to +:func:`clock_settime`. + +.. data:: CLOCK_REALTIME + + System-wide real-time clock. Setting this clock requires appropriate + privileges. + + Availability: Unix. + + .. versionadded:: 3.3 + + +.. _time-timezone-constants: + +Timezone Constants +------------------- + +.. data:: altzone + + The offset of the local DST timezone, in seconds west of UTC, if one is defined. + This is negative if the local DST timezone is east of UTC (as in Western Europe, + including the UK). Only use this if ``daylight`` is nonzero. See note below. + +.. data:: daylight + + Nonzero if a DST timezone is defined. See note below. + +.. data:: timezone + + The offset of the local (non-DST) timezone, in seconds west of UTC (negative in + most of Western Europe, positive in the US, zero in the UK). See note below. + +.. data:: tzname + + A tuple of two strings: the first is the name of the local non-DST timezone, the + second is the name of the local DST timezone. If no DST timezone is defined, + the second string should not be used. See note below. + +.. note:: + + For the above Timezone constants (:data:`altzone`, :data:`daylight`, :data:`timezone`, + and :data:`tzname`), the value is determined by the timezone rules in effect + at module load time or the last time :func:`tzset` is called and may be incorrect + for times in the past. It is recommended to use the :attr:`tm_gmtoff` and + :attr:`tm_zone` results from :func:`localtime` to obtain timezone information. + + .. seealso:: Module :mod:`datetime` diff --git a/Modules/timemodule.c b/Modules/timemodule.c index 31050fb554..2c0a8d61ed 100644 --- a/Modules/timemodule.c +++ b/Modules/timemodule.c @@ -1342,28 +1342,7 @@ The tuple items are:\n\ DST (Daylight Savings Time) flag (-1, 0 or 1)\n\ If the DST flag is 0, the time is given in the regular time zone;\n\ if it is 1, the time is given in the DST time zone;\n\ -if it is -1, mktime() should guess based on the date and time.\n\ -\n\ -Variables:\n\ -\n\ -timezone -- difference in seconds between UTC and local standard time\n\ -altzone -- difference in seconds between UTC and local DST time\n\ -daylight -- whether local time should reflect DST\n\ -tzname -- tuple of (standard time zone name, DST time zone name)\n\ -\n\ -Functions:\n\ -\n\ -time() -- return current time in seconds since the Epoch as a float\n\ -clock() -- return CPU time since process start as a float\n\ -sleep() -- delay for a number of seconds given as a float\n\ -gmtime() -- convert seconds since Epoch to UTC tuple\n\ -localtime() -- convert seconds since Epoch to local time tuple\n\ -asctime() -- convert time tuple to string\n\ -ctime() -- convert time in seconds to string\n\ -mktime() -- convert local time tuple to seconds since Epoch\n\ -strftime() -- convert time tuple to string according to format specification\n\ -strptime() -- parse string to time tuple according to format specification\n\ -tzset() -- change the local timezone"); +if it is -1, mktime() should guess based on the date and time.\n"); -- 2.40.0