Docs: Improve phrasing of flush argument for print()

[aeros]

BPO	37581
Nosy	@ezio-melotti, @merwok, @willingc, @JulienPalard, @aeros

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-07-13.06:42:51.715>
labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs']
title = 'Docs: Improve phrasing of flush argument for print()'
updated_at = <Date 2019-07-13.06:44:11.573>
user = 'https://github.com/aeros'

bugs.python.org fields:

activity = <Date 2019-07-13.06:44:11.573>
actor = 'aeros'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-07-13.06:42:51.715>
creator = 'aeros'
dependencies = []
files = []
hgrepos = []
issue_num = 37581
keywords = []
message_count = 1.0
messages = ['347778']
nosy_count = 6.0
nosy_names = ['ezio.melotti', 'eric.araujo', 'docs@python', 'willingc', 'mdk', 'aeros']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue37581'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

Linked PRs

• gh-81762: Clarify and simplify description of print's flush param #103264
• [3.11] gh-81762: Clarify and simplify description of print's flush param (GH-103264) #103273
• [3.10] gh-81762: Clarify and simplify description of print's flush param (GH-103264) #103274

[aeros]

Currently in the documentation for print() (https://docs.python.org/3/library/functions.html#print), the phrasing for the flush argument is:

Whether output is buffered is usually determined by file, but if the flush keyword argument is true, the stream is forcibly flushed.

For the sake of clarity, I would recommend changing it to one of the following:

1. Whether or not output is buffered is usually determined by *file*, but if the *flush* keyword argument is true, the stream is forcibly flushed.

2. Whether or not output is buffered is usually determined by *file*. However, if the *flush* keyword argument is true, the stream is forcibly flushed.

3. Output buffering is usually determined by *file*. However, if the *flush* keyword argument is true, the stream is forcibly flushed.

4. Output buffering is usually determined by *file*. However, if *flush* is true, the stream is forcibly flushed.

Each of the options are ordered in difference from the original, with one being the closest. The first couple options simply attempt improve the readability without changing the message itself significantly.

In the third option, "output is buffered" is replaced by "output buffering", which is a commonly used programming term for what is being described.

The fourth option removes "keyword argument" after *flush*, since it was not mentioned for *file* (which is also a keyword argument). Users can simply look at the function arguments to see that it's a keyword argument. Explicitly specifying this seems like it might be in partial violation of https://devguide.python.org/documenting/#economy-of-expression and https://devguide.python.org/documenting/#audience.

I'll be submitting a PR to attach to this issue soon. Let me know if this change is helpful, and if so, which option (or variation) provides the most concise and helpful explanation to users.

[iritkatriel]

CC @CAM-Gerlach.