Issue #7545: improve documentation of the `buffering` argument in io.open().

1 files changed, 14 insertions, 4 deletions

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 3308639..adde553 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -106,10 +106,20 @@ Module Interface
    :class:`unicode` 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