classification
Title: Docs: Improve phrasing of flush argument for print()
Type: enhancement Stage:
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: aeros, docs@python, eric.araujo, ezio.melotti, mdk, willingc
Priority: normal Keywords:

Created on 2019-07-13 06:42 by aeros, last changed 2019-07-13 06:44 by aeros.

Messages (1)
msg347778 - (view) Author: Kyle Stanley (aeros) * (Python committer) Date: 2019-07-13 06:42
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.
History
Date User Action Args
2019-07-13 06:44:11aerossetversions: + Python 3.7, Python 3.8, Python 3.9
nosy: + docs@python

assignee: docs@python
components: + Documentation
type: enhancement
2019-07-13 06:42:51aeroscreate