Skip to content

Commit 5652bfe

Browse files
Refactor output buffering documentation for clarity
1 parent 9dac9fe commit 5652bfe

File tree

1 file changed

+15
-12
lines changed

1 file changed

+15
-12
lines changed

Doc/library/functions.rst

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1616,27 +1616,29 @@ are always available. They are listed here in alphabetical order.
16161616
Output buffering is usually determined by *file*.
16171617
However, if *flush* is true, the stream is forcibly flushed.
16181618

1619+
Output buffering is usually determined by *file*. However, if *flush* is true,
1620+
the stream is forcibly flushed.
1621+
16191622
.. note::
16201623

1621-
In Python, printing a string containing newline characters does not automatically flush stdout.
1622-
Python performs buffering at the write/operation level, so newlines inside a single write
1623-
do not necessarily trigger an immediate flush. The exact timing of output may vary depending
1624-
on the environment:
1624+
In Python, printing a string containing newline characters does not automatically
1625+
flush stdout. Python performs buffering at the write/operation level, so newlines
1626+
inside a single write do not necessarily trigger an immediate flush. The exact
1627+
timing of output may vary depending on the environment:
16251628

1626-
- When stdout is connected to a terminal (TTY), output is line-buffered and typically flushes
1627-
after the write completes.
1628-
- When stdout is redirected to a file or pipe, output may be fully buffered and not flush
1629-
until the buffer fills or flush is requested.
1629+
- When stdout is connected to a terminal (TTY), output is line-buffered and
1630+
typically flushes after the write completes.
1631+
- When stdout is redirected to a file or pipe, output may be fully buffered and
1632+
not flush until the buffer fills or flush is requested.
16301633

1631-
For guaranteed immediate output, use ``flush=True`` or call ``sys.stdout.flush()`` explicitly.
1632-
Running Python with the ``-u`` flag also forces unbuffered output, which may be useful in
1633-
scripts requiring immediate writes.
1634+
For guaranteed immediate output, use ``flush=True`` or call
1635+
``sys.stdout.flush()`` explicitly. Running Python with the ``-u`` flag also
1636+
forces unbuffered output, which may be useful in scripts requiring immediate writes.
16341637

16351638
Example:
16361639

16371640
.. code-block:: python
16381641
from time import sleep
1639-
16401642
# Whether the default end is a newline ('\\n') or any other character,
16411643
# Python performs a single write operation for the entire string.
16421644
# Therefore, newlines inside the string do not cause mid-string flushing.
@@ -1647,6 +1649,7 @@ are always available. They are listed here in alphabetical order.
16471649
.. versionchanged:: 3.3
16481650
Added the *flush* keyword argument.
16491651

1652+
16501653
.. class:: property(fget=None, fset=None, fdel=None, doc=None)
16511654

16521655
Return a property attribute.

0 commit comments

Comments
 (0)