New submission from Alexander Belopolsky <belopol...@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, d...@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 <rep...@bugs.python.org> <http://bugs.python.org/issue8899> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
