Merged revisions 76896 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().
........

1 files changed, 14 insertions, 4 deletions

diff --git a/Lib/io.py b/Lib/io.py
index 03c867638f..70f2abaf57 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