[issue8899] Add docstrings to time.struct_time
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> _______________________________________
Georg Brandl <georg@python.org> added the comment: Patch review: * Quite a few lines are pretty long. Please stay below 80 chars/line. * There are trailing spaces in two member docs. * The range notation is inconsistent. [first, last] or [first, last+1) is what we generally use. * "if cannot be determined" does not sound grammatical, maybe just "unknown" is better. * Between "strftime()" and "may be considered" the sentence should be split. ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8899> _______________________________________
Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: Please see fixes in issue8899.diff. * Quite a few lines are pretty long. Please stay below 80 chars/line. Fixed. * There are trailing spaces in two member docs. Fixed. * The range notation is inconsistent. [first, last] or [first, last+1) is what we generally use. Fixed in docstrings and time.rst. * "if cannot be determined" does not sound grammatical, maybe just "unknown" is better. Fixed. POSIX spec uses "if the information is not available", but I like * Between "strftime()" and "may be considered" the sentence should be split. Fixed in docstrings and time.rst. ---------- Added file: http://bugs.python.org/file17557/issue8899.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8899> _______________________________________
Georg Brandl <georg@python.org> added the comment: The first change in time.rst is not needed; there the sentence is not a direct description of struct_time. The rest is good to commit. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8899> _______________________________________
Changes by Alexander Belopolsky <belopolsky@users.sourceforge.net>: ---------- resolution: -> accepted _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8899> _______________________________________
Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: Committed in r81756 (trunk) and r81757 (py3k). ---------- stage: commit review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8899> _______________________________________
participants (2)
-
Alexander Belopolsky -
Georg Brandl