From 7cc4851ac4ba300e863306b33abd401e94dcfdee Mon Sep 17 00:00:00 2001 From: Vemulakonda559 <42494818+Vemulakonda559@users.noreply.github.com> Date: Wed, 12 Nov 2025 07:34:10 +0530 Subject: [PATCH 01/15] Clarify stdout flush behavior for newline characters in print() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR adds a note to the print() documentation to clarify how Python’s stdout buffering works with newline (\n) characters inside a single print call. Motivation: Current documentation mentions that flush() is implied for writes containing newlines. However, it does not explain that Python flushes only after the entire write operation, not mid-string. This can confuse users coming from C, who expect a flush at each newline, and developers writing scripts that rely on immediate output for progress indicators or CLI feedback. What’s added: A .. note:: block explaining that stdout behavior depends on the environment (TTY vs redirected stdout). Guidance on explicitly flushing with flush=True or sys.stdout.flush(). Mention of python -u for unbuffered output. A short example demonstrating the behavior. Impact: Improves clarity for learners and developers. Aligns documentation with actual behavior across different environments. Not a behavior change — documentation-only PR. Related Issue: Addresses issue #141395 --- Doc/library/functions.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index e98793975556ef..dbca95bcaf268b 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1607,6 +1607,31 @@ are always available. They are listed here in alphabetical order. Output buffering is usually determined by *file*. However, if *flush* is true, the stream is forcibly flushed. +.. note:: + + In Python, printing a string containing newline characters does not automatically flush stdout. + Python performs buffering at the write/operation level, so newlines inside a single write + do not necessarily trigger an immediate flush. The exact timing of output may vary depending + on the environment: + + - When stdout is connected to a terminal (TTY), output is line-buffered and typically flushes + after the write completes. + - When stdout is redirected to a file or pipe, output may be fully buffered and not flush + until the buffer fills or flush is requested. + + For guaranteed immediate output, use ``flush=True`` or call ``sys.stdout.flush()`` explicitly. + Running Python with the ``-u`` flag also forces unbuffered output, which may be useful in + scripts requiring immediate writes. + + Example: + + .. code-block:: python + + from time import sleep + + print("Hello\nWorld", end='') # Both lines appear together on TTY + sleep(3) + print("Hi there!") .. versionchanged:: 3.3 Added the *flush* keyword argument. From 1926974f1ece1d31ff1faaf831f99dca7b9206c5 Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 21:58:18 +0530 Subject: [PATCH 02/15] Refactor stdout flushing note for clarity Removed duplicate text and improved clarity in the note about stdout flushing behavior. --- Doc/library/functions.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index dbca95bcaf268b..4d5741e5ea00f9 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1609,33 +1609,34 @@ are always available. They are listed here in alphabetical order. .. note:: - In Python, printing a string containing newline characters does not automatically flush stdout. - Python performs buffering at the write/operation level, so newlines inside a single write - do not necessarily trigger an immediate flush. The exact timing of output may vary depending + In Python, printing a string containing newline characters does not automatically flush stdout. + Python performs buffering at the write/operation level, so newlines inside a single write + do not necessarily trigger an immediate flush. The exact timing of output may vary depending on the environment: - - When stdout is connected to a terminal (TTY), output is line-buffered and typically flushes + - When stdout is connected to a terminal (TTY), output is line-buffered and typically flushes after the write completes. - - When stdout is redirected to a file or pipe, output may be fully buffered and not flush + - When stdout is redirected to a file or pipe, output may be fully buffered and not flush until the buffer fills or flush is requested. - For guaranteed immediate output, use ``flush=True`` or call ``sys.stdout.flush()`` explicitly. - Running Python with the ``-u`` flag also forces unbuffered output, which may be useful in + For guaranteed immediate output, use ``flush=True`` or call ``sys.stdout.flush()`` explicitly. + Running Python with the ``-u`` flag also forces unbuffered output, which may be useful in scripts requiring immediate writes. Example: .. code-block:: python - from time import sleep - print("Hello\nWorld", end='') # Both lines appear together on TTY + # Whether the default end is a newline ('\\n') or any other character, + # Python performs a single write operation for the entire string. + # Therefore, newlines inside the string do not cause mid-string flushing. + print("Hello\nWorld") sleep(3) print("Hi there!") - .. versionchanged:: 3.3 - Added the *flush* keyword argument. - +.. versionchanged:: 3.3 + Added the *flush* keyword argument. .. class:: property(fget=None, fset=None, fdel=None, doc=None) From b910a6d1cb4023e4da896dbf570ab010c2ad8ea5 Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 22:12:03 +0530 Subject: [PATCH 03/15] Refactor output buffering documentation for clarity --- Doc/library/functions.rst | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 4d5741e5ea00f9..80aefef17c46ff 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1607,27 +1607,29 @@ are always available. They are listed here in alphabetical order. Output buffering is usually determined by *file*. However, if *flush* is true, the stream is forcibly flushed. +Output buffering is usually determined by *file*. However, if *flush* is true, +the stream is forcibly flushed. + .. note:: - In Python, printing a string containing newline characters does not automatically flush stdout. - Python performs buffering at the write/operation level, so newlines inside a single write - do not necessarily trigger an immediate flush. The exact timing of output may vary depending - on the environment: + In Python, printing a string containing newline characters does not automatically + flush stdout. Python performs buffering at the write/operation level, so newlines + inside a single write do not necessarily trigger an immediate flush. The exact + timing of output may vary depending on the environment: - - When stdout is connected to a terminal (TTY), output is line-buffered and typically flushes - after the write completes. - - When stdout is redirected to a file or pipe, output may be fully buffered and not flush - until the buffer fills or flush is requested. + - When stdout is connected to a terminal (TTY), output is line-buffered and + typically flushes after the write completes. + - When stdout is redirected to a file or pipe, output may be fully buffered and + not flush until the buffer fills or flush is requested. - For guaranteed immediate output, use ``flush=True`` or call ``sys.stdout.flush()`` explicitly. - Running Python with the ``-u`` flag also forces unbuffered output, which may be useful in - scripts requiring immediate writes. + For guaranteed immediate output, use ``flush=True`` or call + ``sys.stdout.flush()`` explicitly. Running Python with the ``-u`` flag also + forces unbuffered output, which may be useful in scripts requiring immediate writes. Example: .. code-block:: python from time import sleep - # Whether the default end is a newline ('\\n') or any other character, # Python performs a single write operation for the entire string. # Therefore, newlines inside the string do not cause mid-string flushing. @@ -1638,6 +1640,7 @@ are always available. They are listed here in alphabetical order. .. versionchanged:: 3.3 Added the *flush* keyword argument. + .. class:: property(fget=None, fset=None, fdel=None, doc=None) Return a property attribute. From 8831449693997bd71137e09956392c4093ab528d Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 22:23:10 +0530 Subject: [PATCH 04/15] Update functions.rst From 2a95d38d26366a38083534c66af3dc47e88a8a5a Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 22:24:29 +0530 Subject: [PATCH 05/15] Update functions.rst From 12894fa80f67734b0194452a2c251bea4edcebce Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 22:29:05 +0530 Subject: [PATCH 06/15] Update functions.rst From 7ee22db1adc5995d96e4d48ecc706b6bb7b2daf3 Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 22:36:44 +0530 Subject: [PATCH 07/15] Simplify output buffering explanation Removed redundant sentence about output buffering. --- Doc/library/functions.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 80aefef17c46ff..dd0d004e68ea8b 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1607,9 +1607,6 @@ are always available. They are listed here in alphabetical order. Output buffering is usually determined by *file*. However, if *flush* is true, the stream is forcibly flushed. -Output buffering is usually determined by *file*. However, if *flush* is true, -the stream is forcibly flushed. - .. note:: In Python, printing a string containing newline characters does not automatically From e7b2c6916b2910ef6a25a4bfa52f1a5e09d83bfe Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 22:52:39 +0530 Subject: [PATCH 08/15] Clean up comments in functions.rst Removed unnecessary comments about string flushing in print. --- Doc/library/functions.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index dd0d004e68ea8b..1c10e4a62de43a 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1627,9 +1627,6 @@ are always available. They are listed here in alphabetical order. .. code-block:: python from time import sleep - # Whether the default end is a newline ('\\n') or any other character, - # Python performs a single write operation for the entire string. - # Therefore, newlines inside the string do not cause mid-string flushing. print("Hello\nWorld") sleep(3) print("Hi there!") @@ -1637,7 +1634,6 @@ are always available. They are listed here in alphabetical order. .. versionchanged:: 3.3 Added the *flush* keyword argument. - .. class:: property(fget=None, fset=None, fdel=None, doc=None) Return a property attribute. From 72a8ca736a538621f273ff75e525ba9c2a1f962d Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 23:13:28 +0530 Subject: [PATCH 09/15] Fix formatting and indentation in functions.rst --- Doc/library/functions.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 1c10e4a62de43a..dafdcb8a420fd8 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1607,29 +1607,29 @@ are always available. They are listed here in alphabetical order. Output buffering is usually determined by *file*. However, if *flush* is true, the stream is forcibly flushed. -.. note:: + .. note:: - In Python, printing a string containing newline characters does not automatically - flush stdout. Python performs buffering at the write/operation level, so newlines - inside a single write do not necessarily trigger an immediate flush. The exact - timing of output may vary depending on the environment: + In Python, printing a string containing newline characters does not automatically + flush stdout. Python performs buffering at the write/operation level, so newlines + inside a single write do not necessarily trigger an immediate flush. The exact + timing of output may vary depending on the environment: - - When stdout is connected to a terminal (TTY), output is line-buffered and - typically flushes after the write completes. - - When stdout is redirected to a file or pipe, output may be fully buffered and - not flush until the buffer fills or flush is requested. + - When stdout is connected to a terminal (TTY), output is line-buffered and + typically flushes after the write completes. + - When stdout is redirected to a file or pipe, output may be fully buffered and + not flush until the buffer fills or flush is requested. - For guaranteed immediate output, use ``flush=True`` or call - ``sys.stdout.flush()`` explicitly. Running Python with the ``-u`` flag also - forces unbuffered output, which may be useful in scripts requiring immediate writes. + For guaranteed immediate output, use ``flush=True`` or call + ``sys.stdout.flush()`` explicitly. Running Python with the ``-u`` flag also + forces unbuffered output, which may be useful in scripts requiring immediate writes. - Example: + Example: - .. code-block:: python - from time import sleep - print("Hello\nWorld") - sleep(3) - print("Hi there!") + .. code-block:: python + from time import sleep + print("Hello\nWorld") + sleep(3) + print("Hi there!") .. versionchanged:: 3.3 Added the *flush* keyword argument. From 76e48de6835cb33d7c8e007392577dd5dce66011 Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 23:25:24 +0530 Subject: [PATCH 10/15] Refactor function documentation formatting Remove extra blank lines and fix indentation for versionchanged directive. --- Doc/library/functions.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index dafdcb8a420fd8..d4b5303dab48ca 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1544,7 +1544,6 @@ are always available. They are listed here in alphabetical order. length 1, return its single byte value. For example, ``ord(b'a')`` returns the integer ``97``. - .. function:: pow(base, exp, mod=None) Return *base* to the power *exp*; if *mod* is present, return *base* to the @@ -1586,7 +1585,6 @@ are always available. They are listed here in alphabetical order. Allow keyword arguments. Formerly, only positional arguments were supported. - .. function:: print(*objects, sep=' ', end='\n', file=None, flush=False) Print *objects* to the text stream *file*, separated by *sep* and followed @@ -1631,8 +1629,8 @@ are always available. They are listed here in alphabetical order. sleep(3) print("Hi there!") -.. versionchanged:: 3.3 - Added the *flush* keyword argument. + .. versionchanged:: 3.3 + Added the *flush* keyword argument. .. class:: property(fget=None, fset=None, fdel=None, doc=None) From 871aaa1b84df5f048c1d17e218b4339bfa173705 Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 23:48:21 +0530 Subject: [PATCH 11/15] Reorganize output buffering description in functions.rst Reformat output buffering explanation for clarity. --- Doc/library/functions.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index d4b5303dab48ca..334e6a44bf4f1c 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1602,8 +1602,8 @@ are always available. They are listed here in alphabetical order. arguments are converted to text strings, :func:`print` cannot be used with binary mode file objects. For these, use ``file.write(...)`` instead. - Output buffering is usually determined by *file*. - However, if *flush* is true, the stream is forcibly flushed. + Output buffering is usually determined by *file*. However, if *flush* is + true, the stream is forcibly flushed. .. note:: @@ -1625,6 +1625,8 @@ are always available. They are listed here in alphabetical order. .. code-block:: python from time import sleep + # This call performs one write operation, so the newline inside the string + # does not trigger an immediate flush by itself. print("Hello\nWorld") sleep(3) print("Hi there!") From 1d3f1bcdd5b2f86830809069952c858d2c696a14 Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Sat, 29 Nov 2025 23:59:29 +0530 Subject: [PATCH 12/15] Update functions.rst From d85bb37753d35af833f85fe25977cac0fa1025f5 Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Mon, 1 Dec 2025 19:29:09 +0530 Subject: [PATCH 13/15] Update functions.rst From 7005cc3cc61a1012199c9067fad8bebc43c60752 Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Mon, 1 Dec 2025 19:52:52 +0530 Subject: [PATCH 14/15] Fix indentation in functions.rst example code --- 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 334e6a44bf4f1c..c9855b38e905bb 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1624,12 +1624,12 @@ are always available. They are listed here in alphabetical order. Example: .. code-block:: python - from time import sleep - # This call performs one write operation, so the newline inside the string - # does not trigger an immediate flush by itself. - print("Hello\nWorld") - sleep(3) - print("Hi there!") + from time import sleep + # This call performs one write operation, so the newline inside the string + # does not trigger an immediate flush by itself. + print("Hello\nWorld") + sleep(3) + print("Hi there!") .. versionchanged:: 3.3 Added the *flush* keyword argument. From 2d66675abf645bc8cb1fee930aea0149624e628e Mon Sep 17 00:00:00 2001 From: Vemulakonda559 Date: Mon, 1 Dec 2025 20:05:06 +0530 Subject: [PATCH 15/15] Fix indentation in example code block --- Doc/library/functions.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index c9855b38e905bb..013415128e046f 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1624,12 +1624,13 @@ are always available. They are listed here in alphabetical order. Example: .. code-block:: python - from time import sleep - # This call performs one write operation, so the newline inside the string - # does not trigger an immediate flush by itself. - print("Hello\nWorld") - sleep(3) - print("Hi there!") + + from time import sleep + # This call performs one write operation, so the newline inside the string + # does not trigger an immediate flush by itself. + print("Hello\nWorld") + sleep(3) + print("Hi there!") .. versionchanged:: 3.3 Added the *flush* keyword argument.