This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Add docstrings to time.struct_time
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 2.7
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: belopolsky Nosy List: belopolsky, docs@python, georg.brandl, mark.dickinson
Priority: normal Keywords: easy, patch

Created on 2010-06-04 19:47 by belopolsky, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
struct_time_doc.diff belopolsky, 2010-06-04 19:47 Patch for trunk
issue8899.diff belopolsky, 2010-06-04 20:46
Messages (5)
msg107089 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-04 19:47
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
 |  
 |  ----------------------------------------------------------------------
msg107096 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-06-04 20:21
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.
msg107099 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-04 20:46
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.
msg107101 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-06-04 21:09
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.
msg107138 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-05 15:13
Committed in r81756 (trunk) and r81757 (py3k).
History
Date User Action Args
2022-04-11 14:57:01adminsetgithub: 53145
2010-06-05 15:13:29belopolskysetstatus: open -> closed

messages: + msg107138
stage: commit review -> resolved
2010-06-04 22:26:24belopolskysetresolution: accepted
2010-06-04 21:09:10georg.brandlsetmessages: + msg107101
2010-06-04 20:46:29belopolskysetfiles: + issue8899.diff

messages: + msg107099
2010-06-04 20:21:48georg.brandlsetnosy: + georg.brandl
messages: + msg107096
2010-06-04 19:47:16belopolskycreate