gh-109975: Copyedit "What's New in Python 3.13" (#117902)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

1 files changed, 125 insertions, 115 deletions

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index e8efa99..4d6ce27 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -82,7 +82,7 @@ Important deprecations, removals or restrictions:
 
 Interpreter improvements:
 
-* A basic :ref:`JIT compiler <whatsnew313-jit-compiler>` was added.
+* :pep:`744`: A basic :ref:`JIT compiler <whatsnew313-jit-compiler>` was added.
   It is currently disabled by default (though we may turn it on later).
   Performance improvements are modest -- we expect to be improving this
   over the next few releases.
@@ -212,9 +212,8 @@ Other Language Changes
   (Contributed by William Woodruff in :gh:`112389`.)
 
 * The :class:`configparser.ConfigParser` now accepts unnamed sections before named
-   ones if configured to do so.
-
-   (Contributed by Pedro Sousa Lacerda in :gh:`66449`)
+  ones if configured to do so.
+  (Contributed by Pedro Sousa Lacerda in :gh:`66449`.)
 
 
 New Modules
@@ -233,7 +232,7 @@ argparse
   :meth:`~argparse.ArgumentParser.add_argument` and :meth:`!add_parser`
   which allows to deprecate command-line options, positional arguments and
   subcommands.
-  (Contributed by Serhiy Storchaka in :gh:`83648`).
+  (Contributed by Serhiy Storchaka in :gh:`83648`.)
 
 array
 -----
@@ -263,9 +262,9 @@ ast
   argument that does not map to a field on the AST node is now deprecated,
   and will raise an exception in Python 3.15.
 
-* :func:`ast.parse` now accepts an optional argument ``optimize``
+* :func:`ast.parse` now accepts an optional argument *optimize*
   which is passed on to the :func:`compile` built-in. This makes it
-  possible to obtain an optimized ``AST``.
+  possible to obtain an optimized AST.
   (Contributed by Irit Katriel in :gh:`108113`.)
 
 asyncio
@@ -332,7 +331,7 @@ base64
 ------
 
 * Add :func:`base64.z85encode` and :func:`base64.z85decode` functions which allow encoding
-  and decoding z85 data.
+  and decoding Z85 data.
   See `Z85  specification <https://rfc.zeromq.org/spec/32/>`_ for more information.
   (Contributed by Matan Perelman in :gh:`75299`.)
 
@@ -355,6 +354,9 @@ dbm
   from the database.
   (Contributed by Donghee Na in :gh:`107122`.)
 
+* Add new :mod:`dbm.sqlite3` backend, and make it the default :mod:`!dbm` backend.
+  (Contributed by Raymond Hettinger and Erlend E. Aasland in :gh:`100414`.)
+
 dis
 ---
 
@@ -364,16 +366,6 @@ dis
   the ``show_offsets`` parameter.
   (Contributed by Irit Katriel in :gh:`112137`.)
 
-dbm
----
-
-* Add :meth:`dbm.gnu.gdbm.clear` and :meth:`dbm.ndbm.ndbm.clear`  methods that remove all items
-  from the database.
-  (Contributed by Donghee Na in :gh:`107122`.)
-
-* Add new :mod:`dbm.sqlite3` backend, and make it the default :mod:`!dbm` backend.
-  (Contributed by Raymond Hettinger and Erlend E. Aasland in :gh:`100414`.)
-
 doctest
 -------
 
@@ -390,7 +382,7 @@ email
   encountered instead of potentially inaccurate values. Add optional *strict*
   parameter to these two functions: use ``strict=False`` to get the old
   behavior, accept malformed inputs.
-  ``getattr(email.utils, 'supports_strict_parsing', False)`` can be use to
+  ``getattr(email.utils, 'supports_strict_parsing', False)`` can be used to
   check if the *strict* parameter is available.
   (Contributed by Thomas Dwyer and Victor Stinner for :gh:`102988` to improve
   the CVE-2023-27043 fix.)
@@ -409,21 +401,22 @@ gc
 * The cyclic garbage collector is now incremental, which changes the meanings
   of the results of :meth:`gc.get_threshold` and :meth:`gc.set_threshold` as
   well as :meth:`gc.get_count` and :meth:`gc.get_stats`.
-* :meth:`gc.get_threshold` returns a three-tuple for backwards compatibility,
-  the first value is the threshold for young collections, as before, the second
-  value determines the rate at which the old collection is scanned; the
-  default is 10 and higher values mean that the old collection is scanned more slowly.
-  The third value is meangless and is always zero.
-* :meth:`gc.set_threshold` ignores any items after the second.
-* :meth:`gc.get_count` and :meth:`gc.get_stats`.
-  These functions return the same format of results as before.
-  The only difference is that instead of the results refering to
-  the young, aging and old generations, the results refer to the
-  young generation and the aging and collecting spaces of the old generation.
-
-In summary, code that attempted to manipulate the behavior of the cycle GC may
-not work exactly as intended, but it is very unlikely to harmful.
-All other code will work just fine.
+
+  * :meth:`gc.get_threshold` returns a three-item tuple for backwards compatibility.
+    The first value is the threshold for young collections, as before; the second
+    value determines the rate at which the old collection is scanned (the
+    default is 10, and higher values mean that the old collection is scanned more slowly).
+    The third value is meaningless and is always zero.
+  * :meth:`gc.set_threshold` ignores any items after the second.
+  * :meth:`gc.get_count` and :meth:`gc.get_stats`
+    return the same format of results as before.
+    The only difference is that instead of the results referring to
+    the young, aging and old generations, the results refer to the
+    young generation and the aging and collecting spaces of the old generation.
+
+  In summary, code that attempted to manipulate the behavior of the cycle GC may
+  not work exactly as intended, but it is very unlikely to be harmful.
+  All other code will work just fine.
 
 glob
 ----
@@ -432,46 +425,49 @@ glob
   shell-style wildcards to a regular expression.
   (Contributed by Barney Gale in :gh:`72904`.)
 
-io
---
-
-The :class:`io.IOBase` finalizer now logs the ``close()`` method errors with
-:data:`sys.unraisablehook`. Previously, errors were ignored silently by default,
-and only logged in :ref:`Python Development Mode <devmode>` or on :ref:`Python
-built on debug mode <debug-build>`.
-(Contributed by Victor Stinner in :gh:`62948`.)
-
 importlib
 ---------
 
-Previously deprecated :mod:`importlib.resources` functions are un-deprecated:
+* Previously deprecated :mod:`importlib.resources` functions are un-deprecated:
 
-  * :func:`~importlib.resources.is_resource()`
-  * :func:`~importlib.resources.open_binary()`
-  * :func:`~importlib.resources.open_text()`
-  * :func:`~importlib.resources.path()`
-  * :func:`~importlib.resources.read_binary()`
-  * :func:`~importlib.resources.read_text()`
+    * :func:`~importlib.resources.is_resource()`
+    * :func:`~importlib.resources.open_binary()`
+    * :func:`~importlib.resources.open_text()`
+    * :func:`~importlib.resources.path()`
+    * :func:`~importlib.resources.read_binary()`
+    * :func:`~importlib.resources.read_text()`
 
-All now allow for a directory (or tree) of resources, using multiple positional
-arguments.
+  All now allow for a directory (or tree) of resources, using multiple positional
+  arguments.
 
-For text-reading functions, the *encoding* and *errors* must now be given as
-keyword arguments.
+  For text-reading functions, the *encoding* and *errors* must now be given as
+  keyword arguments.
 
-The :func:`~importlib.resources.contents()` remains deprecated in favor of
-the full-featured :class:`~importlib.resources.abc.Traversable` API.
-However, there is now no plan to remove it.
+  The :func:`~importlib.resources.contents()` remains deprecated in favor of
+  the full-featured :class:`~importlib.resources.abc.Traversable` API.
+  However, there is now no plan to remove it.
 
-(Contributed by Petr Viktorin in :gh:`106532`.)
+  (Contributed by Petr Viktorin in :gh:`106532`.)
+
+io
+--
+
+* The :class:`io.IOBase` finalizer now logs the ``close()`` method errors with
+  :data:`sys.unraisablehook`. Previously, errors were ignored silently by default,
+  and only logged in :ref:`Python Development Mode <devmode>` or on :ref:`Python
+  built on debug mode <debug-build>`.
+  (Contributed by Victor Stinner in :gh:`62948`.)
 
 ipaddress
 ---------
 
 * Add the :attr:`ipaddress.IPv4Address.ipv6_mapped` property, which returns the IPv4-mapped IPv6 address.
   (Contributed by Charles Machalow in :gh:`109466`.)
-* Fix ``is_global`` and ``is_private`` behavior in ``IPv4Address``, ``IPv6Address``, ``IPv4Network``
-  and ``IPv6Network``.
+* Fix ``is_global`` and ``is_private`` behavior in
+  :class:`~ipaddress.IPv4Address`,
+  :class:`~ipaddress.IPv6Address`,
+  :class:`~ipaddress.IPv4Network` and
+  :class:`~ipaddress.IPv6Network`.
 
 itertools
 ---------
@@ -492,12 +488,12 @@ marshal
 math
 ----
 
-A new function :func:`~math.fma` for fused multiply-add operations has been
-added. This function computes ``x * y + z`` with only a single round, and so
-avoids any intermediate loss of precision. It wraps the ``fma()`` function
-provided by C99, and follows the specification of the IEEE 754
-"fusedMultiplyAdd" operation for special cases.
-(Contributed by Mark Dickinson and Victor Stinner in :gh:`73468`.)
+* A new function :func:`~math.fma` for fused multiply-add operations has been
+  added. This function computes ``x * y + z`` with only a single round, and so
+  avoids any intermediate loss of precision. It wraps the ``fma()`` function
+  provided by C99, and follows the specification of the IEEE 754
+  "fusedMultiplyAdd" operation for special cases.
+  (Contributed by Mark Dickinson and Victor Stinner in :gh:`73468`.)
 
 mmap
 ----
@@ -593,18 +589,18 @@ pathlib
 
 * Add *recurse_symlinks* keyword-only argument to :meth:`pathlib.Path.glob`
   and :meth:`~pathlib.Path.rglob`.
-  (Contributed by Barney Gale in :gh:`77609`).
+  (Contributed by Barney Gale in :gh:`77609`.)
 
 * Add *follow_symlinks* keyword-only argument to :meth:`~pathlib.Path.is_file`,
   :meth:`~pathlib.Path.is_dir`, :meth:`~pathlib.Path.owner`,
   :meth:`~pathlib.Path.group`.
   (Contributed by Barney Gale in :gh:`105793`, and Kamil Turek in
-  :gh:`107962`).
+  :gh:`107962`.)
 
 * Return files and directories from :meth:`pathlib.Path.glob` and
   :meth:`~pathlib.Path.rglob` when given a pattern that ends with "``**``". In
   earlier versions, only directories were returned.
-  (Contributed by Barney Gale in :gh:`70303`).
+  (Contributed by Barney Gale in :gh:`70303`.)
 
 pdb
 ---
@@ -653,6 +649,8 @@ statistics
   from a fixed number of discrete samples.
   (Contributed by Raymond Hettinger in :gh:`115863`.)
 
+.. _whatsnew313-subprocess:
+
 subprocess
 ----------
 
@@ -685,7 +683,7 @@ time
 
 * On Windows, :func:`time.time()` now uses the
   ``GetSystemTimePreciseAsFileTime()`` clock to have a resolution better
-  than 1 us, instead of the ``GetSystemTimeAsFileTime()`` clock which has a
+  than 1 μs, instead of the ``GetSystemTimeAsFileTime()`` clock which has a
   resolution of 15.6 ms.
   (Contributed by Victor Stinner in :gh:`63207`.)
 
@@ -782,6 +780,7 @@ zipimport
 * Gains support for ZIP64 format files.  Everybody loves huge code right?
   (Contributed by Tim Hatch in :gh:`94146`.)
 
+.. Add improved modules above alphabetically, not here at the end.
 
 Optimizations
 =============
@@ -792,7 +791,8 @@ Optimizations
 * The :mod:`subprocess` module uses :func:`os.posix_spawn` in more situations
   including the default where ``close_fds=True`` on many modern platforms.  This
   should provide a noteworthy performance increase launching processes on
-  FreeBSD and Solaris.  See the ``subprocess`` section above for details.
+  FreeBSD and Solaris.  See the :ref:`subprocess <whatsnew313-subprocess>`
+  section above for details.
   (Contributed by Jakub Kulik in :gh:`113117`.)
 
 .. _whatsnew313-jit-compiler:
@@ -831,6 +831,8 @@ The internal architecture is roughly as follows.
   *copy-and-patch*. It has no runtime dependencies, but there is a new
   build-time dependency on LLVM.
 
+See :pep:`744` for more details.
+
 (JIT by Brandt Bucher, inspired by a paper by Haoran Xu and Fredrik Kjolstad.
 Tier 2 IR by Mark Shannon and Guido van Rossum.
 Tier 2 optimizer by Ken Jin.)
@@ -844,7 +846,7 @@ Deprecated
   emits :exc:`DeprecationWarning` since 3.13
   and will be removed in Python 3.16.
   Use the ``'w'`` format code instead.
-  (contributed by Hugo van Kemenade in :gh:`80480`)
+  (Contributed by Hugo van Kemenade in :gh:`80480`.)
 
 * :mod:`ctypes`: Deprecate undocumented :func:`!ctypes.SetPointerType`
   and :func:`!ctypes.ARRAY` functions.
@@ -860,6 +862,11 @@ Deprecated
   membership in :data:`~dis.hasarg` instead.
   (Contributed by Irit Katriel in :gh:`109319`.)
 
+* :ref:`frame-objects`:
+  Calling :meth:`frame.clear` on a suspended frame raises :exc:`RuntimeError`
+  (as has always been the case for an executing frame).
+  (Contributed by Irit Katriel in :gh:`79932`.)
+
 * :mod:`getopt` and :mod:`optparse` modules: They are now
   :term:`soft deprecated`: the :mod:`argparse` module should be used for new projects.
   Previously, the :mod:`optparse` module was already deprecated, its removal
@@ -889,6 +896,12 @@ Deprecated
   removal in Python 3.15. Use :func:`os.path.isreserved` to detect reserved
   paths on Windows.
 
+* :mod:`platform`:
+  :func:`~platform.java_ver` is deprecated and will be removed in 3.15.
+  It was largely untested, had a confusing API,
+  and was only useful for Jython support.
+  (Contributed by Nikita Sobolev in :gh:`116349`.)
+
 * :mod:`pydoc`: Deprecate undocumented :func:`!pydoc.ispackage` function.
   (Contributed by Zackery Spytz in :gh:`64020`.)
 
@@ -917,6 +930,10 @@ Deprecated
   Replace it with the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment variable.
   (Contributed by Inada Naoki in :gh:`73427`.)
 
+* :mod:`tarfile`:
+  The undocumented and unused ``tarfile`` attribute of :class:`tarfile.TarFile`
+  is deprecated and scheduled for removal in Python 3.16.
+
 * :mod:`traceback`: The field *exc_type* of :class:`traceback.TracebackException`
   is deprecated. Use *exc_type_str* instead.
 
@@ -949,28 +966,19 @@ Deprecated
     the new :ref:`type parameter syntax <type-params>` instead.
     (Contributed by Michael The in :gh:`107116`.)
 
-* :mod:`wave`: Deprecate the ``getmark()``, ``setmark()`` and ``getmarkers()``
-  methods of the :class:`wave.Wave_read` and :class:`wave.Wave_write` classes.
-  They will be removed in Python 3.15.
-  (Contributed by Victor Stinner in :gh:`105096`.)
-
-* Calling :meth:`frame.clear` on a suspended frame raises :exc:`RuntimeError`
-  (as has always been the case for an executing frame).
-  (Contributed by Irit Katriel in :gh:`79932`.)
-
-* Assignment to a function's :attr:`~function.__code__` attribute where the new code
+* :ref:`user-defined-funcs`:
+  Assignment to a function's :attr:`~function.__code__` attribute where the new code
   object's type does not match the function's type, is deprecated. The
   different types are: plain function, generator, async generator and
   coroutine.
   (Contributed by Irit Katriel in :gh:`81137`.)
 
-* The undocumented and unused ``tarfile`` attribute of :class:`tarfile.TarFile`
-  is deprecated and scheduled for removal in Python 3.16.
+* :mod:`wave`: Deprecate the ``getmark()``, ``setmark()`` and ``getmarkers()``
+  methods of the :class:`wave.Wave_read` and :class:`wave.Wave_write` classes.
+  They will be removed in Python 3.15.
+  (Contributed by Victor Stinner in :gh:`105096`.)
 
-* :func:`platform.java_ver` is deprecated and will be removed in 3.15.
-  It was largely untested, had a confusing API,
-  and was only useful for Jython support.
-  (Contributed by Nikita Sobolev in :gh:`116349`.)
+.. Add deprecations above alphabetically, not here at the end.
 
 Pending Removal in Python 3.14
 ------------------------------
@@ -1070,7 +1078,8 @@ Pending Removal in Python 3.14
 * :mod:`typing`: :class:`~typing.ByteString`, deprecated since Python 3.9,
   now causes a :exc:`DeprecationWarning` to be emitted when it is used.
 
-* :class:`!urllib.parse.Quoter` is deprecated: it was not intended to be a
+* :mod:`urllib`:
+  :class:`!urllib.parse.Quoter` is deprecated: it was not intended to be a
   public API.
   (Contributed by Gregory P. Smith in :gh:`88168`.)
 
@@ -1098,6 +1107,12 @@ Pending Removal in Python 3.15
   removal in Python 3.15. Use :func:`os.path.isreserved` to detect reserved
   paths on Windows.
 
+* :mod:`platform`:
+  :func:`~platform.java_ver` is deprecated and will be removed in 3.15.
+  It was largely untested, had a confusing API,
+  and was only useful for Jython support.
+  (Contributed by Nikita Sobolev in :gh:`116349`.)
+
 * :mod:`threading`:
   Passing any arguments to :func:`threading.RLock` is now deprecated.
   C version allows any numbers of args and kwargs,
@@ -1107,22 +1122,22 @@ Pending Removal in Python 3.15
 
 * :class:`typing.NamedTuple`:
 
-  * The undocumented keyword argument syntax for creating NamedTuple classes
+  * The undocumented keyword argument syntax for creating :class:`!NamedTuple` classes
     (``NT = NamedTuple("NT", x=int)``) is deprecated, and will be disallowed in
     3.15. Use the class-based syntax or the functional syntax instead.
 
-  * When using the functional syntax to create a NamedTuple class, failing to
-    pass a value to the 'fields' parameter (``NT = NamedTuple("NT")``) is
-    deprecated. Passing ``None`` to the 'fields' parameter
+  * When using the functional syntax to create a :class:`!NamedTuple` class, failing to
+    pass a value to the *fields* parameter (``NT = NamedTuple("NT")``) is
+    deprecated. Passing ``None`` to the *fields* parameter
     (``NT = NamedTuple("NT", None)``) is also deprecated. Both will be
-    disallowed in Python 3.15. To create a NamedTuple class with 0 fields, use
+    disallowed in Python 3.15. To create a :class:`!NamedTuple` class with 0 fields, use
     ``class NT(NamedTuple): pass`` or ``NT = NamedTuple("NT", [])``.
 
 * :class:`typing.TypedDict`: When using the functional syntax to create a
-  TypedDict class, failing to pass a value to the 'fields' parameter (``TD =
-  TypedDict("TD")``) is deprecated. Passing ``None`` to the 'fields' parameter
+  :class:`!TypedDict` class, failing to pass a value to the *fields* parameter (``TD =
+  TypedDict("TD")``) is deprecated. Passing ``None`` to the *fields* parameter
   (``TD = TypedDict("TD", None)``) is also deprecated. Both will be disallowed
-  in Python 3.15. To create a TypedDict class with 0 fields, use ``class
+  in Python 3.15. To create a :class:`!TypedDict` class with 0 fields, use ``class
   TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``.
 
 * :mod:`wave`: Deprecate the ``getmark()``, ``setmark()`` and ``getmarkers()``
@@ -1130,11 +1145,6 @@ Pending Removal in Python 3.15
   They will be removed in Python 3.15.
   (Contributed by Victor Stinner in :gh:`105096`.)
 
-* :func:`platform.java_ver` is deprecated and will be removed in 3.15.
-  It was largely untested, had a confusing API,
-  and was only useful for Jython support.
-  (Contributed by Nikita Sobolev in :gh:`116349`.)
-
 Pending Removal in Python 3.16
 ------------------------------
 
@@ -1575,15 +1585,15 @@ Changes in the Python API
   than directories only. Users may add a trailing slash to match only
   directories.
 
-* :c:func:`!PyCode_GetFirstFree` is an ustable API now and has been renamed
+* :c:func:`!PyCode_GetFirstFree` is an unstable API now and has been renamed
   to :c:func:`PyUnstable_Code_GetFirstFree`.
-  (Contributed by Bogdan Romanyuk in :gh:`115781`)
+  (Contributed by Bogdan Romanyuk in :gh:`115781`.)
 
 
 Build Changes
 =============
 
-* Autoconf 2.71 and aclocal 1.16.4 is now required to regenerate
+* Autoconf 2.71 and aclocal 1.16.4 are now required to regenerate
   the :file:`configure` script.
   (Contributed by Christian Heimes in :gh:`89886`.)
 
@@ -1606,10 +1616,10 @@ Build Changes
   :ref:`limited C API <limited-c-api>`.
   (Contributed by Victor Stinner in :gh:`85283`.)
 
-* ``wasm32-wasi`` is now a tier 2 platform.
+* ``wasm32-wasi`` is now a :pep:`11` tier 2 platform.
   (Contributed by Brett Cannon in :gh:`115192`.)
 
-* ``wasm32-emscripten`` is no longer a supported platform.
+* ``wasm32-emscripten`` is no longer a :pep:`11` supported platform.
   (Contributed by Brett Cannon in :gh:`115192`.)
 
 
@@ -1835,6 +1845,13 @@ Porting to Python 3.13
   and ``setitimer()`` functions.
   (Contributed by Victor Stinner in :gh:`108765`.)
 
+* On Windows, ``Python.h`` no longer includes the ``<stddef.h>`` standard
+  header file. If needed, it should now be included explicitly. For example, it
+  provides ``offsetof()`` function, and ``size_t`` and ``ptrdiff_t`` types.
+  Including ``<stddef.h>`` explicitly was already needed by all other
+  platforms, the ``HAVE_STDDEF_H`` macro is only defined on Windows.
+  (Contributed by Victor Stinner in :gh:`108765`.)
+
 * If the :c:macro:`Py_LIMITED_API` macro is defined, :c:macro:`!Py_BUILD_CORE`,
   :c:macro:`!Py_BUILD_CORE_BUILTIN` and :c:macro:`!Py_BUILD_CORE_MODULE` macros
   are now undefined by ``<Python.h>``.
@@ -1844,7 +1861,7 @@ Porting to Python 3.13
   were removed. They should be replaced by the new macros ``Py_TRASHCAN_BEGIN``
   and ``Py_TRASHCAN_END``.
 
-  A tp_dealloc function that has the old macros, such as::
+  A ``tp_dealloc`` function that has the old macros, such as::
 
     static void
     mytype_dealloc(mytype *p)
@@ -1869,13 +1886,6 @@ Porting to Python 3.13
   Note that ``Py_TRASHCAN_BEGIN`` has a second argument which
   should be the deallocation function it is in.
 
-* On Windows, ``Python.h`` no longer includes the ``<stddef.h>`` standard
-  header file. If needed, it should now be included explicitly. For example, it
-  provides ``offsetof()`` function, and ``size_t`` and ``ptrdiff_t`` types.
-  Including ``<stddef.h>`` explicitly was already needed by all other
-  platforms, the ``HAVE_STDDEF_H`` macro is only defined on Windows.
-  (Contributed by Victor Stinner in :gh:`108765`.)
-
 Deprecated
 ----------