classification
Title: tempfile module: functions with the 'buffering' option are incorrectly documented
Type: Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: MartyMacGyver, akshaysharma096, docs@python, miss-islington, sir-sigurd, vinay.sajip, ztane
Priority: normal Keywords: patch

Created on 2018-04-07 19:22 by MartyMacGyver, last changed 2020-09-13 18:21 by vinay.sajip. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 6418 closed akshaysharma, 2018-04-08 12:08
PR 21763 merged sir-sigurd, 2020-09-13 17:41
PR 22225 merged miss-islington, 2020-09-13 18:05
PR 22226 merged miss-islington, 2020-09-13 18:05
Messages (7)
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.
msg376840 - (view) Author: miss-islington (miss-islington) Date: 2020-09-13 17:59
New changeset b48389d95093c3f912549add8da339edc164bf0d by Sergey Fedoseev in branch 'master':
bpo-33239: Fix default value of 'buffering' parameter in docs of tempfile.* functions (GH-21763)
https://github.com/python/cpython/commit/b48389d95093c3f912549add8da339edc164bf0d
msg376842 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2020-09-13 18:16
New changeset bf50b0e80a8a0d651af2f953b662eeadd27c7c93 by Miss Islington (bot) in branch '3.8':
bpo-33239: Fix default value of 'buffering' parameter in docs of tempfile.* functions (GH-21763) (GH-22226)
https://github.com/python/cpython/commit/bf50b0e80a8a0d651af2f953b662eeadd27c7c93
msg376843 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2020-09-13 18:20
New changeset c978be283db768743d995f04414c65439a632bdd by Miss Islington (bot) in branch '3.9':
bpo-33239: Fix default value of 'buffering' parameter in docs of tempfile.* functions (GH-21763) (GH-22225)
https://github.com/python/cpython/commit/c978be283db768743d995f04414c65439a632bdd
History
Date User Action Args
2020-09-13 18:21:10vinay.sajipsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2020-09-13 18:20:41vinay.sajipsetmessages: + msg376843
2020-09-13 18:17:37vinay.sajipsetversions: - Python 3.7
2020-09-13 18:16:42vinay.sajipsetnosy: + vinay.sajip
messages: + msg376842
2020-09-13 18:08:33vinay.sajipsetversions: + Python 3.9, Python 3.10, - Python 3.4, Python 3.5, Python 3.6
2020-09-13 18:05:28miss-islingtonsetpull_requests: + pull_request21281
2020-09-13 18:05:19miss-islingtonsetpull_requests: + pull_request21280
2020-09-13 17:59:04miss-islingtonsetnosy: + miss-islington
messages: + msg376840
2020-09-13 17:41:53sir-sigurdsetnosy: + sir-sigurd
pull_requests: + pull_request21279
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