Agreed. Here is a patch I will commit if you approve.  I deleted 'convenience function' as distracting, labelled *file* a *text* stream in the first line, and added the rest of the comment after the current 'file' sentence, making separate 'file' and 'flush' paragraphs.

I unstarred 'file' in the addition to try to make it slightly clearer that the comment applies to the default sys.stdout, when rebound to a binary mode file, as well as to explicit *file=* arguments.