Hi everyone,
I would like to discuss a small but potentially confusing difference between C stdio and Python’s stdout behavior that may benefit from clearer documentation.
In C, when stdout is line-buffered (for example, when connected to a terminal), encountering a ‘\n’ within a string causes the output buffer to flush immediately up to that point. As a result, developers often expect incremental flushing behavior when newline characters appear inside a single output call.
In CPython, however, a single print() call that contains embedded ‘\n’ characters produces multiple lines of output, but the flush occurs only once at the end of the call (unless flush=True is explicitly specified). The intermediate newline characters split the output into lines, but they do not guarantee intermediate flushes.
This difference can easily confuse users—especially those coming from C—when demonstrating buffering behavior, writing CLI tools, or reasoning about output timing.
To address this, I opened a documentation issue and a corresponding PR proposing a clarification that:
- Newline characters inside a single print() call do not necessarily trigger a flush
- Explicit flushing should be done using flush=True
- Python’s stdout buffering behavior differs from C’s line-buffered stdio
- The behavior is implementation-dependent and should not be relied upon for precise timing
Issue: Documentation clarity request: stdout flush behavior with mid-string newline characters · Issue #141395 · python/cpython · GitHub
PR: gh-141395: Clarify stdout flush behavior for newline characters in print() by Vemulakonda559 · Pull Request #142094 · python/cpython · GitHub
I would appreciate feedback on whether this distinction should be documented more explicitly, and whether the proposed wording aligns with Python’s documentation standards.
Thank you for your time and guidance.