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.
This commit is contained in:
Cheryl Sabella
Berker Peksag
parent
eeb5ffd54e
commit
703ff381ff
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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");
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue