classification
Title: tempfile module: functions with the 'buffering' option are incorrectly documented
Type: Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6, Python 3.5, Python 3.4
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: MartyMacGyver, akshaysharma096, docs@python, ztane
Priority: normal Keywords: patch

Created on 2018-04-07 19:22 by MartyMacGyver, last changed 2018-09-13 18:08 by ztane.

Pull Requests
URL Status Linked Edit
PR 6418 open akshaysharma, 2018-04-08 12:08
Messages (4)
msg315072 - (view) Author: Martin Falatic (MartyMacGyver) * Date: 2018-04-07 19:22
The documentation for the tempfile module in Python 3.x for the `buffering` option is incorrect:

https://docs.python.org/3/library/tempfile.html

TemporaryFile, NamedTemporaryFile, and SpooledTemporaryFile all take the `buffering` option, which in turn appears to correlate to the Python 2.7 option `bufsize`, which was and continues to be an integer (per the source).

In the 3.x documentation the default signature for TemporaryFile, NamedTemporaryFile, and SpooledTemporaryFile includes `buffering=None`. Actually specifying None as a default for this will cause an exception (`TypeError: an integer is required (got type NoneType)`).

There is a cross-reference in the 3.x tempfile docs to `open` (https://docs.python.org/3/library/functions.html#open) which in turn shows the correct signature to use for `buffering`. Additionally, the source code is clearly documented (https://github.com/python/cpython/blob/master/Lib/tempfile.py)

A good correction would be to ensure `buffering=-1` is documented as the default for the three functions in tempfile, with an additional note explicitly stating that -1 == no buffering, and the existing `open` cross-reference retained.
msg315082 - (view) Author: Akshay Sharma (akshaysharma096) * Date: 2018-04-08 11:22
Hi, will it be good to link the cross-reference for `open`(https://docs.python.org/3/library/functions.html#open) in the documentation?

I think specifically mentioning the usage of the  `buffering` is a better way.
msg315100 - (view) Author: Martin Falatic (MartyMacGyver) * Date: 2018-04-08 23:41
The correction of `buffering=None` --> `buffering=-1` for the defaults definitely needs to happen.

A reference to `open()` is already present in the 3.x documentation: "buffering, encoding and newline are interpreted as for open()."

Given that the `open()` reference already suffices for `encoding` and `newline`, it ought to suffice for `buffering` as well. No extra text beyond that should be necessary (I originally thought that might be good to add, but looking at this now it's clear if you add more to describe `buffering` you'll need to add it for the other two options, and it's all duplicative. Fixing the defaults should suffice.)
msg325271 - (view) Author: Antti Haapala (ztane) * Date: 2018-09-13 18:08
This week we were bit by this in production. I foolishly thought that the  docs would give me correct default values... It is worse that it didn't actually occur until we went over the limit.
History
Date User Action Args
2018-09-13 18:08:51ztanesetnosy: + ztane
messages: + msg325271
2018-04-08 23:41:40MartyMacGyversetmessages: + msg315100
2018-04-08 12:08:51akshaysharmasetkeywords: + patch
stage: patch review
pull_requests: + pull_request6120
2018-04-08 11:22:25akshaysharma096setnosy: + akshaysharma096
messages: + msg315082
2018-04-07 19:22:42MartyMacGyvercreate