I'm working on a PR now. It seems there is little support for keeping the python2 content in the docs, so I'm re-writing it as though it was never there. If someone wants to add a note about Python 2, of course that can be added later.
Note that "moving the Python 2 content to a section at the end" is not all that straightforward, as it is pretty mixed in with the text at this point.
"Code in the core Python distribution should always use UTF-8"
and then:
"In the standard library, non-default encodings should be used only for
test purposes or when a comment or docstring needs to mention an author
name that contains non-ASCII characters ..."
I *think* that's a remnant of the Py2 ASCII encoding days -- but I wanted to make sure, a bit later on, it says:
"The following policy is prescribed for the
standard library ... In addition, string literals and comments must also be in ASCII."
Is that still correct for string literals and comments? And what about docstrings?
It seems to me that if we really are utf-8, then there is no need for those "textual" elements to be ASCII. e.g they can still contain non-ascii characters, and escaping those makes things less readable, not more.
So I think that section should now read:
"""
Source File Encoding
--------------------
Code in the core Python distribution should always use UTF-8, and should not have an encoding declaration.
In the standard library, non-UTF-8 encodings should be used only for
test purposes.
The following policy is prescribed for the standard library (see PEP
3131): All identifiers in the Python standard library MUST use
ASCII-only identifiers, and SHOULD use English words wherever feasible
(in many cases, abbreviations and technical terms are used which aren't
English). In comment and docstrings, authors whose names tht are not
based on the Latin alphabet (latin-1, ISO/IEC 8859-1 character set)
MUST provide a transliteration of their names in this character set.
Open source projects with a global audience are encouraged to adopt a
similar policy.
"""
But maybe we do want to keep comments, docstrings and literals as ASCII with escapes?