New submission from Alexander Belopolsky <belopolsky@users.sourceforge.net>: The time.struct_time class is missing class and field docstrings:
time.struct_time.__doc__ is None True time.struct_time.tm_year.__doc__ is None True
This is significant because it is not obvious that field values are different from those of C language struct tm fields with the same names. (While module level docstring describes the timetuple, it does not list the names of the struct_time fields or mentions struct_time.) With the attached patch,
from time import * localtime() time.struct_time(tm_year=2010, tm_mon=6, tm_mday=4, tm_hour=15, tm_min=27, tm_sec=15, tm_wday=4, tm_yday=155, tm_isdst=1) help(_) Help on struct_time object:
time.struct_time = class struct_time(__builtin__.object) | The time value as returned by gmtime(), localtime(), and strptime(), and accepted | by asctime(), mktime() and strftime(), may be considered as a sequence of 9 integers. | Note that several fields' values are not the same as those defined by the C language | standard for struct tm. For example, the value of tm_year is the actual year, not | year - 1900. See individual fields' descriptions for details. ... | ---------------------------------------------------------------------- | Data descriptors defined here: | | tm_hour | hours, range [0 - 23] | | tm_isdst | 1 if summer time is in effect, 0 if not, and -1 if cannot be determined | | tm_mday | day of month, range [1 - 31] | | tm_min | minutes, range [0 - 59] | | tm_mon | month of year, range [1 - 12] | | 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_year | year, for example, 1993 | | ---------------------------------------------------------------------- ---------- assignee: belopolsky components: Documentation files: struct_time_doc.diff keywords: easy, patch messages: 107089 nosy: belopolsky, docs@python, mark.dickinson priority: normal severity: normal stage: commit review status: open title: Add docstrings to time.struct_time type: feature request versions: Python 2.7, Python 3.2 Added file: http://bugs.python.org/file17556/struct_time_doc.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8899> _______________________________________