classification
Title: Fix fileinput doc and docstrings (add 'buffer' in 2.7)
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: Terrel.Shumway, docs@python, python-dev, r.david.murray, terry.reedy
Priority: normal Keywords: patch

Created on 2013-06-27 15:59 by Terrel.Shumway, last changed 2013-06-28 23:01 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
fileinput-document-bufsize.patch Terrel.Shumway, 2013-06-27 17:21 patch to document bufsize parameter review
fileinput-document-bufsize.patch Terrel.Shumway, 2013-06-27 17:25 patch to document bufsize parameter review
18315-fileinput-27.diff terry.reedy, 2013-06-28 21:35 added .doc changes review
Messages (12)
msg191952 - (view) Author: Terrel Shumway (Terrel.Shumway) Date: 2013-06-27 15:59
for line in fileinput.input(files,inplace,backup,"rU"):
  File "/usr/lib/python2.7/fileinput.py", line 253, in next
    line = self.readline()
  File "/usr/lib/python2.7/fileinput.py", line 346, in readline
    self._buffer = self._file.readlines(self._bufsize)
TypeError: an integer is required

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.
msg191953 - (view) Author: Terrel Shumway (Terrel.Shumway) Date: 2013-06-27 16:12
http://hg.python.org/cpython/file/4dbbf322a9df/Lib/fileinput.py

>In the process, I added an optional bufsize argument to the input()
>function and the FileInput class.
msg191954 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-06-27 16:19
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.
msg191955 - (view) Author: Terrel Shumway (Terrel.Shumway) Date: 2013-06-27 16:34
http://hg.python.org/cpython/file/68c776ba5ea5/Lib/fileinput.py

This is where the incorrect docstrings get added.
msg191958 - (view) Author: Terrel Shumway (Terrel.Shumway) Date: 2013-06-27 17:21
Here is a patch against the 2.7 branch.  It will probably also apply to 2.6 if anyone cares.
msg191959 - (view) Author: Terrel Shumway (Terrel.Shumway) Date: 2013-06-27 17:25
Oops. I messed up, even on such a tiny fix. #:(
msg192019 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-06-28 21:20
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.
msg192020 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-06-28 21:27
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?
msg192021 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-06-28 21:34
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).
msg192022 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-06-28 21:50
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:

input(files=None, inplace=False, backup='', bufsize=0, mode='r', openhook=None)
    input(files=None, inplace=False, backup="", bufsize=0, mode="r", openhook=None)
...
So the 3.x files need correcting also.
For .doc, the signature does need to be present and correct.
msg192023 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-06-28 23:00
New changeset 80b1c5b25ff0 by Terry Jan Reedy in branch '2.7':
Issue #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 #18315: Improve fileinput docs by adding 'bufsize' where missing and
http://hg.python.org/cpython/rev/0760b58526ba
msg192024 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-06-28 23:01
There was one missing 'bufsize' in 3.x also.
History
Date User Action Args
2013-06-28 23:01:29terry.reedysetstatus: open -> closed
resolution: fixed
messages: + msg192024

stage: resolved
2013-06-28 23:00:19python-devsetnosy: + python-dev
messages: + msg192023
2013-06-28 21:50:47terry.reedysettitle: bufsize parameter not documented in 2.7.5 -> Fix fileinput doc and docstrings (add 'buffer' in 2.7)
messages: + msg192022
versions: + Python 3.3, Python 3.4
2013-06-28 21:35:41terry.reedysetfiles: + 18315-fileinput-27.diff
2013-06-28 21:34:17r.david.murraysetmessages: + msg192021
2013-06-28 21:27:19terry.reedysetmessages: + msg192020
2013-06-28 21:20:36terry.reedysetassignee: docs@python -> terry.reedy

messages: + msg192019
nosy: + terry.reedy
2013-06-27 17:25:00Terrel.Shumwaysetfiles: + fileinput-document-bufsize.patch

messages: + msg191959
2013-06-27 17:21:02Terrel.Shumwaysetfiles: + fileinput-document-bufsize.patch
keywords: + patch
messages: + msg191958
2013-06-27 16:34:47Terrel.Shumwaysetmessages: + msg191955
2013-06-27 16:19:41r.david.murraysetnosy: + r.david.murray
messages: + msg191954
2013-06-27 16:12:57Terrel.Shumwaysetmessages: + msg191953
2013-06-27 15:59:58Terrel.Shumwaycreate