[Python-checkins] bpo-28157: Improvements for the time module documentation (GH-928)
Berker Peksag
webhook-mailer at python.org
Wed Oct 11 09:29:17 EDT 2017
https://github.com/python/cpython/commit/703ff381ffa946c23e7e25b0ae93a636a2607a40
commit: 703ff381ffa946c23e7e25b0ae93a636a2607a40
branch: master
author: Cheryl Sabella <cheryl.sabella at gmail.com>
committer: Berker Peksag <berker.peksag at gmail.com>
date: 2017-10-11T16:29:14+03:00
summary:
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.
files:
M Doc/library/time.rst
M Modules/timemodule.c
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index 179762ed1c8..25a4ab50826 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 31050fb554b..2c0a8d61eda 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");
More information about the Python-checkins
mailing list