From d5587bc4745f9d0b1dfdf7c93947f5b197a37176 Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Sat, 19 Dec 2009 21:08:31 +0000 Subject: Merged revisions 76896,76898 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ 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). ........ --- Doc/library/io.rst | 18 ++++++++++++++---- Lib/_pyio.py | 18 ++++++++++++++---- Modules/_io/_iomodule.c | 18 ++++++++++++++---- 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 04aed8d..a4beb2b 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" -- cgit v0.12