Update docs now UTF-8 is default (PEP 686)

Author: hugovk

Doc/library/csv.rst

@@ -673,17 +673,16 @@ The corresponding simplest possible writing example is::
        writer.writerows(someiterable)
 
 Since :func:`open` is used to open a CSV file for reading, the file
-will by default be decoded into unicode using the system default
-encoding (see :func:`locale.getencoding`).  To decode a file
+will by default be decoded into Unicode using UTF-8.  To decode a file
 using a different encoding, use the ``encoding`` argument of open::
 
    import csv
-   with open('some.csv', newline='', encoding='utf-8') as f:
+   with open('some.csv', newline='', encoding='latin-1') as f:
        reader = csv.reader(f)
        for row in reader:
            print(row)
 
-The same applies to writing in something other than the system default
+The same applies to writing in something other than the default
 encoding: specify the encoding argument when opening the output file.
 
 Registering a new dialect::

Doc/library/functions.rst

@@ -1459,7 +1459,8 @@ are always available.  They are listed here in alphabetical order.
    already exists), ``'x'`` for exclusive creation, and ``'a'`` for appending
    (which on *some* Unix systems, means that *all* writes append to the end of
    the file regardless of the current seek position).  In text mode, if
-   *encoding* is not specified the encoding used is platform-dependent:
+   *encoding* is not specified, UTF-8 is used by default; if
+   :ref:`Python UTF-8 Mode <utf8-mode>` is disabled,
    :func:`locale.getencoding` is called to get the current locale encoding.
    (For reading and writing raw bytes use binary mode and leave
    *encoding* unspecified.)  The available modes are:
@@ -1490,7 +1491,7 @@ are always available.  They are listed here in alphabetical order.
    argument) return contents as :class:`bytes` objects without any decoding.  In
    text mode (the default, or when ``'t'`` is included in the *mode* argument),
    the contents of the file are returned as :class:`str`, the bytes having been
-   first decoded using a platform-dependent encoding or using the specified
+   first decoded using the default encoding or using the specified
    *encoding* if given.
 
    .. note::
@@ -1519,9 +1520,11 @@ are always available.  They are listed here in alphabetical order.
      described above for binary files.
 
    *encoding* is the name of the encoding used to decode or encode the file.
-   This should only be used in text mode.  The default encoding is platform
-   dependent (whatever :func:`locale.getencoding` returns), but any
-   :term:`text encoding` supported by Python can be used.
+   This should only be used in text mode.  The default encoding is UTF-8;
+   if :ref:`Python UTF-8 Mode <utf8-mode>` is disabled, the default is
+   platform-dependent (whatever :func:`locale.getencoding` returns).
+   Any :term:`text encoding` supported by Python can be used, and
+   ``encoding="locale"`` specifies the current locale encoding explicitly.
    See the :mod:`codecs` module for the list of supported encodings.
 
    *errors* is an optional string that specifies how encoding and decoding
@@ -1638,6 +1641,10 @@ are always available.  They are listed here in alphabetical order.
    .. versionchanged:: 3.11
       The ``'U'`` mode has been removed.
 
+   .. versionchanged:: 3.15
+      UTF-8 is now the default encoding, instead of the
+      platform-dependent locale encoding (:pep:`686`).
+
 .. function:: ord(character, /)
 
    Return the ordinal value of a character.

Doc/library/io.rst

@@ -118,31 +118,18 @@ The raw stream API is described in detail in the docs of :class:`RawIOBase`.
 Text Encoding
 -------------
 
-The default encoding of :class:`TextIOWrapper` and :func:`open` is
-locale-specific (:func:`locale.getencoding`).
-
-However, many developers forget to specify the encoding when opening text files
-encoded in UTF-8 (e.g. JSON, TOML, Markdown, etc...) since most Unix
-platforms use UTF-8 locale by default. This causes bugs because the locale
-encoding is not UTF-8 for most Windows users. For example::
-
-   # May not work on Windows when non-ASCII characters in the file.
-   with open("README.md") as f:
-       long_description = f.read()
-
-Accordingly, it is highly recommended that you specify the encoding
-explicitly when opening text files. If you want to use UTF-8, pass
-``encoding="utf-8"``. To use the current locale encoding,
-``encoding="locale"`` is supported since Python 3.10.
+The default encoding of :class:`TextIOWrapper` and :func:`open` is UTF-8.
+If :ref:`Python UTF-8 Mode <utf8-mode>` is disabled, the default encoding
+is locale-specific (:func:`locale.getencoding`).
 
 .. seealso::
 
    :ref:`utf8-mode`
-      Python UTF-8 Mode can be used to change the default encoding to
-      UTF-8 from locale-specific encoding.
+      Python UTF-8 Mode ignores the locale encoding and forces the use
+      of UTF-8.
 
    :pep:`686`
-      Python 3.15 will make :ref:`utf8-mode` default.
+      Python 3.15 made :ref:`utf8-mode` the default.
 
 .. _io-encoding-warning:
 
@@ -152,7 +139,7 @@ Opt-in EncodingWarning
 .. versionadded:: 3.10
    See :pep:`597` for more details.
 
-To find where the default locale encoding is used, you can enable
+To find where the default encoding is used, you can enable
 the :option:`-X warn_default_encoding <-X>` command line option or set the
 :envvar:`PYTHONWARNDEFAULTENCODING` environment variable, which will
 emit an :exc:`EncodingWarning` when the default encoding is used.
@@ -1004,8 +991,8 @@ Text I/O
    :class:`TextIOBase`.
 
    *encoding* gives the name of the encoding that the stream will be decoded or
-   encoded with.  In :ref:`UTF-8 Mode <utf8-mode>`, this defaults to UTF-8.
-   Otherwise, it defaults to :func:`locale.getencoding`.
+   encoded with.  This defaults to UTF-8; if :ref:`UTF-8 Mode <utf8-mode>` is
+   disabled, it defaults to :func:`locale.getencoding`.
    ``encoding="locale"`` can be used to specify the current locale's encoding
    explicitly. See :ref:`io-text-encoding` for more information.
 

Doc/tutorial/inputoutput.rst

@@ -311,12 +311,11 @@ Reading and Writing Files
    pair: object; file
 
 :func:`open` returns a :term:`file object`, and is most commonly used with
-two positional arguments and one keyword argument:
-``open(filename, mode, encoding=None)``
+two positional arguments: ``open(filename, mode)``
 
 ::
 
-   >>> f = open('workfile', 'w', encoding="utf-8")
+   >>> f = open('workfile', 'w')
 
 .. XXX str(f) is <io.TextIOWrapper object at 0x82e8dc4>
 
@@ -334,10 +333,7 @@ omitted.
 
 Normally, files are opened in :dfn:`text mode`, that means, you read and write
 strings from and to the file, which are encoded in a specific *encoding*.
-If *encoding* is not specified, the default is platform dependent
-(see :func:`open`).
-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.
+If *encoding* is not specified, the default is UTF-8 (see :func:`open`).
 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.
@@ -356,7 +352,7 @@ after its suite finishes, even if an exception is raised at some
 point.  Using :keyword:`!with` is also much shorter than writing
 equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
 
-    >>> with open('workfile', encoding="utf-8") as f:
+    >>> with open('workfile') as f:
     ...     read_data = f.read()
 
     >>> # We can check that the file has been automatically closed.
@@ -532,8 +528,8 @@ To decode the object again, if ``f`` is a :term:`binary file` or
    x = json.load(f)
 
 .. note::
-   JSON files must be encoded in UTF-8. Use ``encoding="utf-8"`` when opening
-   JSON file as a :term:`text file` for both of reading and writing.
+   JSON files must be encoded in UTF-8, the default encoding for
+   :term:`text files <text file>`.
 
 This simple serialization technique can handle lists and dictionaries, but
 serializing arbitrary class instances in JSON requires a bit of extra effort.

Doc/using/windows.rst

@@ -1345,14 +1345,15 @@ UTF-8 mode
    Python UTF-8 mode is now enabled by default (:pep:`686`).
 
 Windows still uses legacy encodings for the system encoding (the ANSI Code
-Page).  Python uses it for the default encoding of text files (e.g.
+Page).  When the :ref:`Python UTF-8 Mode <utf8-mode>` is disabled, Python
+uses it for the default encoding of text files (for example,
 :func:`locale.getencoding`).
 
 This may cause issues because UTF-8 is widely used on the internet
 and most Unix systems, including WSL (Windows Subsystem for Linux).
 
-The :ref:`Python UTF-8 Mode <utf8-mode>`, enabled by default, can help by
-changing the default text encoding to UTF-8.
+The :ref:`Python UTF-8 Mode <utf8-mode>`, enabled by default, ignores the
+system encoding and uses UTF-8 as the default text encoding.
 When the :ref:`UTF-8 mode <utf8-mode>` is enabled, you can still use the
 system encoding (the ANSI Code Page) via the "mbcs" codec.