Merged revisions 76900 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

................
  r76900 | antoine.pitrou | 2009-12-19 22:08:31 +0100 (sam., 19 déc. 2009) | 13 lines

  Merged revisions 76896,76898 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r76896 | antoine.pitrou | 2009-12-19 22:01:10 +0100 (sam., 19 déc. 2009) | 3 lines

    Issue #7545: improve documentation of the `buffering` argument in io.open().
  ........
    r76898 | antoine.pitrou | 2009-12-19 22:06:36 +0100 (sam., 19 déc. 2009) | 3 lines

    Remove superfetatory paragraph (left there by mistake).
  ........
................

3 files changed, 42 insertions, 12 deletions

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 8fb984e..90573bd 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -96,10 +96,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/_pyio.py b/Lib/_pyio.py
index 5458f99..2458e40 100644
--- a/Lib/_pyio.py
+++ b/Lib/_pyio.py
@@ -82,10 +82,20 @@ def open(file: (str, bytes), mode: str = "r", buffering: int = 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
diff --git a/Modules/_io/_iomodule.c b/Modules/_io/_iomodule.c
index dfd66aa..14a4356 100644
--- 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"