diff --git a/Doc/library/io.rst b/Doc/library/io.rst index a72d3ed05c3..a8a4068c7f3 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -94,10 +94,20 @@ Module Interface strings, the bytes having been first decoded using a platform-dependent encoding or using the specified *encoding* if given. - *buffering* is an optional integer used to set the buffering policy. By - default full buffering is on. Pass 0 to switch buffering off (only allowed - in binary mode), 1 to set line buffering, and an integer > 1 to indicate the - size of the buffer. + *buffering* is an optional integer used to set the buffering policy. + Pass 0 to switch buffering off (only allowed in binary mode), 1 to select + line buffering (only usable in text mode), and an integer > 1 to indicate + the size of a fixed-size chunk buffer. When no *buffering* argument is + given, the default buffering policy works as follows: + + * Binary files are buffered in fixed-size chunks; the size of the buffer + is chosen using a heuristic trying to determine the underlying device's + "block size" and falling back on :attr:`DEFAULT_BUFFER_SIZE`. + On many systems, the buffer will typically be 4096 or 8192 bytes long. + + * "Interactive" text files (files for which :meth:`isatty` returns True) + use line buffering. Other text files use the policy described above + for binary files. *encoding* is the name of the encoding used to decode or encode the file. This should only be used in text mode. The default encoding is platform diff --git a/Lib/io.py b/Lib/io.py index 03c867638f4..70f2abaf57e 100644 --- a/Lib/io.py +++ b/Lib/io.py @@ -124,10 +124,20 @@ def open(file, mode="r", buffering=None, encoding=None, errors=None, returned as strings, the bytes having been first decoded using a platform-dependent encoding or using the specified encoding if given. - buffering is an optional integer used to set the buffering policy. By - default full buffering is on. Pass 0 to switch buffering off (only - allowed in binary mode), 1 to set line buffering, and an integer > 1 - for full buffering. + buffering is an optional integer used to set the buffering policy. + Pass 0 to switch buffering off (only allowed in binary mode), 1 to select + line buffering (only usable in text mode), and an integer > 1 to indicate + the size of a fixed-size chunk buffer. When no buffering argument is + given, the default buffering policy works as follows: + + * Binary files are buffered in fixed-size chunks; the size of the buffer + is chosen using a heuristic trying to determine the underlying device's + "block size" and falling back on `io.DEFAULT_BUFFER_SIZE`. + On many systems, the buffer will typically be 4096 or 8192 bytes long. + + * "Interactive" text files (files for which isatty() returns True) + use line buffering. Other text files use the policy described above + for binary files. encoding is the name of the encoding used to decode or encode the file. This should only be used in text mode. The default encoding is