Repository navigation
Fix fileinput doc and docstrings (add 'buffer' in 2.7) #62515
Description
| BPO | 18315 |
|---|---|
| Nosy | @terryjreedy, @bitdancer |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = 'https://github.com/terryjreedy'
closed_at = <Date 2013-06-28.23:01:29.168>
created_at = <Date 2013-06-27.15:59:58.437>
labels = ['type-bug', 'docs']
title = "Fix fileinput doc and docstrings (add 'buffer' in 2.7)"
updated_at = <Date 2013-06-28.23:01:29.167>
user = 'https://bugs.python.org/TerrelShumway'bugs.python.org fields:
activity = <Date 2013-06-28.23:01:29.167>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2013-06-28.23:01:29.168>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2013-06-27.15:59:58.437>
creator = 'Terrel.Shumway'
dependencies = []
files = ['30712', '30713', '30727']
hgrepos = []
issue_num = 18315
keywords = ['patch']
message_count = 12.0
messages = ['191952', '191953', '191954', '191955', '191958', '191959', '192019', '192020', '192021', '192022', '192023', '192024']
nosy_count = 5.0
nosy_names = ['terry.reedy', 'r.david.murray', 'docs@python', 'python-dev', 'Terrel.Shumway']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue18315'
versions = ['Python 2.7', 'Python 3.3', 'Python 3.4']
Activity
terrelshumway commentedon Jun 27, 2013
According to the documentation, my code was correct. But somewhere along the line, someone added a 'bufsize' parameter and didn't update the docstrings.
It's an easy fix, but I'll have to investigate when this broke.
terrelshumway commentedon Jun 27, 2013
http://hg.python.org/cpython/file/4dbbf322a9df/Lib/fileinput.py
bitdancer commentedon Jun 27, 2013
A quick look at the VCS history indicates bufsize has been in there for a long time. The sphinx docs are wrong as well. This is correctly documented in python3, apparently as part of the conversion from [] notation to keyword notation in d143eb624cf5.
terrelshumway commentedon Jun 27, 2013
http://hg.python.org/cpython/file/68c776ba5ea5/Lib/fileinput.py
This is where the incorrect docstrings get added.
terrelshumway commentedon Jun 27, 2013
Here is a patch against the 2.7 branch. It will probably also apply to 2.6 if anyone cares.
terrelshumway commentedon Jun 27, 2013
Oops. I messed up, even on such a tiny fix. #:(
terryjreedy commentedon Jun 28, 2013
If you think you will ever contribute another patch (and we hope you do), and you have not yet submitted a contributor agreement, please do.
http://www.python.org/psf/contrib/contrib-form/
http://www.python.org/psf/contrib/
Once processed, a * will appear after your name.
In the meanwhile, I will fix this. (2.6 is security patches only.)
Your patch missed the doc, as opposed to the docstrings, but your report with tracker research was unusually complete. Thanks.
terryjreedy commentedon Jun 28, 2013
David, with the addition, this line
"""class FileInput([files[, inplace[, backup[, bufsize[, mode[, openhook]]]]]])
ends at position 83 instead of 80. It should stay on one line. I could reduce that by removing blanks after ,s. Is it better to be a bit too long or a bit too compressed?
bitdancer commentedon Jun 28, 2013
At 83 it is a judgement call whether to leave it long or wrap it. I wouldn't compress it. (Wrapping is done by putting a '\' at the end of the line you want to wrap, if you don't already know that).
terryjreedy commentedon Jun 28, 2013
I just remembered: the first list of a .py file docstring should be a one line summary of what the callable does. It should not give the signature because (unlike C function currently) help does that for us from the callable itself (using the inspect module). Putting it in the docstring just repeats it. On 3.3.2:
>>> help(fileinput.input) Help on function input in module fileinput:[-]bufsize parameter not documented in 2.7.5[/-][+]Fix fileinput doc and docstrings (add 'buffer' in 2.7)[/+]python-dev commentedon Jun 28, 2013
New changeset 80b1c5b25ff0 by Terry Jan Reedy in branch '2.7':
Issue bpo-18315: Improve fileinput docs by adding 'bufsize' where missing and
http://hg.python.org/cpython/rev/80b1c5b25ff0
New changeset 0760b58526ba by Terry Jan Reedy in branch '3.3':
Issue bpo-18315: Improve fileinput docs by adding 'bufsize' where missing and
http://hg.python.org/cpython/rev/0760b58526ba
terryjreedy commentedon Jun 28, 2013
There was one missing 'bufsize' in 3.x also.