Merged revisions 81756 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r81756 | alexander.belopolsky | 2010-06-05 10:54:26 -0400 (Sat, 05 Jun 2010) | 1 line

  Issue #8899: time.struct_time now has class and atribute docstrings.
........

diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index ceae8fa29c2b0363d08562726155c1e4dc227fbd..d3b4305f4b0debddd51b3929483a7f95599aee6b 100644 (file)
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -81,30 +81,31 @@ 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.
+  +-------+-------------------+---------------------------------+
+  | 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.

diff --git a/Misc/NEWS b/Misc/NEWS
index ee997374a91a1bed2cf19c0a5621d8b0013fd28f..a8c430cd056ee8b8fde49844df5327e4b923f741 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -398,6 +398,8 @@ C-API
 Library
 -------
 
+- Issue #8899: time.struct_time now has class and atribute docstrings.
+
 - Issue #6470: Drop UNC prefix in FixTk.
 
 - Issue #4768: base64 encoded email body parts were incorrectly stored as

diff --git a/Modules/timemodule.c b/Modules/timemodule.c
index 20acacfc308ef29d9dccc3a8ff65a59d901911ab..18fe13f2ef8208bd14af408bd8489c321459d4dd 100644 (file)
--- a/Modules/timemodule.c
+++ b/Modules/timemodule.c
@@ -208,21 +208,27 @@ Delay execution for a given number of seconds.  The argument may be\n\
 a floating point number for subsecond precision.");
 
 static PyStructSequence_Field struct_time_type_fields[] = {
-    {"tm_year", NULL},
-    {"tm_mon", NULL},
-    {"tm_mday", NULL},
-    {"tm_hour", NULL},
-    {"tm_min", NULL},
-    {"tm_sec", NULL},
-    {"tm_wday", NULL},
-    {"tm_yday", NULL},
-    {"tm_isdst", NULL},
+    {"tm_year", "year, for example, 1993"},
+    {"tm_mon", "month of year, range [1, 12]"},
+    {"tm_mday", "day of month, range [1, 31]"},
+    {"tm_hour", "hours, range [0, 23]"},
+    {"tm_min", "minutes, range [0, 59]"},
+    {"tm_sec", "seconds, range [0, 61])"},
+    {"tm_wday", "day of week, range [0, 6], Monday is 0"},
+    {"tm_yday", "day of year, range [1, 366]"},
+    {"tm_isdst", "1 if summer time is in effect, 0 if not, and -1 if unknown"},
     {0}
 };
 
 static PyStructSequence_Desc struct_time_type_desc = {
     "time.struct_time",
-    NULL,
+    "The time value as returned by gmtime(), localtime(), and strptime(), and\n"
+    " accepted by asctime(), mktime() and strftime().  May be considered as a\n"
+    " sequence of 9 integers.\n\n"
+    " Note that several fields' values are not the same as those defined by\n"
+    " the C language standard for struct tm.  For example, the value of the\n"
+    " field tm_year is the actual year, not year - 1900.  See individual\n"
+    " fields' descriptions for details.",
     struct_time_type_fields,
     9,
 };