#7790: move table of struct_time members to the actual description of struct_time.

birkenfeld · birkenfeld · commit b67878a522a1 · 2010-10-15T17:01:15.000Z
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
@@ -16,21 +16,23 @@ semantics of these functions varies among platforms.
 
 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 @@ An explanation of some terminology and conventions is in order.
   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,38 +83,7 @@ An explanation of some terminology and conventions is in order.
   :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:
 
@@ -389,10 +360,45 @@ The module defines the following functions and data items:
    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()
