Skip to content

Commit

Permalink
[3.12] GH-109190: Copyedit 3.12 What's New: Deprecations (GH-109766) (#…
Browse files Browse the repository at this point in the history 
…109925)

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

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

* 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 <9087854+AA-Turner@users.noreply.github.com>
  • Loading branch information
@miss-islington @AA-Turner
miss-islington and AA-Turner authored Sep 27, 2023
1 parent 648198c commit 1d6ef7e
Showing 1 changed file with 170 additions and 107 deletions.
277 changes: 170 additions & 107 deletions Doc/whatsnew/3.12.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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`.)

Expand All @@ -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
------------------------------

Expand Down Expand Up @@ -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
----------------------------------
Expand Down

0 comments on commit 1d6ef7e

Please sign in to comment.