Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from
svn+ssh://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.
........
r85532 | georg.brandl | 2010-10-15 18:03:02 +0200 (Fr, 15 Okt 2010) | 1 line
#7771: reference to documentation of dictview methods and operations.
........
r85533 | georg.brandl | 2010-10-15 18:07:41 +0200 (Fr, 15 Okt 2010) | 1 line
#9683: remove broken dead code dealing with nested arguments removed from Py3k, and update the docs and docstrings accordingly.
........
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.
........
r85539 | georg.brandl | 2010-10-15 18:42:14 +0200 (Fr, 15 Okt 2010) | 1 line
Fix issue references.
........
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.
........
r85543 | georg.brandl | 2010-10-15 19:03:02 +0200 (Fr, 15 Okt 2010) | 1 line
#4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
........
r85546 | georg.brandl | 2010-10-15 19:58:45 +0200 (Fr, 15 Okt 2010) | 1 line
#5762: fix handling of empty namespace in minidom, which would result in AttributeError on toxml().
........
r85547 | georg.brandl | 2010-10-15 20:00:35 +0200 (Fr, 15 Okt 2010) | 1 line
#6098: Refrain from claiming DOM level 3 conformance in minidom.
........
r85548 | georg.brandl | 2010-10-15 21:46:19 +0200 (Fr, 15 Okt 2010) | 1 line
#10072: assume a bit less knowledge of the FTP protocol in the ftplib docs.
........
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index ceae8fa..b91aa53 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -16,21 +16,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
@@ -47,16 +49,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
@@ -81,37 +83,7 @@
: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.
* Use the following functions to convert between time representations:
@@ -388,10 +360,45 @@
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 |
+ +-------+-------------------+---------------------------------+
+
+ 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()