From 953e51501e97602e78af07d863e6b5f8ec1258a2 Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Fri, 10 Jun 2022 11:11:09 -0300 Subject: [PATCH 01/13] Clarify the meaning of buffering=-1 in open() This commit clarify the meaning of buffering=-1 in open() function. Add this information in Docs and in source code docstring. --- Doc/library/functions.rst | 12 ++++++------ Lib/_pyio.py | 5 +++-- Modules/_io/_iomodule.c | 5 +++-- Modules/_io/clinic/_iomodule.c.h | 5 +++-- 4 files changed, 15 insertions(+), 12 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index f5e4c1a8640f45..1bc55fe588e0c2 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1181,12 +1181,12 @@ are always available. They are listed here in alphabetical order. *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 - in bytes of a fixed-size chunk buffer. Note that specifying a buffer size this - way applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened - with ``mode='r+'``) would have another buffering. To disable buffering in - ``TextIOWrapper``, consider using the ``write_through`` flag for - :func:`io.TextIOWrapper.reconfigure`. When no *buffering* argument is - given, the default buffering policy works as follows: + in bytes of a fixed-size chunk buffer, or -1 to use the default buffer size. + Note that specifying a buffer size this way applies for binary buffered I/O, + but ``TextIOWrapper`` (i.e., files opened with ``mode='r+'``) would have + another buffering. To disable buffering in ``TextIOWrapper``, consider using + the ``write_through`` flag for :func:`io.TextIOWrapper.reconfigure`. 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 diff --git a/Lib/_pyio.py b/Lib/_pyio.py index 0bfdeaafae274b..bbf8ce55d81c46 100644 --- a/Lib/_pyio.py +++ b/Lib/_pyio.py @@ -123,8 +123,9 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None, 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: + the size of a fixed-size chunk buffer, or-1 to use the default buffer size. + 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 diff --git a/Modules/_io/_iomodule.c b/Modules/_io/_iomodule.c index 38ef24637b7318..40cb43e4afd09a 100644 --- a/Modules/_io/_iomodule.c +++ b/Modules/_io/_iomodule.c @@ -124,8 +124,9 @@ platform-dependent encoding or using the specified encoding if given. 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: +the size of a fixed-size chunk buffer, or -1 to use the default buffer +size. 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 diff --git a/Modules/_io/clinic/_iomodule.c.h b/Modules/_io/clinic/_iomodule.c.h index 0249dd184b1d35..56c8cea2cc0dc7 100644 --- a/Modules/_io/clinic/_iomodule.c.h +++ b/Modules/_io/clinic/_iomodule.c.h @@ -54,8 +54,9 @@ PyDoc_STRVAR(_io_open__doc__, "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" +"the size of a fixed-size chunk buffer, or -1 to use the default buffer size.\n" +"When no buffering argument is given, the default buffering policy works as\n" +"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" From 52239436ff7925795eac1a273f324fc50ea43957 Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Fri, 10 Jun 2022 20:06:06 -0300 Subject: [PATCH 02/13] Update Doc/library/functions.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 1bc55fe588e0c2..8bddf5cf3c8393 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1180,7 +1180,7 @@ are always available. They are listed here in alphabetical order. *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 + buffering (only usable in text mode), an integer > 1 to indicate the size in bytes of a fixed-size chunk buffer, or -1 to use the default buffer size. Note that specifying a buffer size this way applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened with ``mode='r+'``) would have From 421e0e741472581c72f1095f1fb568219dc5faba Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Fri, 10 Jun 2022 20:06:16 -0300 Subject: [PATCH 03/13] Update Lib/_pyio.py Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Lib/_pyio.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/_pyio.py b/Lib/_pyio.py index bbf8ce55d81c46..aa13c768a60010 100644 --- a/Lib/_pyio.py +++ b/Lib/_pyio.py @@ -122,7 +122,7 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None, 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 + line buffering (only usable in text mode), an integer > 1 to indicate the size of a fixed-size chunk buffer, or-1 to use the default buffer size. When no buffering argument is given, the default buffering policy works as follows: From b379ec94c95f1b536432ac06ce3b7ccec3fcbd69 Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Fri, 10 Jun 2022 20:06:29 -0300 Subject: [PATCH 04/13] Update Lib/_pyio.py Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Lib/_pyio.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/_pyio.py b/Lib/_pyio.py index aa13c768a60010..8a807c081cab34 100644 --- a/Lib/_pyio.py +++ b/Lib/_pyio.py @@ -123,7 +123,7 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None, 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), an integer > 1 to indicate - the size of a fixed-size chunk buffer, or-1 to use the default buffer size. + the size of a fixed-size chunk buffer, or -1 to use the default buffering policy. When no buffering argument is given, the default buffering policy works as follows: From 88023fb7bce0c7289eb57c607c617b6353a09d39 Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Fri, 10 Jun 2022 20:06:37 -0300 Subject: [PATCH 05/13] Update Modules/_io/_iomodule.c Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Modules/_io/_iomodule.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Modules/_io/_iomodule.c b/Modules/_io/_iomodule.c index 40cb43e4afd09a..c0530ff2341f75 100644 --- a/Modules/_io/_iomodule.c +++ b/Modules/_io/_iomodule.c @@ -123,7 +123,7 @@ platform-dependent encoding or using the specified encoding if given. 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 +line buffering (only usable in text mode), an integer > 1 to indicate the size of a fixed-size chunk buffer, or -1 to use the default buffer size. When no buffering argument is given, the default buffering policy works as follows: From 0384a43d2fc9e3f5e5c3d301cdf01ca69bb93a26 Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Fri, 10 Jun 2022 20:06:49 -0300 Subject: [PATCH 06/13] Update Modules/_io/_iomodule.c Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Modules/_io/_iomodule.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Modules/_io/_iomodule.c b/Modules/_io/_iomodule.c index c0530ff2341f75..7826df35068815 100644 --- a/Modules/_io/_iomodule.c +++ b/Modules/_io/_iomodule.c @@ -124,8 +124,8 @@ platform-dependent encoding or using the specified encoding if given. 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), an integer > 1 to indicate -the size of a fixed-size chunk buffer, or -1 to use the default buffer -size. When no buffering argument is given, the default buffering policy +the size of a fixed-size chunk buffer, or -1 to use the default buffering +policy. 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 From eacc570a3db6632a4f70de67d13393a77b37a978 Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Fri, 10 Jun 2022 20:06:55 -0300 Subject: [PATCH 07/13] Update Doc/library/functions.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 8bddf5cf3c8393..72ba58987f16d4 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1181,7 +1181,7 @@ are always available. They are listed here in alphabetical order. *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), an integer > 1 to indicate the size - in bytes of a fixed-size chunk buffer, or -1 to use the default buffer size. + in bytes of a fixed-size chunk buffer, or -1 to use the default buffering policy. Note that specifying a buffer size this way applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened with ``mode='r+'``) would have another buffering. To disable buffering in ``TextIOWrapper``, consider using From 0ae953d5bc09cda228fb81412cb6d71a2b3ffca4 Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Fri, 10 Jun 2022 20:30:48 -0300 Subject: [PATCH 08/13] run clinic --- Modules/_io/_iomodule.c | 2 +- Modules/_io/clinic/_iomodule.c.h | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Modules/_io/_iomodule.c b/Modules/_io/_iomodule.c index 7826df35068815..d361550d15b50b 100644 --- a/Modules/_io/_iomodule.c +++ b/Modules/_io/_iomodule.c @@ -197,7 +197,7 @@ static PyObject * _io_open_impl(PyObject *module, PyObject *file, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd, PyObject *opener) -/*[clinic end generated code: output=aefafc4ce2b46dc0 input=5bb37f174cb2fb11]*/ +/*[clinic end generated code: output=aefafc4ce2b46dc0 input=e90b1875043160db]*/ { unsigned i; diff --git a/Modules/_io/clinic/_iomodule.c.h b/Modules/_io/clinic/_iomodule.c.h index 56c8cea2cc0dc7..72bacf605a9ca0 100644 --- a/Modules/_io/clinic/_iomodule.c.h +++ b/Modules/_io/clinic/_iomodule.c.h @@ -53,10 +53,10 @@ PyDoc_STRVAR(_io_open__doc__, "\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, or -1 to use the default buffer size.\n" -"When no buffering argument is given, the default buffering policy works as\n" -"follows:\n" +"line buffering (only usable in text mode), an integer > 1 to indicate\n" +"the size of a fixed-size chunk buffer, or -1 to use the default buffering\n" +"policy. When no buffering argument is given, the default buffering policy\n" +"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" @@ -356,4 +356,4 @@ _io_open_code(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObjec exit: return return_value; } -/*[clinic end generated code: output=c4d7e4ef878985f8 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=262fbd17bd4cc08b input=a9049054013a1b77]*/ From 84b07f272f63254f4ed0b5619042f07d8bb6411a Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Sat, 11 Jun 2022 10:00:48 -0300 Subject: [PATCH 09/13] re-wrap text --- Doc/library/functions.rst | 13 +++++++------ Lib/_pyio.py | 6 +++--- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 72ba58987f16d4..04894ad2c08d5a 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1181,12 +1181,13 @@ are always available. They are listed here in alphabetical order. *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), an integer > 1 to indicate the size - in bytes of a fixed-size chunk buffer, or -1 to use the default buffering policy. - Note that specifying a buffer size this way applies for binary buffered I/O, - but ``TextIOWrapper`` (i.e., files opened with ``mode='r+'``) would have - another buffering. To disable buffering in ``TextIOWrapper``, consider using - the ``write_through`` flag for :func:`io.TextIOWrapper.reconfigure`. When no - *buffering* argument is given, the default buffering policy works as follows: + in bytes of a fixed-size chunk buffer, or -1 to use the default buffering + policy. Note that specifying a buffer size this way applies for binary + buffered I/O, but ``TextIOWrapper`` (i.e., files opened with ``mode='r+'``) + would have another buffering. To disable buffering in ``TextIOWrapper``, + consider using the ``write_through`` flag for + :func:`io.TextIOWrapper.reconfigure`. 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 diff --git a/Lib/_pyio.py b/Lib/_pyio.py index 8a807c081cab34..940af586f6b7a8 100644 --- a/Lib/_pyio.py +++ b/Lib/_pyio.py @@ -123,9 +123,9 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None, 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), an integer > 1 to indicate - the size of a fixed-size chunk buffer, or -1 to use the default buffering policy. - When no buffering argument is given, the default buffering policy works as - follows: + the size of a fixed-size chunk buffer, or -1 to use the default buffering + policy. 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 From 3b2a188877cea98c72b0e14c68bcebe5f8c2f125 Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Tue, 9 Aug 2022 07:19:12 -0300 Subject: [PATCH 10/13] Update Doc/library/functions.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply suggestion of @merwok Co-authored-by: Éric --- Doc/library/functions.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 04894ad2c08d5a..be5fd9a943bbfa 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1182,12 +1182,12 @@ are always available. They are listed here in alphabetical order. to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), an integer > 1 to indicate the size in bytes of a fixed-size chunk buffer, or -1 to use the default buffering - policy. Note that specifying a buffer size this way applies for binary - buffered I/O, but ``TextIOWrapper`` (i.e., files opened with ``mode='r+'``) - would have another buffering. To disable buffering in ``TextIOWrapper``, - consider using the ``write_through`` flag for - :func:`io.TextIOWrapper.reconfigure`. When no *buffering* argument is given, - the default buffering policy works as follows: + policy. Note that specifying a buffer size this way + applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened + with ``mode='r+'``) would have another buffering. To disable buffering in + ``TextIOWrapper``, consider using the ``write_through`` flag for + :func:`io.TextIOWrapper.reconfigure`. 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 From a65f8c7794d55109af073cfba3c400639d219c2d Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Tue, 9 Aug 2022 07:20:09 -0300 Subject: [PATCH 11/13] Update Lib/_pyio.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply suggestion of @merwok Co-authored-by: Éric --- Lib/_pyio.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Lib/_pyio.py b/Lib/_pyio.py index 940af586f6b7a8..9be3c873660bcf 100644 --- a/Lib/_pyio.py +++ b/Lib/_pyio.py @@ -124,8 +124,8 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None, Pass 0 to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), an integer > 1 to indicate the size of a fixed-size chunk buffer, or -1 to use the default buffering - policy. When no buffering argument is given, the default buffering policy - works as follows: + policy. 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 From 29055ca5c13157688a5a8d8d5e98789aeefafe45 Mon Sep 17 00:00:00 2001 From: Emmanuel Arias Date: Tue, 9 Aug 2022 07:20:25 -0300 Subject: [PATCH 12/13] Update Modules/_io/_iomodule.c MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply suggestion of @merwok Co-authored-by: Éric --- Modules/_io/_iomodule.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Modules/_io/_iomodule.c b/Modules/_io/_iomodule.c index d361550d15b50b..f8a3fd1ed218e0 100644 --- a/Modules/_io/_iomodule.c +++ b/Modules/_io/_iomodule.c @@ -125,8 +125,8 @@ 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), an integer > 1 to indicate the size of a fixed-size chunk buffer, or -1 to use the default buffering -policy. When no buffering argument is given, the default buffering policy -works as follows: +policy. 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 From b54846796326f634c41940c8af2188b47704350b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric?= Date: Tue, 9 Aug 2022 10:12:21 -0400 Subject: [PATCH 13/13] minimize diff --- Doc/library/functions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index be5fd9a943bbfa..644bbe615f7c9e 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1182,8 +1182,8 @@ are always available. They are listed here in alphabetical order. to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), an integer > 1 to indicate the size in bytes of a fixed-size chunk buffer, or -1 to use the default buffering - policy. Note that specifying a buffer size this way - applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened + policy. Note that specifying a buffer size this + way applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened with ``mode='r+'``) would have another buffering. To disable buffering in ``TextIOWrapper``, consider using the ``write_through`` flag for :func:`io.TextIOWrapper.reconfigure`. When no *buffering* argument is