mirror of https://github.com/python/cpython
880 lines
34 KiB
ReStructuredText
880 lines
34 KiB
ReStructuredText
|
|
****************************
|
|
What's New In Python 3.12
|
|
****************************
|
|
|
|
:Release: |release|
|
|
:Date: |today|
|
|
|
|
.. Rules for maintenance:
|
|
|
|
* Anyone can add text to this document. Do not spend very much time
|
|
on the wording of your changes, because your text will probably
|
|
get rewritten to some degree.
|
|
|
|
* The maintainer will go through Misc/NEWS periodically and add
|
|
changes; it's therefore more important to add your changes to
|
|
Misc/NEWS than to this file.
|
|
|
|
* This is not a complete list of every single change; completeness
|
|
is the purpose of Misc/NEWS. Some changes I consider too small
|
|
or esoteric to include. If such a change is added to the text,
|
|
I'll just remove it. (This is another reason you shouldn't spend
|
|
too much time on writing your addition.)
|
|
|
|
* If you want to draw your new text to the attention of the
|
|
maintainer, add 'XXX' to the beginning of the paragraph or
|
|
section.
|
|
|
|
* It's OK to just add a fragmentary note about a change. For
|
|
example: "XXX Describe the transmogrify() function added to the
|
|
socket module." The maintainer will research the change and
|
|
write the necessary text.
|
|
|
|
* You can comment out your additions if you like, but it's not
|
|
necessary (especially when a final release is some months away).
|
|
|
|
* Credit the author of a patch or bugfix. Just the name is
|
|
sufficient; the e-mail address isn't necessary.
|
|
|
|
* It's helpful to add the issue number as a comment:
|
|
|
|
XXX Describe the transmogrify() function added to the socket
|
|
module.
|
|
(Contributed by P.Y. Developer in :gh:`12345`.)
|
|
|
|
This saves the maintainer the effort of going through the VCS log when
|
|
researching a change.
|
|
|
|
This article explains the new features in Python 3.12, compared to 3.11.
|
|
|
|
For full details, see the :ref:`changelog <changelog>`.
|
|
|
|
.. note::
|
|
|
|
Prerelease users should be aware that this document is currently in draft
|
|
form. It will be updated substantially as Python 3.12 moves towards release,
|
|
so it's worth checking back even after reading earlier versions.
|
|
|
|
|
|
Summary -- Release highlights
|
|
=============================
|
|
|
|
.. This section singles out the most important changes in Python 3.12.
|
|
Brevity is key.
|
|
|
|
|
|
.. PEP-sized items next.
|
|
|
|
Important deprecations, removals or restrictions:
|
|
|
|
* :pep:`623`, Remove wstr from Unicode
|
|
|
|
* :pep:`632`, Remove the ``distutils`` package.
|
|
|
|
Improved Error Messages
|
|
=======================
|
|
|
|
* Modules from the standard library are now potentially suggested as part of
|
|
the error messages displayed by the interpreter when a :exc:`NameError` is
|
|
raised to the top level. Contributed by Pablo Galindo in :gh:`98254`.
|
|
|
|
>>> sys.version_info
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1, in <module>
|
|
NameError: name 'sys' is not defined. Did you forget to import 'sys'?
|
|
|
|
* Improve the error suggestion for :exc:`NameError` exceptions for instances.
|
|
Now if a :exc:`NameError` is raised in a method and the instance has an
|
|
attribute that's exactly equal to the name in the exception, the suggestion
|
|
will include ``self.<NAME>`` instead of the closest match in the method
|
|
scope. Contributed by Pablo Galindo in :gh:`99139`.
|
|
|
|
>>> class A:
|
|
... def __init__(self):
|
|
... self.blech = 1
|
|
...
|
|
... def foo(self):
|
|
... somethin = blech
|
|
|
|
>>> A().foo()
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1
|
|
somethin = blech
|
|
^^^^^
|
|
NameError: name 'blech' is not defined. Did you mean: 'self.blech'?
|
|
|
|
|
|
* Improve the :exc:`SyntaxError` error message when the user types ``import x
|
|
from y`` instead of ``from y import x``. Contributed by Pablo Galindo in :gh:`98931`.
|
|
|
|
>>> import a.y.z from b.y.z
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1
|
|
import a.y.z from b.y.z
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
SyntaxError: Did you mean to use 'from ... import ...' instead?
|
|
|
|
* :exc:`ImportError` exceptions raised from failed ``from <module> import
|
|
<name>`` statements now include suggestions for the value of ``<name>`` based on the
|
|
available names in ``<module>``. Contributed by Pablo Galindo in :gh:`91058`.
|
|
|
|
>>> from collections import chainmap
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1, in <module>
|
|
ImportError: cannot import name 'chainmap' from 'collections'. Did you mean: 'ChainMap'?
|
|
|
|
|
|
New Features
|
|
============
|
|
|
|
* Add :ref:`perf_profiling` through the new
|
|
environment variable :envvar:`PYTHONPERFSUPPORT`,
|
|
the new command-line option :option:`-X perf <-X>`,
|
|
as well as the new :func:`sys.activate_stack_trampoline`,
|
|
:func:`sys.deactivate_stack_trampoline`,
|
|
and :func:`sys.is_stack_trampoline_active` APIs.
|
|
(Design by Pablo Galindo. Contributed by Pablo Galindo and Christian Heimes
|
|
with contributions from Gregory P. Smith [Google] and Mark Shannon
|
|
in :gh:`96123`.)
|
|
|
|
|
|
Other Language Changes
|
|
======================
|
|
|
|
* :class:`types.MappingProxyType` instances are now hashable if the underlying
|
|
mapping is hashable.
|
|
(Contributed by Serhiy Storchaka in :gh:`87995`.)
|
|
|
|
* :class:`memoryview` now supports the half-float type (the "e" format code).
|
|
(Contributed by Dong-hee Na and Antoine Pitrou in :gh:`90751`.)
|
|
|
|
* The parser now raises :exc:`SyntaxError` when parsing source code containing
|
|
null bytes. (Contributed by Pablo Galindo in :gh:`96670`.)
|
|
|
|
* :func:`ast.parse` now raises :exc:`SyntaxError` instead of :exc:`ValueError`
|
|
when parsing source code containing null bytes. (Contributed by Pablo Galindo
|
|
in :gh:`96670`.)
|
|
|
|
* The Garbage Collector now runs only on the eval breaker mechanism of the
|
|
Python bytecode evaluation loop instead on object allocations. The GC can
|
|
also run when :c:func:`PyErr_CheckSignals` is called so C extensions that
|
|
need to run for a long time without executing any Python code also have a
|
|
chance to execute the GC periodically. (Contributed by Pablo Galindo in
|
|
:gh:`97922`.)
|
|
|
|
* A backslash-character pair that is not a valid escape sequence now generates
|
|
a :exc:`SyntaxWarning`, instead of :exc:`DeprecationWarning`.
|
|
For example, ``re.compile("\d+\.\d+")`` now emits a :exc:`SyntaxWarning`
|
|
(``"\d"`` is an invalid escape sequence), use raw strings for regular
|
|
expression: ``re.compile(r"\d+\.\d+")``.
|
|
In a future Python version, :exc:`SyntaxError` will eventually be raised,
|
|
instead of :exc:`SyntaxWarning`.
|
|
(Contributed by Victor Stinner in :gh:`98401`.)
|
|
|
|
* Octal escapes with value larger than ``0o377`` (ex: ``"\477"``), deprecated
|
|
in Python 3.11, now produce a :exc:`SyntaxWarning`, instead of
|
|
:exc:`DeprecationWarning`.
|
|
In a future Python version they will be eventually a :exc:`SyntaxError`.
|
|
(Contributed by Victor Stinner in :gh:`98401`.)
|
|
|
|
|
|
New Modules
|
|
===========
|
|
|
|
* None yet.
|
|
|
|
|
|
Improved Modules
|
|
================
|
|
|
|
array
|
|
-----
|
|
|
|
* The :class:`array.array` class now supports subscripting, making it a
|
|
:term:`generic type`. (Contributed by Jelle Zijlstra in :gh:`98658`.)
|
|
|
|
asyncio
|
|
-------
|
|
|
|
* On Linux, :mod:`asyncio` uses :class:`~asyncio.PidfdChildWatcher` by default
|
|
if :func:`os.pidfd_open` is available and functional instead of
|
|
: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.
|
|
(Contributed by Kumar Aditya in :gh:`94597`.)
|
|
|
|
* Add *loop_factory* parameter to :func:`asyncio.run` to allow specifying
|
|
a custom event loop factory.
|
|
(Contributed by Kumar Aditya in :gh:`99388`.)
|
|
|
|
|
|
pathlib
|
|
-------
|
|
|
|
* Add :meth:`~pathlib.Path.walk` for walking the directory trees and generating
|
|
all file or directory names within them, similar to :func:`os.walk`.
|
|
(Contributed by Stanislav Zmiev in :gh:`90385`.)
|
|
|
|
* Add *walk_up* optional parameter to :meth:`pathlib.PurePath.relative_to`
|
|
to allow the insertion of ``..`` entries in the result; this behavior is
|
|
more consistent with :func:`os.path.relpath`.
|
|
(Contributed by Domenico Ragusa in :issue:`40358`.)
|
|
|
|
dis
|
|
---
|
|
|
|
* Pseudo instruction opcodes (which are used by the compiler but
|
|
do not appear in executable bytecode) are now exposed in the
|
|
:mod:`dis` module.
|
|
:data:`~dis.HAVE_ARGUMENT` is still relevant to real opcodes,
|
|
but it is not useful for pseudo instructions. Use the new
|
|
:data:`~dis.hasarg` collection instead.
|
|
(Contributed by Irit Katriel in :gh:`94216`.)
|
|
|
|
os
|
|
--
|
|
|
|
* Add :data:`os.PIDFD_NONBLOCK` to open a file descriptor
|
|
for a process with :func:`os.pidfd_open` in non-blocking mode.
|
|
(Contributed by Kumar Aditya in :gh:`93312`.)
|
|
|
|
shutil
|
|
------
|
|
|
|
* :func:`shutil.make_archive` now passes the *root_dir* argument to custom
|
|
archivers which support it.
|
|
In this case it no longer temporarily changes the current working directory
|
|
of the process to *root_dir* to perform archiving.
|
|
(Contributed by Serhiy Storchaka in :gh:`74696`.)
|
|
|
|
|
|
sqlite3
|
|
-------
|
|
|
|
* Add a :ref:`command-line interface <sqlite3-cli>`.
|
|
(Contributed by Erlend E. Aasland in :gh:`77617`.)
|
|
|
|
* Add the :attr:`~sqlite3.Connection.autocommit` attribute
|
|
to :class:`~sqlite3.Connection`
|
|
and the *autocommit* parameter to :func:`~sqlite3.connect`
|
|
to control :pep:`249`-compliant
|
|
:ref:`transaction handling <sqlite3-transaction-control-autocommit>`.
|
|
(Contributed by Erlend E. Aasland in :gh:`83638`.)
|
|
|
|
threading
|
|
---------
|
|
|
|
* Add :func:`threading.settrace_all_threads` and
|
|
:func:`threading.setprofile_all_threads` that allow to set tracing and
|
|
profiling functions in all running threads in addition to the calling one.
|
|
(Contributed by Pablo Galindo in :gh:`93503`.)
|
|
|
|
unicodedata
|
|
-----------
|
|
|
|
* The Unicode database has been updated to version 15.0.0. (Contributed by
|
|
Benjamin Peterson in :gh:`96734`).
|
|
|
|
tempfile
|
|
--------
|
|
|
|
The :class:`tempfile.NamedTemporaryFile` function has a new optional parameter
|
|
*delete_on_close* (Contributed by Evgeny Zorin in :gh:`58451`.)
|
|
|
|
sys
|
|
---
|
|
|
|
* Add :func:`sys.activate_stack_trampoline` and
|
|
:func:`sys.deactivate_stack_trampoline` for activating and deactivating
|
|
stack profiler trampolines,
|
|
and :func:`sys.is_stack_trampoline_active` for querying if stack profiler
|
|
trampolines are active.
|
|
(Contributed by Pablo Galindo and Christian Heimes
|
|
with contributions from Gregory P. Smith [Google] and Mark Shannon
|
|
in :gh:`96123`.)
|
|
|
|
|
|
Optimizations
|
|
=============
|
|
|
|
* Removed ``wstr`` and ``wstr_length`` members from Unicode objects.
|
|
It reduces object size by 8 or 16 bytes on 64bit platform. (:pep:`623`)
|
|
(Contributed by Inada Naoki in :gh:`92536`.)
|
|
|
|
* Added experimental support for using the BOLT binary optimizer in the build
|
|
process, which improves performance by 1-5%.
|
|
(Contributed by Kevin Modzelewski in :gh:`90536`.)
|
|
|
|
* Speed up the regular expression substitution (functions :func:`re.sub` and
|
|
:func:`re.subn` and corresponding :class:`re.Pattern` methods) for
|
|
replacement strings containing group references by 2--3 times.
|
|
(Contributed by Serhiy Storchaka in :gh:`91524`.)
|
|
|
|
|
|
CPython bytecode changes
|
|
========================
|
|
|
|
* Removed the :opcode:`LOAD_METHOD` instruction. It has been merged into
|
|
:opcode:`LOAD_ATTR`. :opcode:`LOAD_ATTR` will now behave like the old
|
|
:opcode:`LOAD_METHOD` instruction if the low bit of its oparg is set.
|
|
(Contributed by Ken Jin in :gh:`93429`.)
|
|
|
|
|
|
Demos and Tools
|
|
===============
|
|
|
|
* Remove the ``Tools/demo/`` directory which contained old demo scripts. A copy
|
|
can be found in the `old-demos project
|
|
<https://github.com/gvanrossum/old-demos>`_.
|
|
(Contributed by Victor Stinner in :gh:`97681`.)
|
|
|
|
* Remove outdated example scripts of the ``Tools/scripts/`` directory.
|
|
A copy can be found in the `old-demos project
|
|
<https://github.com/gvanrossum/old-demos>`_.
|
|
(Contributed by Victor Stinner in :gh:`97669`.)
|
|
|
|
|
|
Deprecated
|
|
==========
|
|
|
|
* :class:`typing.Hashable` and :class:`typing.Sized` aliases for :class:`collections.abc.Hashable`
|
|
and :class:`collections.abc.Sized`. (:gh:`94309`.)
|
|
|
|
* The :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`.)
|
|
|
|
* The 3-arg signatures (type, value, traceback) of :meth:`~coroutine.throw`,
|
|
:meth:`~generator.throw` and :meth:`~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`.)
|
|
|
|
* :exc:`DeprecationWarning` is now raised when ``__package__`` on a
|
|
module differs from ``__spec__.parent`` (previously it was
|
|
:exc:`ImportWarning`).
|
|
(Contributed by Brett Cannon in :gh:`65961`.)
|
|
|
|
|
|
Pending Removal in Python 3.13
|
|
------------------------------
|
|
|
|
The following modules and APIs have been deprecated in earlier Python releases,
|
|
and will be removed in Python 3.13.
|
|
|
|
Modules (see :pep:`594`):
|
|
|
|
* :mod:`aifc`
|
|
* :mod:`audioop`
|
|
* :mod:`cgi`
|
|
* :mod:`cgitb`
|
|
* :mod:`chunk`
|
|
* :mod:`crypt`
|
|
* :mod:`imghdr`
|
|
* :mod:`mailcap`
|
|
* :mod:`msilib`
|
|
* :mod:`nis`
|
|
* :mod:`nntplib`
|
|
* :mod:`ossaudiodev`
|
|
* :mod:`pipes`
|
|
* :mod:`sndhdr`
|
|
* :mod:`spwd`
|
|
* :mod:`sunau`
|
|
* :mod:`telnetlib`
|
|
* :mod:`uu`
|
|
* :mod:`xdrlib`
|
|
|
|
APIs:
|
|
|
|
* :class:`configparser.LegacyInterpolation` (:gh:`90765`)
|
|
* :func:`locale.getdefaultlocale` (:gh:`90817`)
|
|
* :meth:`turtle.RawTurtle.settiltangle` (:gh:`50096`)
|
|
* :func:`unittest.findTestCases` (:gh:`50096`)
|
|
* :func:`unittest.makeSuite` (:gh:`50096`)
|
|
* :func:`unittest.getTestCaseNames` (:gh:`50096`)
|
|
* :class:`webbrowser.MacOSX` (:gh:`86421`)
|
|
|
|
Pending Removal in Python 3.14
|
|
==============================
|
|
|
|
* Deprecated the following :mod:`importlib.abc` 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.TraversableResources`
|
|
* :class:`importlib.resources.abc.Traversable`
|
|
* :class:`importlib.resources.abc.TraversableResources`
|
|
|
|
(Contributed by Jason R. Coombs and Hugo van Kemenade in :gh:`93963`.)
|
|
|
|
* Creating :c:data:`immutable types <Py_TPFLAGS_IMMUTABLETYPE>` with mutable
|
|
bases using the C API.
|
|
|
|
* ``__package__`` and ``__cached__`` will cease to be set or taken
|
|
into consideration by the import system (:gh:`97879`).
|
|
|
|
|
|
Pending Removal in Future Versions
|
|
----------------------------------
|
|
|
|
The following APIs were deprecated in earlier Python versions and will be removed,
|
|
although there is currently no date scheduled for their removal.
|
|
|
|
* :class:`typing.Text` (:gh:`92332`)
|
|
|
|
* Currently Python accepts numeric literals immediately followed by keywords,
|
|
for example ``0in x``, ``1or x``, ``0if 1else 2``. It allows confusing
|
|
and ambiguous expressions like ``[0x1for x in y]`` (which can be
|
|
interpreted as ``[0x1 for x in y]`` or ``[0x1f or x in y]``).
|
|
A syntax warning is raised if the numeric literal is
|
|
immediately followed by one of keywords :keyword:`and`, :keyword:`else`,
|
|
:keyword:`for`, :keyword:`if`, :keyword:`in`, :keyword:`is` and :keyword:`or`.
|
|
In a future release it will be changed to a syntax error. (:gh:`87999`)
|
|
|
|
|
|
Removed
|
|
=======
|
|
|
|
* Remove the ``distutils`` package. It was deprecated in Python 3.10 by
|
|
:pep:`632` "Deprecate distutils module". For projects still using
|
|
``distutils`` and cannot be updated to something else, the ``setuptools``
|
|
project can be installed: it still provides ``distutils``.
|
|
(Contributed by Victor Stinner in :gh:`92584`.)
|
|
|
|
* Removed many old deprecated :mod:`unittest` features:
|
|
|
|
- A number of :class:`~unittest.TestCase` method aliases:
|
|
|
|
============================ =============================== ===============
|
|
Deprecated alias Method Name Deprecated in
|
|
============================ =============================== ===============
|
|
``failUnless`` :meth:`.assertTrue` 3.1
|
|
``failIf`` :meth:`.assertFalse` 3.1
|
|
``failUnlessEqual`` :meth:`.assertEqual` 3.1
|
|
``failIfEqual`` :meth:`.assertNotEqual` 3.1
|
|
``failUnlessAlmostEqual`` :meth:`.assertAlmostEqual` 3.1
|
|
``failIfAlmostEqual`` :meth:`.assertNotAlmostEqual` 3.1
|
|
``failUnlessRaises`` :meth:`.assertRaises` 3.1
|
|
``assert_`` :meth:`.assertTrue` 3.2
|
|
``assertEquals`` :meth:`.assertEqual` 3.2
|
|
``assertNotEquals`` :meth:`.assertNotEqual` 3.2
|
|
``assertAlmostEquals`` :meth:`.assertAlmostEqual` 3.2
|
|
``assertNotAlmostEquals`` :meth:`.assertNotAlmostEqual` 3.2
|
|
``assertRegexpMatches`` :meth:`.assertRegex` 3.2
|
|
``assertRaisesRegexp`` :meth:`.assertRaisesRegex` 3.2
|
|
``assertNotRegexpMatches`` :meth:`.assertNotRegex` 3.5
|
|
============================ =============================== ===============
|
|
|
|
You can use https://github.com/isidentical/teyit to automatically modernise
|
|
your unit tests.
|
|
|
|
- Undocumented and broken :class:`~unittest.TestCase` method
|
|
``assertDictContainsSubset`` (deprecated in Python 3.2).
|
|
|
|
- Undocumented :meth:`TestLoader.loadTestsFromModule
|
|
<unittest.TestLoader.loadTestsFromModule>` parameter *use_load_tests*
|
|
(deprecated and ignored since Python 3.2).
|
|
|
|
- An alias of the :class:`~unittest.TextTestResult` class:
|
|
``_TextTestResult`` (deprecated in Python 3.2).
|
|
|
|
(Contributed by Serhiy Storchaka in :issue:`45162`.)
|
|
|
|
* Several names deprecated in the :mod:`configparser` way back in 3.2 have
|
|
been removed per :gh:`89336`:
|
|
|
|
* :class:`configparser.ParsingError` no longer has a ``filename`` attribute
|
|
or argument. Use the ``source`` attribute and argument instead.
|
|
* :mod:`configparser` no longer has a ``SafeConfigParser`` class. Use the
|
|
shorter :class:`~configparser.ConfigParser` name instead.
|
|
* :class:`configparser.ConfigParser` no longer has a ``readfp`` method.
|
|
Use :meth:`~configparser.ConfigParser.read_file` instead.
|
|
|
|
* The following undocumented :mod:`sqlite3` features, deprecated in Python
|
|
3.10, are now removed:
|
|
|
|
* ``sqlite3.enable_shared_cache()``
|
|
* ``sqlite3.OptimizedUnicode``
|
|
|
|
If a shared cache must be used, open the database in URI mode using the
|
|
``cache=shared`` query parameter.
|
|
|
|
The ``sqlite3.OptimizedUnicode`` text factory has been an alias for
|
|
:class:`str` since Python 3.3. Code that previously set the text factory to
|
|
``OptimizedUnicode`` can either use ``str`` explicitly, or rely on the
|
|
default value which is also ``str``.
|
|
|
|
(Contributed by Erlend E. Aasland in :gh:`92548`.)
|
|
|
|
* ``smtpd`` has been removed according to the schedule in :pep:`594`,
|
|
having been deprecated in Python 3.4.7 and 3.5.4.
|
|
Use aiosmtpd_ PyPI module or any other
|
|
:mod:`asyncio`-based server instead.
|
|
(Contributed by Oleg Iarygin in :gh:`93243`.)
|
|
|
|
.. _aiosmtpd: https://pypi.org/project/aiosmtpd/
|
|
|
|
* ``asynchat`` and ``asyncore`` have been removed
|
|
according to the schedule in :pep:`594`,
|
|
having been deprecated in Python 3.6.
|
|
Use :mod:`asyncio` instead.
|
|
(Contributed by Nikita Sobolev in :gh:`96580`.)
|
|
|
|
* Remove ``io.OpenWrapper`` and ``_pyio.OpenWrapper``, deprecated in Python
|
|
3.10: just use :func:`open` instead. The :func:`open` (:func:`io.open`)
|
|
function is a built-in function. Since Python 3.10, :func:`_pyio.open` is
|
|
also a static method.
|
|
(Contributed by Victor Stinner in :gh:`94169`.)
|
|
|
|
* Remove the :func:`ssl.RAND_pseudo_bytes` function, deprecated in Python 3.6:
|
|
use :func:`os.urandom` or :func:`ssl.RAND_bytes` instead.
|
|
(Contributed by Victor Stinner in :gh:`94199`.)
|
|
|
|
* :mod:`gzip`: Remove the ``filename`` attribute of :class:`gzip.GzipFile`,
|
|
deprecated since Python 2.6, use the :attr:`~gzip.GzipFile.name` attribute
|
|
instead. In write mode, the ``filename`` attribute added ``'.gz'`` file
|
|
extension if it was not present.
|
|
(Contributed by Victor Stinner in :gh:`94196`.)
|
|
|
|
* Remove the :func:`ssl.match_hostname` function. The
|
|
:func:`ssl.match_hostname` was deprecated in Python 3.7. OpenSSL performs
|
|
hostname matching since Python 3.7, Python no longer uses the
|
|
:func:`ssl.match_hostname` function.
|
|
(Contributed by Victor Stinner in :gh:`94199`.)
|
|
|
|
* Remove the :func:`locale.format` function, deprecated in Python 3.7:
|
|
use :func:`locale.format_string` instead.
|
|
(Contributed by Victor Stinner in :gh:`94226`.)
|
|
|
|
* :mod:`hashlib`: Remove the pure Python implementation of
|
|
:func:`hashlib.pbkdf2_hmac()`, deprecated in Python 3.10. Python 3.10 and
|
|
newer requires OpenSSL 1.1.1 (:pep:`644`): this OpenSSL version provides
|
|
a C implementation of :func:`~hashlib.pbkdf2_hmac()` which is faster.
|
|
(Contributed by Victor Stinner in :gh:`94199`.)
|
|
|
|
* :mod:`xml.etree`: Remove the ``ElementTree.Element.copy()`` method of the
|
|
pure Python implementation, deprecated in Python 3.10, use the
|
|
:func:`copy.copy` function instead. The C implementation of :mod:`xml.etree`
|
|
has no ``copy()`` method, only a ``__copy__()`` method.
|
|
(Contributed by Victor Stinner in :gh:`94383`.)
|
|
|
|
* :mod:`zipimport`: Remove ``find_loader()`` and ``find_module()`` methods,
|
|
deprecated in Python 3.10: use the ``find_spec()`` method instead. See
|
|
:pep:`451` for the rationale.
|
|
(Contributed by Victor Stinner in :gh:`94379`.)
|
|
|
|
* Remove the :func:`ssl.wrap_socket` function, deprecated in Python 3.7:
|
|
instead, create a :class:`ssl.SSLContext` object and call its
|
|
:class:`ssl.SSLContext.wrap_socket` method. Any package that still uses
|
|
:func:`ssl.wrap_socket` is broken and insecure. The function neither sends a
|
|
SNI TLS extension nor validates server hostname. Code is subject to `CWE-295
|
|
<https://cwe.mitre.org/data/definitions/295.html>`_: Improper Certificate
|
|
Validation.
|
|
(Contributed by Victor Stinner in :gh:`94199`.)
|
|
|
|
* Many previously deprecated cleanups in :mod:`importlib` have now been
|
|
completed:
|
|
|
|
* References to, and support for ``module_repr()`` has been eradicated.
|
|
|
|
|
|
* ``importlib.util.set_package`` has been removed.
|
|
(Contributed by Brett Cannon in :gh:`65961`.)
|
|
|
|
* Removed the ``suspicious`` rule from the documentation Makefile, and
|
|
removed ``Doc/tools/rstlint.py``, both in favor of `sphinx-lint
|
|
<https://github.com/sphinx-contrib/sphinx-lint>`_.
|
|
(Contributed by Julien Palard in :gh:`98179`.)
|
|
|
|
* Remove the *keyfile*, *certfile* and *check_hostname* parameters, deprecated
|
|
since Python 3.6, in modules: :mod:`ftplib`, :mod:`http.client`,
|
|
:mod:`imaplib`, :mod:`poplib` and :mod:`smtplib`. Use the *context* parameter
|
|
(*ssl_context* in :mod:`imaplib`) instead.
|
|
(Contributed by Victor Stinner in :gh:`94172`.)
|
|
|
|
* :mod:`ftplib`: Remove the ``FTP_TLS.ssl_version`` class attribute: use the
|
|
*context* parameter instead.
|
|
(Contributed by Victor Stinner in :gh:`94172`.)
|
|
|
|
|
|
Porting to Python 3.12
|
|
======================
|
|
|
|
This section lists previously described changes and other bugfixes
|
|
that may require changes to your code.
|
|
|
|
Changes in the Python API
|
|
-------------------------
|
|
|
|
* More strict rules are now applied for numerical group references and
|
|
group names in regular expressions.
|
|
Only sequence of ASCII digits is now accepted as a numerical reference.
|
|
The group name in bytes patterns and replacement strings can now only
|
|
contain ASCII letters and digits and underscore.
|
|
(Contributed by Serhiy Storchaka in :gh:`91760`.)
|
|
|
|
* Removed randrange() functionality deprecated since Python 3.10. Formerly,
|
|
randrange(10.0) losslessly converted to randrange(10). Now, it raises a
|
|
TypeError. Also, the exception raised for non-integral values such as
|
|
randrange(10.5) or randrange('10') has been changed from ValueError to
|
|
TypeError. This also prevents bugs where ``randrange(1e25)`` would silently
|
|
select from a larger range than ``randrange(10**25)``.
|
|
(Originally suggested by Serhiy Storchaka gh-86388.)
|
|
|
|
* :class:`argparse.ArgumentParser` changed encoding and error handler
|
|
for reading arguments from file (e.g. ``fromfile_prefix_chars`` option)
|
|
from default text encoding (e.g. :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>`)
|
|
to :term:`filesystem encoding and error handler`.
|
|
Argument files should be encoded in UTF-8 instead of ANSI Codepage on Windows.
|
|
|
|
* Removed the ``asyncore``-based ``smtpd`` module deprecated in Python 3.4.7
|
|
and 3.5.4. A recommended replacement is the
|
|
:mod:`asyncio`-based aiosmtpd_ PyPI module.
|
|
|
|
* :func:`shlex.split`: Passing ``None`` for *s* argument now raises an
|
|
exception, rather than reading :data:`sys.stdin`. The feature was deprecated
|
|
in Python 3.9.
|
|
(Contributed by Victor Stinner in :gh:`94352`.)
|
|
|
|
* The :mod:`os` module no longer accepts bytes-like paths, like
|
|
:class:`bytearray` and :class:`memoryview` types: only the exact
|
|
:class:`bytes` type is accepted for bytes strings.
|
|
(Contributed by Victor Stinner in :gh:`98393`.)
|
|
|
|
|
|
Build Changes
|
|
=============
|
|
|
|
* Python no longer uses ``setup.py`` to build shared C extension modules.
|
|
Build parameters like headers and libraries are detected in ``configure``
|
|
script. Extensions are built by ``Makefile``. Most extensions use
|
|
``pkg-config`` and fall back to manual detection.
|
|
(Contributed by Christian Heimes in :gh:`93939`.)
|
|
|
|
* ``va_start()`` with two parameters, like ``va_start(args, format),``
|
|
is now required to build Python.
|
|
``va_start()`` is no longer called with a single parameter.
|
|
(Contributed by Kumar Aditya in :gh:`93207`.)
|
|
|
|
* CPython now uses the ThinLTO option as the default link time optimization policy
|
|
if the Clang compiler accepts the flag.
|
|
(Contributed by Dong-hee Na in :gh:`89536`.)
|
|
|
|
* Add ``COMPILEALL_OPTS`` variable in Makefile to override :mod:`compileall`
|
|
options (default: ``-j0``) in ``make install``. Also merged the 3
|
|
``compileall`` commands into a single command to build .pyc files for all
|
|
optimization levels (0, 1, 2) at once.
|
|
(Contributed by Victor Stinner in :gh:`99289`.)
|
|
|
|
|
|
C API Changes
|
|
=============
|
|
|
|
New Features
|
|
------------
|
|
|
|
* Added the new limited C API function :c:func:`PyType_FromMetaclass`,
|
|
which generalizes the existing :c:func:`PyType_FromModuleAndSpec` using
|
|
an additional metaclass argument.
|
|
(Contributed by Wenzel Jakob in :gh:`93012`.)
|
|
|
|
* API for creating objects that can be called using
|
|
:ref:`the vectorcall protocol <vectorcall>` was added to the
|
|
:ref:`Limited API <stable>`:
|
|
|
|
* :const:`Py_TPFLAGS_HAVE_VECTORCALL`
|
|
* :c:func:`PyVectorcall_NARGS`
|
|
* :c:func:`PyVectorcall_Call`
|
|
* :c:type:`vectorcallfunc`
|
|
|
|
The :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
|
|
when the class's :py:meth:`~object.__call__` method is reassigned.
|
|
This makes vectorcall safe to use with mutable types (i.e. heap types
|
|
without the :const:`immutable <Py_TPFLAGS_IMMUTABLETYPE>` flag).
|
|
Mutable types that do not override :c:member:`~PyTypeObject.tp_call` now
|
|
inherit the ``Py_TPFLAGS_HAVE_VECTORCALL`` flag.
|
|
(Contributed by Petr Viktorin in :gh:`93274`.)
|
|
|
|
The :const:`Py_TPFLAGS_MANAGED_DICT` and :const:`Py_TPFLAGS_MANAGED_WEAKREF`
|
|
flags have been added. This allows extensions classes to support object
|
|
``__dict__`` and weakrefs with less bookkeeping,
|
|
using less memory and with faster access.
|
|
|
|
* API for performing calls using
|
|
:ref:`the vectorcall protocol <vectorcall>` was added to the
|
|
:ref:`Limited API <stable>`:
|
|
|
|
* :c:func:`PyObject_Vectorcall`
|
|
* :c:func:`PyObject_VectorcallMethod`
|
|
* :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`
|
|
|
|
This means that both the incoming and outgoing ends of the vector call
|
|
protocol are now available in the :ref:`Limited API <stable>`. (Contributed
|
|
by Wenzel Jakob in :gh:`98586`.)
|
|
|
|
* Added two new public functions,
|
|
:c:func:`PyEval_SetProfileAllThreads` and
|
|
:c:func:`PyEval_SetTraceAllThreads`, that allow to set tracing and profiling
|
|
functions in all running threads in addition to the calling one. (Contributed
|
|
by Pablo Galindo in :gh:`93503`.)
|
|
|
|
* Added new function :c:func:`PyFunction_SetVectorcall` to the C API
|
|
which sets the vectorcall field of a given :c:type:`PyFunctionObject`.
|
|
(Contributed by Andrew Frost in :gh:`92257`.)
|
|
|
|
* The C API now permits registering callbacks via :c:func:`PyDict_AddWatcher`,
|
|
:c:func:`PyDict_AddWatch` and related APIs to be called whenever a dictionary
|
|
is modified. This is intended for use by optimizing interpreters, JIT
|
|
compilers, or debuggers.
|
|
(Contributed by Carl Meyer in :gh:`91052`.)
|
|
|
|
* Added :c:func:`PyType_AddWatcher` and :c:func:`PyType_Watch` API to register
|
|
callbacks to receive notification on changes to a type.
|
|
(Contributed by Carl Meyer in :gh:`91051`.)
|
|
|
|
|
|
* Add :c:func:`PyFrame_GetVar` and :c:func:`PyFrame_GetVarString` functions to
|
|
get a frame variable by its name.
|
|
(Contributed by Victor Stinner in :gh:`91248`.)
|
|
|
|
Porting to Python 3.12
|
|
----------------------
|
|
|
|
* Legacy Unicode APIs based on ``Py_UNICODE*`` representation has been removed.
|
|
Please migrate to APIs based on UTF-8 or ``wchar_t*``.
|
|
|
|
* Argument parsing functions like :c:func:`PyArg_ParseTuple` doesn't support
|
|
``Py_UNICODE*`` based format (e.g. ``u``, ``Z``) anymore. Please migrate
|
|
to other formats for Unicode like ``s``, ``z``, ``es``, and ``U``.
|
|
|
|
* ``tp_weaklist`` for all static builtin types is always ``NULL``.
|
|
This is an internal-only field on ``PyTypeObject``
|
|
but we're pointing out the change in case someone happens to be
|
|
accessing the field directly anyway. To avoid breakage, consider
|
|
using the existing public C-API instead, or, if necessary, the
|
|
(internal-only) ``_PyObject_GET_WEAKREFS_LISTPTR()`` macro.
|
|
|
|
* This internal-only :c:member:`PyTypeObject.tp_subclasses` may now not be
|
|
a valid object pointer. Its type was changed to :c:expr:`void *` to
|
|
reflect this. We mention this in case someone happens to be accessing the
|
|
internal-only field directly.
|
|
|
|
To get a list of subclasses, call the Python method
|
|
:py:meth:`~class.__subclasses__` (using :c:func:`PyObject_CallMethod`,
|
|
for example).
|
|
|
|
* An unrecognized format character in :c:func:`PyUnicode_FromFormat` and
|
|
:c:func:`PyUnicode_FromFormatV` now sets a :exc:`SystemError`.
|
|
In previous versions it caused all the rest of the format string to be
|
|
copied as-is to the result string, and any extra arguments discarded.
|
|
(Contributed by Serhiy Storchaka in :gh:`95781`.)
|
|
|
|
* Fixed wrong sign placement in :c:func:`PyUnicode_FromFormat` and
|
|
:c:func:`PyUnicode_FromFormatV`.
|
|
(Contributed by Philip Georgi in :gh:`95504`.)
|
|
|
|
* Extension classes wanting to add a ``__dict__`` or weak reference slot
|
|
should use :const:`Py_TPFLAGS_MANAGED_DICT` and
|
|
:const:`Py_TPFLAGS_MANAGED_WEAKREF` instead of ``tp_dictoffset`` and
|
|
``tp_weaklistoffset``, respectively.
|
|
The use of ``tp_dictoffset`` and ``tp_weaklistoffset`` is still
|
|
supported, but does not fully support multiple inheritance
|
|
(:gh:`95589`), and performance may be worse.
|
|
Classes declaring :const:`Py_TPFLAGS_MANAGED_DICT` should call
|
|
:c:func:`_PyObject_VisitManagedDict` and :c:func:`_PyObject_ClearManagedDict`
|
|
to traverse and clear their instance's dictionaries.
|
|
To clear weakrefs, call :c:func:`PyObject_ClearWeakRefs`, as before.
|
|
|
|
* The :c:func:`PyUnicode_FSDecoder` function no longer accepts bytes-like
|
|
paths, like :class:`bytearray` and :class:`memoryview` types: only the exact
|
|
:class:`bytes` type is accepted for bytes strings.
|
|
(Contributed by Victor Stinner in :gh:`98393`.)
|
|
|
|
* The :c:macro:`Py_CLEAR`, :c:macro:`Py_SETREF` and :c:macro:`Py_XSETREF`
|
|
macros now only evaluate their argument once. If the argument has side
|
|
effects, these side effects are no longer duplicated.
|
|
(Contributed by Victor Stinner in :gh:`98724`.)
|
|
|
|
Deprecated
|
|
----------
|
|
|
|
* Deprecate global configuration variable:
|
|
|
|
* :c:var:`Py_DebugFlag`: use :c:member:`PyConfig.parser_debug`
|
|
* :c:var:`Py_VerboseFlag`: use :c:member:`PyConfig.verbose`
|
|
* :c:var:`Py_QuietFlag`: use :c:member:`PyConfig.quiet`
|
|
* :c:var:`Py_InteractiveFlag`: use :c:member:`PyConfig.interactive`
|
|
* :c:var:`Py_InspectFlag`: use :c:member:`PyConfig.inspect`
|
|
* :c:var:`Py_OptimizeFlag`: use :c:member:`PyConfig.optimization_level`
|
|
* :c:var:`Py_NoSiteFlag`: use :c:member:`PyConfig.site_import`
|
|
* :c:var:`Py_BytesWarningFlag`: use :c:member:`PyConfig.bytes_warning`
|
|
* :c:var:`Py_FrozenFlag`: use :c:member:`PyConfig.pathconfig_warnings`
|
|
* :c:var:`Py_IgnoreEnvironmentFlag`: use :c:member:`PyConfig.use_environment`
|
|
* :c:var:`Py_DontWriteBytecodeFlag`: use :c:member:`PyConfig.write_bytecode`
|
|
* :c:var:`Py_NoUserSiteDirectory`: use :c:member:`PyConfig.user_site_directory`
|
|
* :c:var:`Py_UnbufferedStdioFlag`: use :c:member:`PyConfig.buffered_stdio`
|
|
* :c:var:`Py_HashRandomizationFlag`: use :c:member:`PyConfig.use_hash_seed`
|
|
and :c:member:`PyConfig.hash_seed`
|
|
* :c:var:`Py_IsolatedFlag`: use :c:member:`PyConfig.isolated`
|
|
* :c:var:`Py_LegacyWindowsFSEncodingFlag`: use :c:member:`PyConfig.legacy_windows_fs_encoding`
|
|
* :c:var:`Py_LegacyWindowsStdioFlag`: use :c:member:`PyConfig.legacy_windows_stdio`
|
|
* :c:var:`Py_FileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding`
|
|
* :c:var:`Py_FileSystemDefaultEncodeErrors`: use :c:member:`PyConfig.filesystem_errors`
|
|
* :c:var:`Py_UTF8Mode`: use :c:member:`PyPreConfig.utf8_mode` (see :c:func:`Py_PreInitialize`)
|
|
|
|
The :c:func:`Py_InitializeFromConfig` API should be used with
|
|
:c:type:`PyConfig` instead.
|
|
(Contributed by Victor Stinner in :gh:`77782`.)
|
|
|
|
* Creating :c:data:`immutable types <Py_TPFLAGS_IMMUTABLETYPE>` with mutable
|
|
bases is deprecated and will be disabled in Python 3.14.
|
|
|
|
|
|
Removed
|
|
-------
|
|
|
|
* Remove the ``token.h`` header file. There was never any public tokenizer C
|
|
API. The ``token.h`` header file was only designed to be used by Python
|
|
internals.
|
|
(Contributed by Victor Stinner in :gh:`92651`.)
|
|
|
|
* Leagcy Unicode APIs has been removed. See :pep:`623` for detail.
|
|
|
|
* :c:macro:`PyUnicode_WCHAR_KIND`
|
|
* :c:func:`PyUnicode_AS_UNICODE`
|
|
* :c:func:`PyUnicode_AsUnicode`
|
|
* :c:func:`PyUnicode_AsUnicodeAndSize`
|
|
* :c:func:`PyUnicode_AS_DATA`
|
|
* :c:func:`PyUnicode_FromUnicode`
|
|
* :c:func:`PyUnicode_GET_SIZE`
|
|
* :c:func:`PyUnicode_GetSize`
|
|
* :c:func:`PyUnicode_GET_DATA_SIZE`
|
|
|
|
* Remove the ``PyUnicode_InternImmortal()`` function and the
|
|
``SSTATE_INTERNED_IMMORTAL`` macro.
|
|
(Contributed by Victor Stinner in :gh:`85858`.)
|
|
|
|
* Remove ``_use_broken_old_ctypes_structure_semantics_`` flag
|
|
from :mod:`ctypes` module.
|
|
(Contributed by Nikita Sobolev in :gh:`99285`.)
|