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: ```python assignee = None closed_at = None created_at = labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs'] title = 'Docs: Improve phrasing of flush argument for print()' updated_at = user = 'https://github.com/aeros' ``` bugs.python.org fields: ```python activity = actor = 'aeros' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = 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-103264
• gh-103273
• gh-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.

[CAM-Gerlach]

Thanks for the ping, @iritkatriel .

IMO, I prefer the fourth option. "Output buffering" is a more conventional term, and results in a more concise and easier to read first sentence. I also agree it's inconsistent that file is not referred to as a keyword argument here or on any other reference (nor are any of the other args), but flush is, which implies that there is something different about it (when of course there's not). Furthermore, it likewise makes the sentence shorter and easier to read.

Therefore, I've submitted a PR, #103264, to implement that.