Please don't use the term "file handle".

Thanks for the comment @methane ! I've changed the wording from "file handle" to "file object" (the same phrasing in https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files ).

Happy to change it again if you will give me more context for your comment.

I am not sure See :ref:tut-files for file object details. is good reference. open document has this paragraph.

The type of file object returned by the open() function depends on the mode. When open() is used to open a file in a text mode ('w', 'r', 'wt', 'rt', etc.), it returns a subclass of io.TextIOBase (specifically io.TextIOWrapper). When used to open a file in a binary mode with buffering, the returned class is a subclass of io.BufferedIOBase. The exact class varies: in read binary mode, it returns an io.BufferedReader; in write binary and append binary modes, it returns an io.BufferedWriter, and in read/write mode, it returns an io.BufferedRandom. When buffering is disabled, the raw stream, a subclass of io.RawIOBase, io.FileIO, is returned.

I think tut-files is not for "file object details", because io module document is "file object details".

Could you suggest better phrasing for "tutorial"?

When I first read the open() docs, i didn't know how or when the file would be closed, I just knew people told me to use with. The point of this change is to bring reference of the way file objects are handled closer to the open() docs for new users.

Maybe I could change the sentence to:

See :ref:tut-files for more examples of how to use this function.

Once built, this will show to the user:

See Reading and Writing Files for more examples of how to use this function.

Since the Reading and Writing Files tutorial page contains documentation on how & when to use the with keyword with open, I felt it was the best page to link to in order to provide clarity. This page also links back to the open() docs, so they'll be linking to each other.

Do you prefer this new phrasing?

Do you prefer this new phrasing?

I prefere new phrasing to old one.

Other option is "for tutorial", because people may expect "more examples for more complex use cases" when they see "more examples".
But I am not sure "for tutoraial" is natural English.

@methane , I've changed my PR to the "more examples" option. I think it's a tad more clear and you seem to like it too. Please merge if you have no further concerns.

Thanks @bbkane for the PR, and @methane for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8, 3.9.
🐍🍒⛏🤖

GH-21780 is a backport of this pull request to the 3.9 branch.

GH-21781 is a backport of this pull request to the 3.8 branch.