Documentation clarity request: stdout flush behavior with mid-string newline characters

[Vemulakonda559]

Python’s documentation for print() and stdout buffering does not clearly specify the behavior when newline (\n) characters occur inside a single print() call. Users coming from C (where line-buffered stdio flushes on newline) may expect a flush to occur at each newline within the printed string. However, Python does not guarantee this behavior.

This gap can lead to confusion, particularly when demonstrating buffering, interactive console output, or progress indicators.

Example demonstrating the confusion

from time import sleep

print("Hello\nWorld", end='')
sleep(3)
print("Hi there!")

Observed behavior
Both "Hello" and "World" appear immediately, before the sleep. "Hi there!" appears after 3 seconds.

Expected behavior (based on C-style line buffering)
"Hello" should appear first; "WorldHi there!" should appear after the 3-second delay.

Reason for confusion
In C (stdio) with line-buffered stdout:

printf("Hello\nWorld");
sleep(3);
printf("Hi there!");

The output is:
Hello
(World and Hi there! appear after sleep)

This is because newline triggers a flush automatically, even if it is mid-string.

Python does not document whether a newline within the printed string causes a flush.
The current behavior is implementation-dependent (TextIOWrapper buffering), not documented.

Proposed improvement
Add a sentence to the documentation for print() or for I/O buffering clarifying:

• Newline characters inside a single print() call do not necessarily trigger a flush
• flush=True explicitly forces flushing
• Python’s stdout buffering differs from C’s line-buffered stdout behavior
• The behavior is implementation-dependent and should not be relied upon for precise output timing

Why this matters

• Helps developers writing CLI tools
• Avoids confusing differences between Python and C
• Makes buffering expectations clearer
• Educates learners about stdout behavior

Suggested wording (for docs)
In Python, printing a string containing newline characters does not cause stdout to flush automatically. The flush behavior depends on the stream’s buffering mode and flush=True explicitly forces a flush. Unlike C’s stdio line buffering, Python does not guarantee that newline characters inside a single write operation will trigger an immediate flush.

Conclusion
This is not a bug, but a documentation clarity issue.
Clarifying this behavior will prevent misunderstandings and align expectations for users familiar with C-style buffering.

Linked PRs

• gh-141395: Clarify stdout flush behavior for newline characters in print() #142094

[Vemulakonda559]

Python implements operation-level line buffering, while C implements character-level line buffering.

• C behavior: printf("Hello\nWorld") flushes at the \n position → "Hello" appears first
• Python behavior: print("Hello\nWorld", end='') flushes the entire operation → both "Hello" and "World" appear
  together

Python implements operation-level line buffering, while C implements character-level line buffering.

Thank you for this clarification — that makes the behavior much clearer.

To help future learners avoid confusion (especially those coming from C), I would like to add a small note to the documentation explaining that newline characters inside a single print() call do not guarantee an immediate flush in Python.

Here is a proposed wording for the docs (feel free to edit):

Suggested documentation note:
“In Python, printing a string containing newline characters does not cause stdout to flush automatically. Python performs buffering at the write/operation level, so newlines inside a single write do not necessarily trigger an immediate flush. If flushing at a specific point is required, use flush=True or call sys.stdout.flush() explicitly.”

If this looks acceptable, I can open a small documentation PR adding this note to the print() documentation and the I/O buffering section.

[mohsinm-dev]

I might be completely wrong here, but I tried to explore how Python’s stdout buffering actually behaves.

• On a terminal (TTY), sys.stdout is line‑buffered. If a single write contains a newline, Python does an implied flush after that
  write returns. So:

  • print("Hello\nWorld", end='') writes the whole string once, then flushes. Both lines appear immediately.
  • Important: the flush is not “mid‑string at the newline”; it happens after the write call finishes.

• When stdout is redirected (pipe/file), line buffering is usually off. A newline by itself won’t flush; data is kept until the
  buffer fills or you flush manually. To flush immediately, you can:

  • print(..., flush=True)
  • sys.stdout.reconfigure(line_buffering=True)
  • run with python -u (unbuffered/write‑through)

• Compared to some C stdio line buffering, C may flush exactly at the newline boundary; Python flushes after the write if a newline was present. That’s why a single print containing multiple lines appears as one atomic flush.

Key point: newlines inside one print() do not cause mid‑string flushing. Any automatic flush (if line‑buffered) happens after the
call, typically only on a TTY.

[Vemulakonda559]

I might be completely wrong here, but I tried to explore how Python’s stdout buffering actually behaves.

• On a terminal (TTY), sys.stdout is line‑buffered. If a single write contains a newline, Python does an implied flush after that
  write returns. So:

  • print("Hello\nWorld", end='') writes the whole string once, then flushes. Both lines appear immediately.
  • Important: the flush is not “mid‑string at the newline”; it happens after the write call finishes.

• When stdout is redirected (pipe/file), line buffering is usually off. A newline by itself won’t flush; data is kept until the
  buffer fills or you flush manually. To flush immediately, you can:

  • print(..., flush=True)
  • sys.stdout.reconfigure(line_buffering=True)
  • run with python -u (unbuffered/write‑through)

• Compared to some C stdio line buffering, C may flush exactly at the newline boundary; Python flushes after the write if a newline was present. That’s why a single print containing multiple lines appears as one atomic flush.

Key point: newlines inside one print() do not cause mid‑string flushing. Any automatic flush (if line‑buffered) happens after the call, typically only on a TTY.

Thank you for the clarification.
Based on this understanding, I would like to prepare a small documentation PR to add a note explaining that newline characters inside a single print() call do not guarantee an immediate flush.
If you have any concerns or suggestions before I submit the PR, please let me know.

[StanFromIreland]

I think the docs are pretty clear:

flush() is implied when a call to write contains a newline character or a carriage return.

In your example, it does contain \n.

[Vemulakonda559]

I think the docs are pretty clear:

flush() is implied when a call to write contains a newline character or a carriage return.

In your example, it does contain \n.

Thank you for the feedback!

You’re correct that the current documentation states:

“flush() is implied when a call to write contains a newline character or a carriage return.”

It mentions that a \n or \r triggers a flush, but it does not specify which part of the string is flushed.

This can make readers think:

“Python flushes up to the first newline” (like C line-buffering)

Or “Python flushes the entire string containing the newline”

However, in other common scenarios — such as when stdout is redirected to a file or pipe — the behavior is different: output may be fully buffered and newlines inside a single print() call do not trigger an immediate flush.

The intention of this PR is to clarify this distinction and avoid confusion, especially for:

Users coming from C, who expect flush at every newline

Scripts that rely on immediate output for progress indicators or CLI feedback

The added note also explains how to explicitly flush using flush=True or sys.stdout.flush(), and mentions python -u for unbuffered output.

This should help make the documentation accurate and clear for all environments, not just TTY.