[New-bugs-announce] [issue8899] Add docstrings to time.struct_time

[Alexander Belopolsky]

New submission from Alexander Belopolsky <belopolsky at 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 at 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 at bugs.python.org>
<http://bugs.python.org/issue8899>
_______________________________________