[3.12] GH-109190: Copyedit 3.12 What's New: Deprecations (GH-109766) (#109925)

* GH-109190: Copyedit 3.12 What's New: Deprecations (GH-109766)
(cherry picked from commit 87ddfa7)

Co-authored-by: Adam Turner <[email protected]>

* GH-109190: Copyedit 3.12 What's New: Deprecations (``os`` fix)  (#109927)

Merge the two ``os`` entries

(cherry picked from commit 0e28d0f)

---------

Co-authored-by: Adam Turner <[email protected]>

Author: miss-islington

Doc/whatsnew/3.12.rst

@@ -580,19 +580,10 @@ asyncio
   :class:`asyncio.ThreadedChildWatcher`.
   (Contributed by Kumar Aditya in :gh:`98024`.)
 
-* The child watcher classes :class:`asyncio.MultiLoopChildWatcher`,
-  :class:`asyncio.FastChildWatcher`, :class:`asyncio.AbstractChildWatcher`
-  and :class:`asyncio.SafeChildWatcher` are deprecated and
-  will be removed in Python 3.14. It is recommended to not manually
-  configure a child watcher as the event loop now uses the best available
-  child watcher for each platform (:class:`asyncio.PidfdChildWatcher`
-  if supported and :class:`asyncio.ThreadedChildWatcher` otherwise).
-  (Contributed by Kumar Aditya in :gh:`94597`.)
-
-* :func:`asyncio.set_child_watcher`, :func:`asyncio.get_child_watcher`,
-  :meth:`asyncio.AbstractEventLoopPolicy.set_child_watcher` and
-  :meth:`asyncio.AbstractEventLoopPolicy.get_child_watcher` are deprecated
-  and will be removed in Python 3.14.
+* The event loop now uses the best available child watcher for each platform
+  (:class:`asyncio.PidfdChildWatcher` if supported and
+  :class:`asyncio.ThreadedChildWatcher` otherwise), so manually
+  configuring a child watcher is not recommended.
   (Contributed by Kumar Aditya in :gh:`94597`.)
 
 * Add *loop_factory* parameter to :func:`asyncio.run` to allow specifying
@@ -1046,15 +1037,52 @@ Demos and Tools
 Deprecated
 ==========
 
-* :mod:`asyncio`: The :meth:`~asyncio.get_event_loop` method of the
-  default event loop policy now emits a :exc:`DeprecationWarning` if there
-  is no current event loop set and it decides to create one.
-  (Contributed by Serhiy Storchaka and Guido van Rossum in :gh:`100160`.)
+* :mod:`argparse`: The *type*, *choices*, and *metavar* parameters
+  of :class:`!argparse.BooleanOptionalAction` are deprecated
+  and will be removed in 3.14.
+  (Contributed by Nikita Sobolev in :gh:`92248`.)
+
+* :mod:`ast`: The following :mod:`ast` features have been deprecated in documentation since
+  Python 3.8, now cause a :exc:`DeprecationWarning` to be emitted at runtime
+  when they are accessed or used, and will be removed in Python 3.14:
+
+  * :class:`!ast.Num`
+  * :class:`!ast.Str`
+  * :class:`!ast.Bytes`
+  * :class:`!ast.NameConstant`
+  * :class:`!ast.Ellipsis`
+
+  Use :class:`ast.Constant` instead.
+  (Contributed by Serhiy Storchaka in :gh:`90953`.)
+
+* :mod:`asyncio`:
+
+  * The child watcher classes :class:`asyncio.MultiLoopChildWatcher`,
+    :class:`asyncio.FastChildWatcher`, :class:`asyncio.AbstractChildWatcher`
+    and :class:`asyncio.SafeChildWatcher` are deprecated and
+    will be removed in Python 3.14.
+    (Contributed by Kumar Aditya in :gh:`94597`.)
+
+  * :func:`asyncio.set_child_watcher`, :func:`asyncio.get_child_watcher`,
+    :meth:`asyncio.AbstractEventLoopPolicy.set_child_watcher` and
+    :meth:`asyncio.AbstractEventLoopPolicy.get_child_watcher` are deprecated
+    and will be removed in Python 3.14.
+    (Contributed by Kumar Aditya in :gh:`94597`.)
+
+  * The :meth:`~asyncio.get_event_loop` method of the
+    default event loop policy now emits a :exc:`DeprecationWarning` if there
+    is no current event loop set and it decides to create one.
+    (Contributed by Serhiy Storchaka and Guido van Rossum in :gh:`100160`.)
 
 * :mod:`calendar`: ``calendar.January`` and ``calendar.February`` constants are deprecated and
   replaced by :data:`calendar.JANUARY` and :data:`calendar.FEBRUARY`.
   (Contributed by Prince Roshan in :gh:`103636`.)
 
+* :mod:`collections.abc`: Deprecated :class:`collections.abc.ByteString`.
+  Prefer :class:`Sequence` or :class:`collections.abc.Buffer`.
+  For use in typing, prefer a union, like ``bytes | bytearray``, or :class:`collections.abc.Buffer`.
+  (Contributed by Shantanu Jain in :gh:`91896`.)
+
 * :mod:`datetime`: :class:`datetime.datetime`'s :meth:`~datetime.datetime.utcnow` and
   :meth:`~datetime.datetime.utcfromtimestamp` are deprecated and will be
   removed in a future version. Instead, use timezone-aware objects to represent
@@ -1063,42 +1091,88 @@ Deprecated
   :const:`datetime.UTC`.
   (Contributed by Paul Ganssle in :gh:`103857`.)
 
-* :mod:`os`: The ``st_ctime`` fields return by :func:`os.stat` and :func:`os.lstat` on
-  Windows are deprecated. In a future release, they will contain the last
-  metadata change time, consistent with other platforms. For now, they still
-  contain the creation time, which is also available in the new ``st_birthtime``
-  field. (Contributed by Steve Dower in :gh:`99726`.)
-
-* :mod:`os`: On POSIX platforms, :func:`os.fork` can now raise a
-  :exc:`DeprecationWarning` when it can detect being called from a
-  multithreaded process. There has always been a fundamental incompatibility
-  with the POSIX platform when doing so. Even if such code *appeared* to work.
-  We added the warning to to raise awareness as issues encounted by code doing
-  this are becoming more frequent. See the :func:`os.fork` documentation for
-  more details along with `this discussion on fork being incompatible with threads
-  <https://discuss.python.org/t/33555>`_ for *why* we're now surfacing this
-  longstanding platform compatibility problem to developers.
+* :mod:`email`: Deprecate the *isdst* parameter in :func:`email.utils.localtime`.
+  (Contributed by Alan Williams in :gh:`72346`.)
+
+* :mod:`importlib.abc`: Deprecated the following classes, scheduled for removal in
+  Python 3.14:
+
+  * :class:`!importlib.abc.ResourceReader`
+  * :class:`!importlib.abc.Traversable`
+  * :class:`!importlib.abc.TraversableResources`
+
+  Use :mod:`importlib.resources.abc` classes instead:
+
+  * :class:`importlib.resources.abc.Traversable`
+  * :class:`importlib.resources.abc.TraversableResources`
+
+  (Contributed by Jason R. Coombs and Hugo van Kemenade in :gh:`93963`.)
+
+* :mod:`itertools`: Deprecate the support for copy, deepcopy, and pickle operations,
+  which is undocumented, inefficient, historically buggy, and inconsistent.
+  This will be removed in 3.14 for a significant reduction in code
+  volume and maintenance burden.
+  (Contributed by Raymond Hettinger in :gh:`101588`.)
+
+* :mod:`multiprocessing`: In Python 3.14, the default :mod:`multiprocessing`
+  start method will change to a safer one on Linux, BSDs,
+  and other non-macOS POSIX platforms where ``'fork'`` is currently
+  the default (:gh:`84559`). Adding a runtime warning about this was deemed too
+  disruptive as the majority of code is not expected to care. Use the
+  :func:`~multiprocessing.get_context` or
+  :func:`~multiprocessing.set_start_method` APIs to explicitly specify when
+  your code *requires* ``'fork'``.  See :ref:`contexts and start methods
+  <multiprocessing-start-methods>`.
+
+* :mod:`pkgutil`: :func:`pkgutil.find_loader` and :func:`pkgutil.get_loader`
+  are deprecated and will be removed in Python 3.14;
+  use :func:`importlib.util.find_spec` instead.
+  (Contributed by Nikita Sobolev in :gh:`97850`.)
+
+* :mod:`pty`: The module has two undocumented ``master_open()`` and ``slave_open()``
+  functions that have been deprecated since Python 2 but only gained a
+  proper :exc:`DeprecationWarning` in 3.12. Remove them in 3.14.
+  (Contributed by Soumendra Ganguly and Gregory P. Smith in :gh:`85984`.)
+
+* :mod:`os`:
+
+  * The ``st_ctime`` fields return by :func:`os.stat` and :func:`os.lstat` on
+    Windows are deprecated. In a future release, they will contain the last
+    metadata change time, consistent with other platforms. For now, they still
+    contain the creation time, which is also available in the new ``st_birthtime``
+    field. (Contributed by Steve Dower in :gh:`99726`.)
+
+  * On POSIX platforms, :func:`os.fork` can now raise a
+    :exc:`DeprecationWarning` when it can detect being called from a
+    multithreaded process. There has always been a fundamental incompatibility
+    with the POSIX platform when doing so. Even if such code *appeared* to work.
+    We added the warning to to raise awareness as issues encounted by code doing
+    this are becoming more frequent. See the :func:`os.fork` documentation for
+    more details along with `this discussion on fork being incompatible with threads
+    <https://discuss.python.org/t/33555>`_ for *why* we're now surfacing this
+    longstanding platform compatibility problem to developers.
 
   When this warning appears due to usage of :mod:`multiprocessing` or
   :mod:`concurrent.futures` the fix is to use a different
   :mod:`multiprocessing` start method such as ``"spawn"`` or ``"forkserver"``.
 
-* :mod:`shutil`: The *onerror* argument of :func:`shutil.rmtree` is deprecated as will be removed
+* :mod:`shutil`: The *onerror* argument of :func:`shutil.rmtree` is deprecated and will be removed
   in Python 3.14. Use *onexc* instead. (Contributed by Irit Katriel in :gh:`102828`.)
 
 * :mod:`sqlite3`:
-    * :ref:`default adapters and converters
-      <sqlite3-default-converters>` are now deprecated.
-      Instead, use the :ref:`sqlite3-adapter-converter-recipes`
-      and tailor them to your needs.
-      (Contributed by Erlend E. Aasland in :gh:`90016`.)
-
-    * In :meth:`~sqlite3.Cursor.execute`, :exc:`DeprecationWarning` is now emitted
-      when :ref:`named placeholders <sqlite3-placeholders>` are used together with
-      parameters supplied as a :term:`sequence` instead of as a :class:`dict`.
-      Starting from Python 3.14, using named placeholders with parameters supplied
-      as a sequence will raise a :exc:`~sqlite3.ProgrammingError`.
-      (Contributed by Erlend E. Aasland in :gh:`101698`.)
+
+  * :ref:`default adapters and converters
+    <sqlite3-default-converters>` are now deprecated.
+    Instead, use the :ref:`sqlite3-adapter-converter-recipes`
+    and tailor them to your needs.
+    (Contributed by Erlend E. Aasland in :gh:`90016`.)
+
+  * In :meth:`~sqlite3.Cursor.execute`, :exc:`DeprecationWarning` is now emitted
+    when :ref:`named placeholders <sqlite3-placeholders>` are used together with
+    parameters supplied as a :term:`sequence` instead of as a :class:`dict`.
+    Starting from Python 3.14, using named placeholders with parameters supplied
+    as a sequence will raise a :exc:`~sqlite3.ProgrammingError`.
+    (Contributed by Erlend E. Aasland in :gh:`101698`.)
 
 * :mod:`sys`: The :data:`sys.last_type`, :data:`sys.last_value` and :data:`sys.last_traceback`
   fields are deprecated. Use :data:`sys.last_exc` instead.
@@ -1108,16 +1182,24 @@ Deprecated
   Python 3.14, when ``'data'`` filter will become the default.
   See :ref:`tarfile-extraction-filter` for details.
 
-* :mod:`typing`: :class:`typing.Hashable` and :class:`typing.Sized` aliases for :class:`collections.abc.Hashable`
-  and :class:`collections.abc.Sized`. (:gh:`94309`.)
+* :mod:`typing`:
+
+  * :class:`typing.Hashable` and :class:`typing.Sized` aliases for :class:`collections.abc.Hashable`
+    and :class:`collections.abc.Sized`. (:gh:`94309`.)
+
+  * :class:`typing.ByteString`, deprecated since Python 3.9, now causes a
+    :exc:`DeprecationWarning` to be emitted when it is used.
+    (Contributed by Alex Waygood in :gh:`91896`.)
 
 * :mod:`xml.etree.ElementTree`: The module now emits :exc:`DeprecationWarning`
   when testing the truth value of an :class:`xml.etree.ElementTree.Element`.
   Before, the Python implementation emitted :exc:`FutureWarning`, and the C
   implementation emitted nothing.
+  (Contributed by Jacob Walls in :gh:`83122`.)
 
-* The 3-arg signatures (type, value, traceback) of :meth:`~coroutine.throw`,
-  :meth:`~generator.throw` and :meth:`~agen.athrow` are deprecated and
+* The 3-arg signatures (type, value, traceback) of :meth:`coroutine throw()
+  <coroutine.throw>`, :meth:`generator throw() <generator.throw>` and
+  :meth:`async generator throw() <agen.athrow>` are deprecated and
   may be removed in a future version of Python. Use the single-arg versions
   of these functions instead. (Contributed by Ofey Chan in :gh:`89874`.)
 
@@ -1126,12 +1208,21 @@ Deprecated
   :exc:`ImportWarning`).
   (Contributed by Brett Cannon in :gh:`65961`.)
 
+* Setting ``__package__`` or ``__cached__`` on a module is deprecated,
+  and will cease to be set or taken into consideration by the import system in Python 3.14.
+  (Contributed by Brett Cannon in :gh:`65961`.)
+
 * The bitwise inversion operator (``~``) on bool is deprecated. It will throw an
   error in Python 3.14. Use ``not`` for logical negation of bools instead.
   In the rare case that you really need the bitwise inversion of the underlying
-  ``int``, convert to int explicitly with ``~int(x)``. (Contributed by Tim Hoffmann
+  ``int``, convert to int explicitly: ``~int(x)``. (Contributed by Tim Hoffmann
   in :gh:`103487`.)
 
+* Accessing ``co_lnotab`` on code objects was deprecated in Python 3.10 via :pep:`626`,
+  but it only got a proper :exc:`DeprecationWarning` in 3.12,
+  therefore it will be removed in 3.14.
+  (Contributed by Nikita Sobolev in :gh:`101866`.)
+
 Pending Removal in Python 3.13
 ------------------------------
 
@@ -1179,90 +1270,62 @@ APIs:
 Pending Removal in Python 3.14
 ------------------------------
 
+The following APIs have been deprecated
+and will be removed in Python 3.14.
+
 * :mod:`argparse`: The *type*, *choices*, and *metavar* parameters
-  of :class:`!argparse.BooleanOptionalAction` are deprecated
-  and will be removed in 3.14.
-  (Contributed by Nikita Sobolev in :gh:`92248`.)
+  of :class:`!argparse.BooleanOptionalAction`
 
-* :mod:`ast`: The following :mod:`ast` features have been deprecated in documentation since
-  Python 3.8, now cause a :exc:`DeprecationWarning` to be emitted at runtime
-  when they are accessed or used, and will be removed in Python 3.14:
+* :mod:`ast`:
 
   * :class:`!ast.Num`
   * :class:`!ast.Str`
   * :class:`!ast.Bytes`
   * :class:`!ast.NameConstant`
   * :class:`!ast.Ellipsis`
 
-  Use :class:`ast.Constant` instead.
-  (Contributed by Serhiy Storchaka in :gh:`90953`.)
+* :mod:`asyncio`:
 
-* :mod:`asyncio`: the *msg* parameter of both
-  :meth:`asyncio.Future.cancel` and
-  :meth:`asyncio.Task.cancel` (:gh:`90985`)
+  * :class:`!asyncio.MultiLoopChildWatcher`
+  * :class:`!asyncio.FastChildWatcher`
+  * :class:`!asyncio.AbstractChildWatcher`
+  * :class:`!asyncio.SafeChildWatcher`
+  * :func:`!asyncio.set_child_watcher`
+  * :func:`!asyncio.get_child_watcher`,
+  * :meth:`!asyncio.AbstractEventLoopPolicy.set_child_watcher`
+  * :meth:`!asyncio.AbstractEventLoopPolicy.get_child_watcher`
 
-* :mod:`collections.abc`: Deprecated :class:`collections.abc.ByteString`.
-  Prefer :class:`Sequence` or :class:`collections.abc.Buffer`.
-  For use in typing, prefer a union, like ``bytes | bytearray``, or :class:`collections.abc.Buffer`.
-  (Contributed by Shantanu Jain in :gh:`91896`.)
+* :mod:`collections.abc`: :class:`!collections.abc.ByteString`.
 
-* :mod:`email`: Deprecated the *isdst* parameter in :func:`email.utils.localtime`.
-  (Contributed by Alan Williams in :gh:`72346`.)
+* :mod:`email`: the *isdst* parameter in :func:`email.utils.localtime`.
 
-* :mod:`importlib.abc`: Deprecated the following classes, scheduled for removal in
-  Python 3.14:
+* :mod:`importlib.abc`:
 
   * :class:`!importlib.abc.ResourceReader`
   * :class:`!importlib.abc.Traversable`
   * :class:`!importlib.abc.TraversableResources`
 
-  Use :mod:`importlib.resources.abc` classes instead:
+* :mod:`itertools`: Support for copy, deepcopy, and pickle operations.
 
-  * :class:`importlib.resources.abc.Traversable`
-  * :class:`importlib.resources.abc.TraversableResources`
-
-  (Contributed by Jason R. Coombs and Hugo van Kemenade in :gh:`93963`.)
-
-* :mod:`itertools`: The module had undocumented, inefficient, historically buggy,
-  and inconsistent support for copy, deepcopy, and pickle operations.
-  This will be removed in 3.14 for a significant reduction in code
-  volume and maintenance burden.
-  (Contributed by Raymond Hettinger in :gh:`101588`.)
+* :mod:`pkgutil`:
 
-* :mod:`multiprocessing`: The default :mod:`multiprocessing` start method will change to a safer one on
-  Linux, BSDs, and other non-macOS POSIX platforms where ``'fork'`` is currently
-  the default (:gh:`84559`). Adding a runtime warning about this was deemed too
-  disruptive as the majority of code is not expected to care. Use the
-  :func:`~multiprocessing.get_context` or
-  :func:`~multiprocessing.set_start_method` APIs to explicitly specify when
-  your code *requires* ``'fork'``.  See :ref:`multiprocessing-start-methods`.
+  * :func:`!pkgutil.find_loader`
+  * :func:`!pkgutil.get_loader`.
 
-* :mod:`pkgutil`: :func:`pkgutil.find_loader` and :func:`pkgutil.get_loader`
-  now raise :exc:`DeprecationWarning`;
-  use :func:`importlib.util.find_spec` instead.
-  (Contributed by Nikita Sobolev in :gh:`97850`.)
+* :mod:`pty`:
 
-* :mod:`pty`: The module has two undocumented ``master_open()`` and ``slave_open()``
-  functions that have been deprecated since Python 2 but only gained a
-  proper :exc:`DeprecationWarning` in 3.12. Remove them in 3.14.
+  * :func:`!pty.master_open`
+  * :func:`!pty.slave_open`
 
-* :mod:`shutil`: The *onerror* argument of :func:`shutil.rmtree` is deprecated in 3.12,
-  and will be removed in 3.14.
+* :mod:`shutil`: The *onerror* argument of :func:`shutil.rmtree`
 
-* :mod:`typing`: :class:`typing.ByteString`, deprecated since Python 3.9, now causes a
-  :exc:`DeprecationWarning` to be emitted when it is used.
+* :mod:`typing`: :class:`!typing.ByteString`
 
-* :mod:`xml.etree.ElementTree`: Testing the truth value of an :class:`xml.etree.ElementTree.Element`
-  is deprecated and will raise an exception in Python 3.14.
+* :mod:`xml.etree.ElementTree`: Testing the truth value of an :class:`xml.etree.ElementTree.Element`.
 
-* ``__package__`` and ``__cached__`` will cease to be set or taken
-  into consideration by the import system (:gh:`97879`).
+* The ``__package__`` and ``__cached__`` attributes on module objects.
 
-* Accessing ``co_lnotab`` was deprecated in :pep:`626` since 3.10
-  and was planned to be removed in 3.12
-  but it only got a proper :exc:`DeprecationWarning` in 3.12.
-  May be removed in 3.14.
-  (Contributed by Nikita Sobolev in :gh:`101866`.)
+* The ``co_lnotab`` attribute of code objects.
 
 Pending Removal in Future Versions
 ----------------------------------