gh-85679: Recommend encoding="utf-8" in tutorial
#91778
Conversation
methane
added
docs
methane
changed the title
encoding="utf-8" in tutorialencoding="utf-8" in tutorial
Doc/tutorial/inputoutput.rst
Outdated
| If *encoding* is not specified, the default is platform dependent | ||
| (see :func:`open`). | ||
| But passing ``encoding="utf-8"`` is highly recommended because | ||
| UTF-8 is the most commonly used encoding for now. |
There was a problem hiding this comment.
general rule: don't start a sentence with "and, but, so, or then" words. and try not to end with "for now".
Explicitly passing ``encoding='utf-8'`` is recommended if that is what you need as it is the most common text encoding in the world and leaves no room for doubt about your code's intent.
perhaps.
There was a problem hiding this comment.
This is tutorial and reader won't know what they need.
I want to teach that UTF-8 is the first choice.
How about this?
``encoding="utf-8"`` is recommended unless you need to use other encoding
because UTF-8 is the de-facto standard nowadays.
There was a problem hiding this comment.
How about:
Because UTF-8 is the modern de-facto standard, ``encoding="utf-8"`` is recommended unless you know that you need to use a different encoding.
Doc/tutorial/inputoutput.rst
Outdated
| (see :func:`open`). | ||
| But passing ``encoding="utf-8"`` is highly recommended because | ||
| UTF-8 is the most commonly used encoding for now. | ||
| ``'b'`` appended to the mode opens the file in :dfn:`binary mode`: |
There was a problem hiding this comment.
Appending a ``'b'`` to the mode opens the file in :dfn:`binary mode`. Binary mode data is read and written as ``bytes`` objects without use of a codec.
There was a problem hiding this comment.
I'd use "encoding" instead of "codec". I don't see "codec" used anywhere else in this file.
There was a problem hiding this comment.
(I didn't rewrite this paragraph at all. I just reflow it.)
How about this?
Appending a ``'b'`` to the mode opens the file in :dfn:`binary mode`.
Binary mode data is read and written as :class:`bytes` objects.
You can not specify *encoding* when opening file in binary mode.
Doc/tutorial/inputoutput.rst
Outdated
|
|
||
| x = json.load(f) | ||
|
|
||
| .. note:: | ||
| JSON files must be encoded in UTF-8. Use ``encoding="utf-8"`` when opening | ||
| JSON file as :term:`text file` for both of reading and writing. |
There was a problem hiding this comment.
as a :term:`text file`. add the 'a' and no the "for reading and writing" text can go.
Doc/tutorial/inputoutput.rst
Outdated
| @@ -279,11 +279,11 @@ Reading and Writing Files | |||
| object: file | |||
|
|
|||
| :func:`open` returns a :term:`file object`, and is most commonly used with | |||
| two arguments: ``open(filename, mode)``. | |||
| two or three arguments: ``open(filename, mode, encoding=None)`` | |||
There was a problem hiding this comment.
We like the encoding to be a keyword for readability so I'd word this similar to "two arguments, often with an encoding keyword when using a text mode" rather than including encoding in the number and mentioning two numbers. it feels more clear to me that way.
There was a problem hiding this comment.
At this point, we haven't described the "text mode" yet. It is described in below.
How about "two positional arguments and one keyword argument"?
Since binary file is rare than text file, we can focus on text file at this first open() example.
|
When you're done making the requested changes, leave the comment: |
|
I have made the requested changes; please review again |
|
Thanks for making the requested changes! @gpshead: please review the changes made to this pull request. |
methane
changed the title
encoding="utf-8" in tutorialencoding="utf-8" in tutorial
|
Thanks @methane for the PR 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10. |
bedevere-bot
removed
awaiting change review
needs backport to 3.10
|
GH-92133 is a backport of this pull request to the 3.10 branch. |
|
GH-92134 is a backport of this pull request to the 3.9 branch. |
) (cherry picked from commit 614420d) Co-authored-by: Inada Naoki <songofacandy@gmail.com>
(cherry picked from commit 614420d) Co-authored-by: Inada Naoki <songofacandy@gmail.com>
(cherry picked from commit 614420d) Co-authored-by: Inada Naoki <songofacandy@gmail.com>
) (cherry picked from commit 614420d) Co-authored-by: Inada Naoki <songofacandy@gmail.com>
Fixes #85679