[docs] [issue19622] Default buffering for input and output pipes in subprocess module

[Martin Panter]

New submission from Martin Panter:

Currently the documentation for the “bufsize” parameter in the “subprocess” module says:

"""
Changed in version 3.2.4,: 3.3.1

bufsize now defaults to -1 to enable buffering by default to match the behavior that most code expects. In 3.2.0 through 3.2.3 and 3.3.0 it incorrectly defaulted to 0 which was unbuffered and allowed short reads. This was unintentional and did not match the behavior of Python 2 as most code expected.
"""

First of all the formatting is a bit screwy. There’s a colon in the wrong place, so it’s not obvious that the “changed in version” heading applies to the following paragraph.

The main issue is that I got the impression the default of 0 was a regression, and that Python 3.1 and Python 2 defaulted to -1. However, as far as I can tell the default was actually 0 in 3.1 and 2.

The change to -1 was for Issue 17488, which seems to be focussed on the behaviour of reading from a subprocess’s output pipe. In Python 2, file.read() blocks to read as much as possible, even when buffering is disabled. In Python 3, you end up with either a FileIO or a BufferedIOBase object, and they have different read() behaviours.

Perhaps the documentation should say something like

"""
The “bufsize” argument now defaults to -1 to enable buffering. In 3.2.3, 3.3.0, and earlier, it defaulted to 0 which was unbuffered and allowed short reads.
"""

I would take out the “most code expects buffering” bits. Maybe most code expects the greedy read behaviour from output pipes, but I would say most code writing to an input pipe expects unbuffered behaviour. The big issue with buffering for me is that BufferedWriter.close() may raise a broken pipe condition.

If you want to mention Python 2, maybe say that Python 2 did not use buffering by default, but that file.read() always had blocking read behaviour, which can be emulated by using buffered reading in Python 3.

----------
assignee: docs at python
components: Documentation
messages: 203010
nosy: docs at python, vadmium
priority: normal
severity: normal
status: open
title: Default buffering for input and output pipes in subprocess module
type: behavior
versions: Python 3.2, Python 3.3, Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue19622>
_______________________________________