Skip to content

Commit b910a6d

Browse files
Refactor output buffering documentation for clarity
1 parent 1926974 commit b910a6d

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
@@ -1607,27 +1607,29 @@ are always available. They are listed here in alphabetical order.
16071607
Output buffering is usually determined by *file*.
16081608
However, if *flush* is true, the stream is forcibly flushed.
16091609

1610+
Output buffering is usually determined by *file*. However, if *flush* is true,
1611+
the stream is forcibly flushed.
1612+
16101613
.. note::
16111614

1612-
In Python, printing a string containing newline characters does not automatically flush stdout.
1613-
Python performs buffering at the write/operation level, so newlines inside a single write
1614-
do not necessarily trigger an immediate flush. The exact timing of output may vary depending
1615-
on the environment:
1615+
In Python, printing a string containing newline characters does not automatically
1616+
flush stdout. Python performs buffering at the write/operation level, so newlines
1617+
inside a single write do not necessarily trigger an immediate flush. The exact
1618+
timing of output may vary depending on the environment:
16161619

1617-
- When stdout is connected to a terminal (TTY), output is line-buffered and typically flushes
1618-
after the write completes.
1619-
- When stdout is redirected to a file or pipe, output may be fully buffered and not flush
1620-
until the buffer fills or flush is requested.
1620+
- When stdout is connected to a terminal (TTY), output is line-buffered and
1621+
typically flushes after the write completes.
1622+
- When stdout is redirected to a file or pipe, output may be fully buffered and
1623+
not flush until the buffer fills or flush is requested.
16211624

1622-
For guaranteed immediate output, use ``flush=True`` or call ``sys.stdout.flush()`` explicitly.
1623-
Running Python with the ``-u`` flag also forces unbuffered output, which may be useful in
1624-
scripts requiring immediate writes.
1625+
For guaranteed immediate output, use ``flush=True`` or call
1626+
``sys.stdout.flush()`` explicitly. Running Python with the ``-u`` flag also
1627+
forces unbuffered output, which may be useful in scripts requiring immediate writes.
16251628

16261629
Example:
16271630

16281631
.. code-block:: python
16291632
from time import sleep
1630-
16311633
# Whether the default end is a newline ('\\n') or any other character,
16321634
# Python performs a single write operation for the entire string.
16331635
# 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.
16381640
.. versionchanged:: 3.3
16391641
Added the *flush* keyword argument.
16401642

1643+
16411644
.. class:: property(fget=None, fset=None, fdel=None, doc=None)
16421645

16431646
Return a property attribute.

0 commit comments

Comments
 (0)