Author aeros
Recipients aeros, eric.araujo, ezio.melotti, mdk, willingc
Date 2019-07-13.06:42:51
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1563000171.75.0.259144303863.issue37581@roundup.psfhosted.org>
In-reply-to
Content
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:42:51aerossetrecipients: + aeros, ezio.melotti, eric.araujo, willingc, mdk
2019-07-13 06:42:51aerossetmessageid: <1563000171.75.0.259144303863.issue37581@roundup.psfhosted.org>
2019-07-13 06:42:51aeroslinkissue37581 messages
2019-07-13 06:42:51aeroscreate