[New-bugs-announce] [issue33239] tempfile module: functions with the 'buffering' option are incorrectly documented

[Martin Falatic]

New submission from Martin Falatic <martin at falatic.com>:

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.

----------
assignee: docs at python
components: Documentation
messages: 315072
nosy: MartyMacGyver, docs at python
priority: normal
severity: normal
status: open
title: tempfile module: functions with the 'buffering' option are incorrectly documented
versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue33239>
_______________________________________