Merged revisions 85530,85534,85538,85540-85542 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r85530 | georg.brandl | 2010-10-15 17:32:05 +0200 (Fr, 15 Okt 2010) | 1 line
Refrain from using inline suites.
........
r85534 | georg.brandl | 2010-10-15 18:19:43 +0200 (Fr, 15 Okt 2010) | 1 line
#9801: document how list and dict proxies created by Managers behave w.r.t. mutable items.
........
r85538 | georg.brandl | 2010-10-15 18:35:46 +0200 (Fr, 15 Okt 2010) | 1 line
#7303: add documentation for useful pkgutil functions and classes.
........
r85540 | georg.brandl | 2010-10-15 18:42:37 +0200 (Fr, 15 Okt 2010) | 1 line
#6798: fix wrong docs for the arguments to several trace events.
........
r85541 | georg.brandl | 2010-10-15 18:53:24 +0200 (Fr, 15 Okt 2010) | 1 line
#4968: updates to inspect.is* function docs.
........
r85542 | georg.brandl | 2010-10-15 19:01:15 +0200 (Fr, 15 Okt 2010) | 1 line
#7790: move table of struct_time members to the actual description of struct_time.
........
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index c38b0e0..d6efcee 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -17,21 +17,23 @@
An explanation of some terminology and conventions is in order.
- .. index:: single: epoch
+.. index:: single: epoch
* The :dfn:`epoch` is the point where the time starts. On January 1st of that
year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is
1970. To find out what the epoch is, look at ``gmtime(0)``.
- .. index:: single: Year 2038
+.. index:: single: Year 2038
* The functions in this module do not handle dates and times before the epoch or
far in the future. The cut-off point in the future is determined by the C
library; for Unix, it is typically in 2038.
- .. index::
- single: Year 2000
- single: Y2K
+.. index::
+ single: Year 2000
+ single: Y2K
+
+.. _time-y2kissues:
* **Year 2000 (Y2K) issues**: Python depends on the platform's C library, which
generally doesn't have year 2000 issues, since all dates and times are
@@ -48,16 +50,16 @@
Note that this is new as of Python 1.5.2(a2); earlier versions, up to Python
1.5.1 and 1.5.2a1, would add 1900 to year values below 1900.
- .. index::
- single: UTC
- single: Coordinated Universal Time
- single: Greenwich Mean Time
+.. index::
+ single: UTC
+ single: Coordinated Universal Time
+ single: Greenwich Mean Time
* UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
GMT). The acronym UTC is not a mistake but a compromise between English and
French.
- .. index:: single: Daylight Saving Time
+.. index:: single: Daylight Saving Time
* DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
hour during part of the year. DST rules are magic (determined by local law) and
@@ -82,38 +84,7 @@
values of :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer
attribute names for individual fields.
- +-------+-------------------+---------------------------------+
- | Index | Attribute | Values |
- +=======+===================+=================================+
- | 0 | :attr:`tm_year` | (for example, 1993) |
- +-------+-------------------+---------------------------------+
- | 1 | :attr:`tm_mon` | range [1, 12] |
- +-------+-------------------+---------------------------------+
- | 2 | :attr:`tm_mday` | range [1, 31] |
- +-------+-------------------+---------------------------------+
- | 3 | :attr:`tm_hour` | range [0, 23] |
- +-------+-------------------+---------------------------------+
- | 4 | :attr:`tm_min` | range [0, 59] |
- +-------+-------------------+---------------------------------+
- | 5 | :attr:`tm_sec` | range [0, 61]; see **(1)** in |
- | | | :func:`strftime` description |
- +-------+-------------------+---------------------------------+
- | 6 | :attr:`tm_wday` | range [0, 6], Monday is 0 |
- +-------+-------------------+---------------------------------+
- | 7 | :attr:`tm_yday` | range [1, 366] |
- +-------+-------------------+---------------------------------+
- | 8 | :attr:`tm_isdst` | 0, 1 or -1; see below |
- +-------+-------------------+---------------------------------+
-
- Note that unlike the C structure, the month value is a range of [1, 12],
- not [0, 11].
- A year value will be handled as described under "Year 2000 (Y2K) issues" above.
- A ``-1`` argument as the daylight savings flag, passed to :func:`mktime` will
- usually result in the correct daylight savings state to be filled in.
-
- When a tuple with an incorrect length is passed to a function expecting a
- :class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError`
- is raised.
+ See :class:`struct_time` for a description of these objects.
.. versionchanged:: 2.2
The time value sequence was changed from a tuple to a :class:`struct_time`, with
@@ -419,13 +390,48 @@
documented as supported.
-.. data:: struct_time
+.. class:: struct_time
The type of the time value sequence returned by :func:`gmtime`,
- :func:`localtime`, and :func:`strptime`.
+ :func:`localtime`, and :func:`strptime`. It is an object with a :term:`named
+ tuple` interface: values can be accessed by index and by attribute name. The
+ following values are present:
+
+ +-------+-------------------+---------------------------------+
+ | Index | Attribute | Values |
+ +=======+===================+=================================+
+ | 0 | :attr:`tm_year` | (for example, 1993) |
+ +-------+-------------------+---------------------------------+
+ | 1 | :attr:`tm_mon` | range [1, 12] |
+ +-------+-------------------+---------------------------------+
+ | 2 | :attr:`tm_mday` | range [1, 31] |
+ +-------+-------------------+---------------------------------+
+ | 3 | :attr:`tm_hour` | range [0, 23] |
+ +-------+-------------------+---------------------------------+
+ | 4 | :attr:`tm_min` | range [0, 59] |
+ +-------+-------------------+---------------------------------+
+ | 5 | :attr:`tm_sec` | range [0, 61]; see **(1)** in |
+ | | | :func:`strftime` description |
+ +-------+-------------------+---------------------------------+
+ | 6 | :attr:`tm_wday` | range [0, 6], Monday is 0 |
+ +-------+-------------------+---------------------------------+
+ | 7 | :attr:`tm_yday` | range [1, 366] |
+ +-------+-------------------+---------------------------------+
+ | 8 | :attr:`tm_isdst` | 0, 1 or -1; see below |
+ +-------+-------------------+---------------------------------+
.. versionadded:: 2.2
+ Note that unlike the C structure, the month value is a range of [1, 12], not
+ [0, 11]. A year value will be handled as described under :ref:`Year 2000
+ (Y2K) issues <time-y2kissues>` above. A ``-1`` argument as the daylight
+ savings flag, passed to :func:`mktime` will usually result in the correct
+ daylight savings state to be filled in.
+
+ When a tuple with an incorrect length is passed to a function expecting a
+ :class:`struct_time`, or having elements of the wrong type, a
+ :exc:`TypeError` is raised.
+
.. function:: time()