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

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 3308639035665ef3524ce6d88c81f1160cfd18e4..adde553c51d6c64d3efa559f66694115ebc524a0 100644 (file)
--- 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

diff --git a/Lib/_pyio.py b/Lib/_pyio.py
index b0da0458e00e369d505e7150441f293488b13454..5fe928bb1ab70002310026e5cba5ccaca6275ed2 100644 (file)
--- a/Lib/_pyio.py
+++ b/Lib/_pyio.py
@@ -92,6 +92,21 @@ def open(file, mode="r", buffering=None,
     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
     platform dependent, but any encoding supported by Python can be

diff --git a/Modules/_io/_iomodule.c b/Modules/_io/_iomodule.c
index a2a64304b13c8fb7925c609aab86f744c1798d92..ca359bc84ca7627ec3c1d9bbb037465366fcdccd 100644 (file)
--- a/Modules/_io/_iomodule.c
+++ b/Modules/_io/_iomodule.c
@@ -219,10 +219,20 @@ PyDoc_STRVAR(open_doc,
 "returned as strings, the bytes having been first decoded using a\n"
 "platform-dependent encoding or using the specified encoding if given.\n"
 "\n"
-"buffering is an optional integer used to set the buffering policy. By\n"
-"default full buffering is on. Pass 0 to switch buffering off (only\n"
-"allowed in binary mode), 1 to set line buffering, and an integer > 1\n"
-"for full buffering.\n"
+"buffering is an optional integer used to set the buffering policy.\n"
+"Pass 0 to switch buffering off (only allowed in binary mode), 1 to select\n"
+"line buffering (only usable in text mode), and an integer > 1 to indicate\n"
+"the size of a fixed-size chunk buffer.  When no buffering argument is\n"
+"given, the default buffering policy works as follows:\n"
+"\n"
+"* Binary files are buffered in fixed-size chunks; the size of the buffer\n"
+"  is chosen using a heuristic trying to determine the underlying device's\n"
+"  \"block size\" and falling back on `io.DEFAULT_BUFFER_SIZE`.\n"
+"  On many systems, the buffer will typically be 4096 or 8192 bytes long.\n"
+"\n"
+"* \"Interactive\" text files (files for which isatty() returns True)\n"
+"  use line buffering.  Other text files use the policy described above\n"
+"  for binary files.\n"
 "\n"
 "encoding is the name of the encoding used to decode or encode the\n"
 "file. This should only be used in text mode. The default encoding is\n"