mirror of https://github.com/python/cpython
2146 lines
87 KiB
ReStructuredText
2146 lines
87 KiB
ReStructuredText
|
|
****************************
|
|
What's New In Python 3.12
|
|
****************************
|
|
|
|
:Editor: TBD
|
|
|
|
.. 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.
|
|
|
|
New grammar features:
|
|
|
|
* :ref:`whatsnew312-pep701`
|
|
|
|
Interpreter improvements:
|
|
|
|
* :ref:`whatsnew312-pep684`
|
|
|
|
* :ref:`whatsnew312-pep669`
|
|
|
|
New typing features:
|
|
|
|
* :ref:`whatsnew312-pep688`
|
|
|
|
* :ref:`whatsnew312-pep692`
|
|
|
|
* :ref:`whatsnew312-pep695`
|
|
|
|
* :ref:`whatsnew312-pep698`
|
|
|
|
Important deprecations, removals or restrictions:
|
|
|
|
* :pep:`623`: Remove wstr from Unicode
|
|
|
|
* :pep:`632`: Remove the ``distutils`` package. See
|
|
`the migration guide <https://peps.python.org/pep-0632/#migration-advice>`_
|
|
for advice on its replacement.
|
|
|
|
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
|
|
============
|
|
|
|
.. _whatsnew312-pep701:
|
|
|
|
PEP 701: Syntactic formalization of f-strings
|
|
---------------------------------------------
|
|
|
|
:pep:`701` lifts some restrictions on the usage of f-strings. Expression components
|
|
inside f-strings can now be any valid Python expression including backslashes,
|
|
unicode escaped sequences, multi-line expressions, comments and strings reusing the
|
|
same quote as the containing f-string. Let's cover these in detail:
|
|
|
|
* Quote reuse: in Python 3.11, reusing the same quotes as the containing f-string
|
|
raises a :exc:`SyntaxError`, forcing the user to either use other available
|
|
quotes (like using double quotes or triple quotes if the f-string uses single
|
|
quotes). In Python 3.12, you can now do things like this:
|
|
|
|
>>> songs = ['Take me back to Eden', 'Alkaline', 'Ascensionism']
|
|
>>> f"This is the playlist: {", ".join(songs)}"
|
|
'This is the playlist: Take me back to Eden, Alkaline, Ascensionism'
|
|
|
|
Note that before this change there was no explicit limit in how f-strings can
|
|
be nested, but the fact that string quotes cannot be reused inside the
|
|
expression component of f-strings made it impossible to nest f-strings
|
|
arbitrarily. In fact, this is the most nested f-string that could be written:
|
|
|
|
>>> f"""{f'''{f'{f"{1+1}"}'}'''}"""
|
|
'2'
|
|
|
|
As now f-strings can contain any valid Python expression inside expression
|
|
components, it is now possible to nest f-strings arbitrarily:
|
|
|
|
>>> f"{f"{f"{f"{f"{f"{1+1}"}"}"}"}"}"
|
|
'2'
|
|
|
|
* Multi-line expressions and comments: In Python 3.11, f-strings expressions
|
|
must be defined in a single line even if outside f-strings expressions could
|
|
span multiple lines (like literal lists being defined over multiple lines),
|
|
making them harder to read. In Python 3.12 you can now define expressions
|
|
spanning multiple lines and include comments on them:
|
|
|
|
>>> f"This is the playlist: {", ".join([
|
|
... 'Take me back to Eden', # My, my, those eyes like fire
|
|
... 'Alkaline', # Not acid nor alkaline
|
|
... 'Ascensionism' # Take to the broken skies at last
|
|
... ])}"
|
|
'This is the playlist: Take me back to Eden, Alkaline, Ascensionism'
|
|
|
|
* Backslashes and unicode characters: before Python 3.12 f-string expressions
|
|
couldn't contain any ``\`` character. This also affected unicode escaped
|
|
sequences (such as ``\N{snowman}``) as these contain the ``\N`` part that
|
|
previously could not be part of expression components of f-strings. Now, you
|
|
can define expressions like this:
|
|
|
|
>>> print(f"This is the playlist: {"\n".join(songs)}")
|
|
This is the playlist: Take me back to Eden
|
|
Alkaline
|
|
Ascensionism
|
|
>>> print(f"This is the playlist: {"\N{BLACK HEART SUIT}".join(songs)}")
|
|
This is the playlist: Take me back to Eden♥Alkaline♥Ascensionism
|
|
|
|
See :pep:`701` for more details.
|
|
|
|
As a positive side-effect of how this feature has been implemented (by parsing f-strings
|
|
with the PEG parser (see :pep:`617`), now error messages for f-strings are more precise
|
|
and include the exact location of the error. For example, in Python 3.11, the following
|
|
f-string raises a :exc:`SyntaxError`:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> my_string = f"{x z y}" + f"{1 + 1}"
|
|
File "<stdin>", line 1
|
|
(x z y)
|
|
^^^
|
|
SyntaxError: f-string: invalid syntax. Perhaps you forgot a comma?
|
|
|
|
but the error message doesn't include the exact location of the error within the line and
|
|
also has the expression artificially surrounded by parentheses. In Python 3.12, as f-strings
|
|
are parsed with the PEG parser, error messages can be more precise and show the entire line:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> my_string = f"{x z y}" + f"{1 + 1}"
|
|
File "<stdin>", line 1
|
|
my_string = f"{x z y}" + f"{1 + 1}"
|
|
^^^
|
|
SyntaxError: invalid syntax. Perhaps you forgot a comma?
|
|
|
|
(Contributed by Pablo Galindo, Batuhan Taskaya, Lysandros Nikolaou, Cristián
|
|
Maureira-Fredes and Marta Gómez in :gh:`102856`. PEP written by Pablo Galindo,
|
|
Batuhan Taskaya, Lysandros Nikolaou and Marta Gómez).
|
|
|
|
.. _whatsnew312-pep709:
|
|
|
|
PEP 709: Comprehension inlining
|
|
-------------------------------
|
|
|
|
Dictionary, list, and set comprehensions are now inlined, rather than creating a
|
|
new single-use function object for each execution of the comprehension. This
|
|
speeds up execution of a comprehension by up to 2x.
|
|
|
|
Comprehension iteration variables remain isolated; they don't overwrite a
|
|
variable of the same name in the outer scope, nor are they visible after the
|
|
comprehension. This isolation is now maintained via stack/locals manipulation,
|
|
not via separate function scope.
|
|
|
|
Inlining does result in a few visible behavior changes:
|
|
|
|
* There is no longer a separate frame for the comprehension in tracebacks,
|
|
and tracing/profiling no longer shows the comprehension as a function call.
|
|
* The :mod:`symtable` module will no longer produce child symbol tables for each
|
|
comprehension; instead, the comprehension's locals will be included in the
|
|
parent function's symbol table.
|
|
* Calling :func:`locals` inside a comprehension now includes variables
|
|
from outside the comprehension, and no longer includes the synthetic ``.0``
|
|
variable for the comprehension "argument".
|
|
* A comprehension iterating directly over ``locals()`` (e.g. ``[k for k in
|
|
locals()]``) may see "RuntimeError: dictionary changed size during iteration"
|
|
when run under tracing (e.g. code coverage measurement). This is the same
|
|
behavior already seen in e.g. ``for k in locals():``. To avoid the error, first
|
|
create a list of keys to iterate over: ``keys = list(locals()); [k for k in
|
|
keys]``.
|
|
|
|
Contributed by Carl Meyer and Vladimir Matveev in :pep:`709`.
|
|
|
|
.. _whatsnew312-pep688:
|
|
|
|
PEP 688: Making the buffer protocol accessible in Python
|
|
--------------------------------------------------------
|
|
|
|
:pep:`688` introduces a way to use the :ref:`buffer protocol <bufferobjects>`
|
|
from Python code. Classes that implement the :meth:`~object.__buffer__` method
|
|
are now usable as buffer types.
|
|
|
|
The new :class:`collections.abc.Buffer` ABC provides a standard
|
|
way to represent buffer objects, for example in type annotations.
|
|
The new :class:`inspect.BufferFlags` enum represents the flags that
|
|
can be used to customize buffer creation.
|
|
(Contributed by Jelle Zijlstra in :gh:`102500`.)
|
|
|
|
.. _whatsnew312-pep684:
|
|
|
|
PEP 684: A Per-Interpreter GIL
|
|
------------------------------
|
|
|
|
Sub-interpreters may now be created with a unique GIL per interpreter.
|
|
This allows Python programs to take full advantage of multiple CPU
|
|
cores.
|
|
|
|
Use the new :c:func:`Py_NewInterpreterFromConfig` function to
|
|
create an interpreter with its own GIL::
|
|
|
|
PyInterpreterConfig config = {
|
|
.check_multi_interp_extensions = 1,
|
|
.gil = PyInterpreterConfig_OWN_GIL,
|
|
};
|
|
PyThreadState *tstate = NULL;
|
|
PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);
|
|
if (PyStatus_Exception(status)) {
|
|
return -1;
|
|
}
|
|
/* The new interpeter is now active in the current thread. */
|
|
|
|
For further examples how to use the C-API for sub-interpreters with a
|
|
per-interpreter GIL, see :source:`Modules/_xxsubinterpretersmodule.c`.
|
|
|
|
A Python API is anticipated for 3.13. (See :pep:`554`.)
|
|
|
|
(Contributed by Eric Snow in :gh:`104210`, etc.)
|
|
|
|
.. _whatsnew312-pep669:
|
|
|
|
PEP 669: Low impact monitoring for CPython
|
|
------------------------------------------
|
|
|
|
CPython 3.12 now supports the ability to monitor calls,
|
|
returns, lines, exceptions and other events using instrumentation.
|
|
This means that you only pay for what you use, providing support
|
|
for near-zero overhead debuggers and coverage tools.
|
|
|
|
See :mod:`sys.monitoring` for details.
|
|
|
|
|
|
New Features Related to Type Hints
|
|
==================================
|
|
|
|
This section covers major changes affecting :pep:`484` type hints and
|
|
the :mod:`typing` module.
|
|
|
|
.. _whatsnew312-pep692:
|
|
|
|
PEP 692: Using ``TypedDict`` for more precise ``**kwargs`` typing
|
|
-----------------------------------------------------------------
|
|
|
|
Typing ``**kwargs`` in a function signature as introduced by :pep:`484` allowed
|
|
for valid annotations only in cases where all of the ``**kwargs`` were of the
|
|
same type.
|
|
|
|
This PEP specifies a more precise way of typing ``**kwargs`` by relying on
|
|
typed dictionaries::
|
|
|
|
from typing import TypedDict, Unpack
|
|
|
|
class Movie(TypedDict):
|
|
name: str
|
|
year: int
|
|
|
|
def foo(**kwargs: Unpack[Movie]): ...
|
|
|
|
See :pep:`692` for more details.
|
|
|
|
(Contributed by Franek Magiera in :gh:`103629`.)
|
|
|
|
.. _whatsnew312-pep698:
|
|
|
|
PEP 698: Override Decorator for Static Typing
|
|
---------------------------------------------
|
|
|
|
A new decorator :func:`typing.override` has been added to the :mod:`typing`
|
|
module. It indicates to type checkers that the method is intended to override
|
|
a method in a superclass. This allows type checkers to catch mistakes where
|
|
a method that is intended to override something in a base class
|
|
does not in fact do so.
|
|
|
|
Example::
|
|
|
|
from typing import override
|
|
|
|
class Base:
|
|
def get_color(self) -> str:
|
|
return "blue"
|
|
|
|
class GoodChild(Base):
|
|
@override # ok: overrides Base.get_color
|
|
def get_color(self) -> str:
|
|
return "yellow"
|
|
|
|
class BadChild(Base):
|
|
@override # type checker error: does not override Base.get_color
|
|
def get_colour(self) -> str:
|
|
return "red"
|
|
|
|
(Contributed by Steven Troxler in :gh:`101561`.)
|
|
|
|
.. _whatsnew312-pep695:
|
|
|
|
PEP 695: Type Parameter Syntax
|
|
------------------------------
|
|
|
|
Generic classes and functions under :pep:`484` were declared using a verbose syntax
|
|
that left the scope of type parameters unclear and required explicit declarations of
|
|
variance.
|
|
|
|
:pep:`695` introduces a new, more compact and explicit way to create
|
|
:ref:`generic classes <generic-classes>` and :ref:`functions <generic-functions>`::
|
|
|
|
def max[T](args: Iterable[T]) -> T:
|
|
...
|
|
|
|
class list[T]:
|
|
def __getitem__(self, index: int, /) -> T:
|
|
...
|
|
|
|
def append(self, element: T) -> None:
|
|
...
|
|
|
|
In addition, the PEP introduces a new way to declare :ref:`type aliases <type-aliases>`
|
|
using the :keyword:`type` statement, which creates an instance of
|
|
:class:`~typing.TypeAliasType`::
|
|
|
|
type Point = tuple[float, float]
|
|
|
|
Type aliases can also be :ref:`generic <generic-type-aliases>`::
|
|
|
|
type Point[T] = tuple[T, T]
|
|
|
|
The new syntax allows declaring :class:`~typing.TypeVarTuple`
|
|
and :class:`~typing.ParamSpec` parameters, as well as :class:`~typing.TypeVar`
|
|
parameters with bounds or constraints::
|
|
|
|
type IntFunc[**P] = Callable[P, int] # ParamSpec
|
|
type LabeledTuple[*Ts] = tuple[str, *Ts] # TypeVarTuple
|
|
type HashableSequence[T: Hashable] = Sequence[T] # TypeVar with bound
|
|
type IntOrStrSequence[T: (int, str)] = Sequence[T] # TypeVar with constraints
|
|
|
|
The value of type aliases and the bound and constraints of type variables
|
|
created through this syntax are evaluated only on demand (see
|
|
:ref:`lazy-evaluation`). This means type aliases are able to refer to other
|
|
types defined later in the file.
|
|
|
|
Type parameters declared through a type parameter list are visible within the
|
|
scope of the declaration and any nested scopes, but not in the outer scope. For
|
|
example, they can be used in the type annotations for the methods of a generic
|
|
class or in the class body. However, they cannot be used in the module scope after
|
|
the class is defined. See :ref:`type-params` for a detailed description of the
|
|
runtime semantics of type parameters.
|
|
|
|
In order to support these scoping semantics, a new kind of scope is introduced,
|
|
the :ref:`annotation scope <annotation-scopes>`. Annotation scopes behave for the
|
|
most part like function scopes, but interact differently with enclosing class scopes.
|
|
In Python 3.13, :term:`annotations <annotation>` will also be evaluated in
|
|
annotation scopes.
|
|
|
|
See :pep:`695` for more details.
|
|
|
|
(PEP written by Eric Traut. Implementation by Jelle Zijlstra, Eric Traut,
|
|
and others in :gh:`103764`.)
|
|
|
|
Other Language Changes
|
|
======================
|
|
|
|
* 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`.)
|
|
|
|
* The extraction methods in :mod:`tarfile`, and :func:`shutil.unpack_archive`,
|
|
have a new a *filter* argument that allows limiting tar features than may be
|
|
surprising or dangerous, such as creating files outside the destination
|
|
directory.
|
|
See :ref:`tarfile-extraction-filter` for details.
|
|
In Python 3.14, the default will switch to ``'data'``.
|
|
(Contributed by Petr Viktorin in :pep:`706`.)
|
|
|
|
* :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 of 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`.)
|
|
|
|
* All builtin and extension callables expecting boolean parameters now accept
|
|
arguments of any type instead of just :class:`bool` and :class:`int`.
|
|
(Contributed by Serhiy Storchaka in :gh:`60203`.)
|
|
|
|
* Variables used in the target part of comprehensions that are not stored to
|
|
can now be used in assignment expressions (``:=``).
|
|
For example, in ``[(b := 1) for a, b.prop in some_iter]``, the assignment to
|
|
``b`` is now allowed. Note that assigning to variables stored to in the target
|
|
part of comprehensions (like ``a``) is still disallowed, as per :pep:`572`.
|
|
(Contributed by Nikita Sobolev in :gh:`100581`.)
|
|
|
|
* :class:`slice` objects are now hashable, allowing them to be used as dict keys and
|
|
set items. (Contributed by Will Bradshaw, Furkan Onder, and Raymond Hettinger in :gh:`101264`.)
|
|
|
|
* :func:`sum` now uses Neumaier summation to improve accuracy and commutativity
|
|
when summing floats or mixed ints and floats.
|
|
(Contributed by Raymond Hettinger in :gh:`100425`.)
|
|
|
|
* Exceptions raised in a typeobject's ``__set_name__`` method are no longer
|
|
wrapped by a :exc:`RuntimeError`. Context information is added to the
|
|
exception as a :pep:`678` note. (Contributed by Irit Katriel in :gh:`77757`.)
|
|
|
|
* When a ``try-except*`` construct handles the entire :exc:`ExceptionGroup`
|
|
and raises one other exception, that exception is no longer wrapped in an
|
|
:exc:`ExceptionGroup`. Also changed in version 3.11.4. (Contributed by Irit
|
|
Katriel in :gh:`103590`.)
|
|
|
|
|
|
New Modules
|
|
===========
|
|
|
|
* None.
|
|
|
|
|
|
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
|
|
-------
|
|
|
|
* The performance of writing to sockets in :mod:`asyncio` has been
|
|
significantly improved. ``asyncio`` now avoids unnecessary copying when
|
|
writing to sockets and uses :meth:`~socket.socket.sendmsg` if the platform
|
|
supports it. (Contributed by Kumar Aditya in :gh:`91166`.)
|
|
|
|
* Added :func:`asyncio.eager_task_factory` and :func:`asyncio.create_eager_task_factory`
|
|
functions to allow opting an event loop in to eager task execution,
|
|
making some use-cases 2x to 5x faster.
|
|
(Contributed by Jacob Bower & Itamar O in :gh:`102853`, :gh:`104140`, and :gh:`104138`)
|
|
|
|
* 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`.)
|
|
|
|
* Add C implementation of :func:`asyncio.current_task` for 4x-6x speedup.
|
|
(Contributed by Itamar Ostricher and Pranav Thulasiram Bhat in :gh:`100344`.)
|
|
|
|
* :func:`asyncio.iscoroutine` now returns ``False`` for generators as
|
|
:mod:`asyncio` does not support legacy generator-based coroutines.
|
|
(Contributed by Kumar Aditya in :gh:`102748`.)
|
|
|
|
* :func:`asyncio.wait` and :func:`asyncio.as_completed` now accepts generators
|
|
yielding tasks.
|
|
(Contributed by Kumar Aditya in :gh:`78530`.)
|
|
|
|
calendar
|
|
--------
|
|
|
|
* Add enums :data:`~calendar.Month` and :data:`~calendar.Day`.
|
|
(Contributed by Prince Roshan in :gh:`103636`.)
|
|
|
|
csv
|
|
---
|
|
|
|
* Add :const:`~csv.QUOTE_NOTNULL` and :const:`~csv.QUOTE_STRINGS` flags to
|
|
provide finer grained control of ``None`` and empty strings by
|
|
:class:`~csv.writer` objects.
|
|
|
|
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.
|
|
:opcode:`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`.)
|
|
|
|
fractions
|
|
---------
|
|
|
|
* Objects of type :class:`fractions.Fraction` now support float-style
|
|
formatting. (Contributed by Mark Dickinson in :gh:`100161`.)
|
|
|
|
importlib.resources
|
|
-------------------
|
|
|
|
* :func:`importlib.resources.as_file` now supports resource directories.
|
|
(Contributed by Jason R. Coombs in :gh:`97930`.)
|
|
|
|
inspect
|
|
-------
|
|
|
|
* Add :func:`inspect.markcoroutinefunction` to mark sync functions that return
|
|
a :term:`coroutine` for use with :func:`inspect.iscoroutinefunction`.
|
|
(Contributed Carlton Gibson in :gh:`99247`.)
|
|
|
|
* Add :func:`inspect.getasyncgenstate` and :func:`inspect.getasyncgenlocals`
|
|
for determining the current state of asynchronous generators.
|
|
(Contributed by Thomas Krennwallner in :issue:`35759`.)
|
|
|
|
* The performance of :func:`inspect.getattr_static` has been considerably
|
|
improved. Most calls to the function should be at least 2x faster than they
|
|
were in Python 3.11, and some may be 6x faster or more. (Contributed by Alex
|
|
Waygood in :gh:`103193`.)
|
|
|
|
itertools
|
|
---------
|
|
|
|
* Added :class:`itertools.batched()` for collecting into even-sized
|
|
tuples where the last batch may be shorter than the rest.
|
|
(Contributed by Raymond Hettinger in :gh:`98363`.)
|
|
|
|
math
|
|
----
|
|
|
|
* Added :func:`math.sumprod` for computing a sum of products.
|
|
(Contributed by Raymond Hettinger in :gh:`100485`.)
|
|
|
|
* Extended :func:`math.nextafter` to include a *steps* argument
|
|
for moving up or down multiple steps at a time.
|
|
(By Matthias Goergens, Mark Dickinson, and Raymond Hettinger in :gh:`94906`.)
|
|
|
|
os
|
|
--
|
|
|
|
* Add :const:`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`.)
|
|
|
|
* :class:`os.DirEntry` now includes an :meth:`os.DirEntry.is_junction`
|
|
method to check if the entry is a junction.
|
|
(Contributed by Charles Machalow in :gh:`99547`.)
|
|
|
|
* Add :func:`os.listdrives`, :func:`os.listvolumes` and :func:`os.listmounts`
|
|
functions on Windows for enumerating drives, volumes and mount points.
|
|
(Contributed by Steve Dower in :gh:`102519`.)
|
|
|
|
* :func:`os.stat` and :func:`os.lstat` are now more accurate on Windows.
|
|
The ``st_birthtime`` field will now be filled with the creation time
|
|
of the file, and ``st_ctime`` is deprecated but still contains the
|
|
creation time (but in the future will return the last metadata change,
|
|
for consistency with other platforms). ``st_dev`` may be up to 64 bits
|
|
and ``st_ino`` up to 128 bits depending on your file system, and
|
|
``st_rdev`` is always set to zero rather than incorrect values.
|
|
Both functions may be significantly faster on newer releases of
|
|
Windows. (Contributed by Steve Dower in :gh:`99726`.)
|
|
|
|
os.path
|
|
-------
|
|
|
|
* Add :func:`os.path.isjunction` to check if a given path is a junction.
|
|
(Contributed by Charles Machalow in :gh:`99547`.)
|
|
|
|
* Add :func:`os.path.splitroot` to split a path into a triad
|
|
``(drive, root, tail)``. (Contributed by Barney Gale in :gh:`101000`.)
|
|
|
|
pathlib
|
|
-------
|
|
|
|
* Add support for subclassing :class:`pathlib.PurePath` and
|
|
:class:`~pathlib.Path`, plus their Posix- and Windows-specific variants.
|
|
Subclasses may override the :meth:`~pathlib.PurePath.with_segments` method
|
|
to pass information between path instances.
|
|
|
|
* 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`.)
|
|
|
|
* Add :meth:`pathlib.Path.is_junction` as a proxy to :func:`os.path.isjunction`.
|
|
(Contributed by Charles Machalow in :gh:`99547`.)
|
|
|
|
* Add *case_sensitive* optional parameter to :meth:`pathlib.Path.glob`,
|
|
:meth:`pathlib.Path.rglob` and :meth:`pathlib.PurePath.match` for matching
|
|
the path's case sensitivity, allowing for more precise control over the matching process.
|
|
|
|
pdb
|
|
---
|
|
|
|
* Add convenience variables to hold values temporarily for debug session
|
|
and provide quick access to values like the current frame or the return
|
|
value.
|
|
(Contributed by Tian Gao in :gh:`103693`.)
|
|
|
|
random
|
|
------
|
|
|
|
* Added :func:`random.binomialvariate`.
|
|
(Contributed by Raymond Hettinger in :gh:`81620`.)
|
|
|
|
* Added a default of ``lamb=1.0`` to :func:`random.expovariate`.
|
|
(Contributed by Raymond Hettinger in :gh:`100234`.)
|
|
|
|
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`.)
|
|
|
|
* :func:`shutil.rmtree` now accepts a new argument *onexc* which is an
|
|
error handler like *onerror* but which expects an exception instance
|
|
rather than a *(typ, val, tb)* triplet. *onerror* is deprecated and
|
|
will be removed in Python 3.14.
|
|
(Contributed by Irit Katriel in :gh:`102828`.)
|
|
|
|
* :func:`shutil.which` now consults the *PATHEXT* environment variable to
|
|
find matches within *PATH* on Windows even when the given *cmd* includes
|
|
a directory component.
|
|
(Contributed by Charles Machalow in :gh:`103179`.)
|
|
|
|
:func:`shutil.which` will call ``NeedCurrentDirectoryForExePathW`` when
|
|
querying for executables on Windows to determine if the current working
|
|
directory should be prepended to the search path.
|
|
(Contributed by Charles Machalow in :gh:`103179`.)
|
|
|
|
:func:`shutil.which` will return a path matching the *cmd* with a component
|
|
from ``PATHEXT`` prior to a direct match elsewhere in the search path on
|
|
Windows.
|
|
(Contributed by Charles Machalow in :gh:`103179`.)
|
|
|
|
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`.)
|
|
|
|
* Add *entrypoint* keyword-only parameter to
|
|
:meth:`~sqlite3.Connection.load_extension`,
|
|
for overriding the SQLite extension entry point.
|
|
(Contributed by Erlend E. Aasland in :gh:`103015`.)
|
|
|
|
* Add :meth:`~sqlite3.Connection.getconfig` and
|
|
:meth:`~sqlite3.Connection.setconfig` to :class:`~sqlite3.Connection`
|
|
to make configuration changes to a database connection.
|
|
(Contributed by Erlend E. Aasland in :gh:`103489`.)
|
|
|
|
statistics
|
|
----------
|
|
|
|
* Extended :func:`statistics.correlation` to include as a ``ranked`` method
|
|
for computing the Spearman correlation of ranked data.
|
|
(Contributed by Raymond Hettinger in :gh:`95861`.)
|
|
|
|
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`.)
|
|
|
|
* Add :data:`sys.last_exc` which holds the last unhandled exception that
|
|
was raised (for post-mortem debugging use cases). Deprecate the
|
|
three fields that have the same information in its legacy form:
|
|
:data:`sys.last_type`, :data:`sys.last_value` and :data:`sys.last_traceback`.
|
|
(Contributed by Irit Katriel in :gh:`102778`.)
|
|
|
|
* :func:`sys._current_exceptions` now returns a mapping from thread-id to an
|
|
exception instance, rather than to a ``(typ, exc, tb)`` tuple.
|
|
(Contributed by Irit Katriel in :gh:`103176`.)
|
|
|
|
* :func:`sys.setrecursionlimit` and :func:`sys.getrecursionlimit`.
|
|
The recursion limit now applies only to Python code. Builtin functions do
|
|
not use the recursion limit, but are protected by a different mechanism
|
|
that prevents recursion from causing a virtual machine crash.
|
|
|
|
tempfile
|
|
--------
|
|
|
|
* The :class:`tempfile.NamedTemporaryFile` function has a new optional parameter
|
|
*delete_on_close* (Contributed by Evgeny Zorin in :gh:`58451`.)
|
|
* :func:`tempfile.mkdtemp` now always returns an absolute path, even if the
|
|
argument provided to the *dir* parameter is a relative path.
|
|
|
|
.. _whatsnew-typing-py312:
|
|
|
|
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`.)
|
|
|
|
tkinter
|
|
-------
|
|
|
|
* ``tkinter.Canvas.coords()`` now flattens its arguments.
|
|
It now accepts not only coordinates as separate arguments
|
|
(``x1, y1, x2, y2, ...``) and a sequence of coordinates
|
|
(``[x1, y1, x2, y2, ...]``), but also coordinates grouped in pairs
|
|
(``(x1, y1), (x2, y2), ...`` and ``[(x1, y1), (x2, y2), ...]``),
|
|
like ``create_*()`` methods.
|
|
(Contributed by Serhiy Storchaka in :gh:`94473`.)
|
|
|
|
tokenize
|
|
--------
|
|
|
|
* The :mod:`tokenize` module includes the changes introduced in :pep:`701`. (
|
|
Contributed by Marta Gómez Macías and Pablo Galindo in :gh:`102856`.)
|
|
See :ref:`whatsnew312-porting-to-python312` for more information on the
|
|
changes to the :mod:`tokenize` module.
|
|
|
|
types
|
|
-----
|
|
|
|
* Add :func:`types.get_original_bases` to allow for further introspection of
|
|
:ref:`user-defined-generics` when subclassed. (Contributed by
|
|
James Hilton-Balfe and Alex Waygood in :gh:`101827`.)
|
|
|
|
typing
|
|
------
|
|
|
|
* :func:`isinstance` checks against
|
|
:func:`runtime-checkable protocols <typing.runtime_checkable>` now use
|
|
:func:`inspect.getattr_static` rather than :func:`hasattr` to lookup whether
|
|
attributes exist. This means that descriptors and :meth:`~object.__getattr__`
|
|
methods are no longer unexpectedly evaluated during ``isinstance()`` checks
|
|
against runtime-checkable protocols. However, it may also mean that some
|
|
objects which used to be considered instances of a runtime-checkable protocol
|
|
may no longer be considered instances of that protocol on Python 3.12+, and
|
|
vice versa. Most users are unlikely to be affected by this change.
|
|
(Contributed by Alex Waygood in :gh:`102433`.)
|
|
|
|
* The members of a runtime-checkable protocol are now considered "frozen" at
|
|
runtime as soon as the class has been created. Monkey-patching attributes
|
|
onto a runtime-checkable protocol will still work, but will have no impact on
|
|
:func:`isinstance` checks comparing objects to the protocol. For example::
|
|
|
|
>>> from typing import Protocol, runtime_checkable
|
|
>>> @runtime_checkable
|
|
... class HasX(Protocol):
|
|
... x = 1
|
|
...
|
|
>>> class Foo: ...
|
|
...
|
|
>>> f = Foo()
|
|
>>> isinstance(f, HasX)
|
|
False
|
|
>>> f.x = 1
|
|
>>> isinstance(f, HasX)
|
|
True
|
|
>>> HasX.y = 2
|
|
>>> isinstance(f, HasX) # unchanged, even though HasX now also has a "y" attribute
|
|
True
|
|
|
|
This change was made in order to speed up ``isinstance()`` checks against
|
|
runtime-checkable protocols.
|
|
|
|
* The performance profile of :func:`isinstance` checks against
|
|
:func:`runtime-checkable protocols <typing.runtime_checkable>` has changed
|
|
significantly. Most ``isinstance()`` checks against protocols with only a few
|
|
members should be at least 2x faster than in 3.11, and some may be 20x
|
|
faster or more. However, ``isinstance()`` checks against protocols with fourteen
|
|
or more members may be slower than in Python 3.11. (Contributed by Alex
|
|
Waygood in :gh:`74690` and :gh:`103193`.)
|
|
|
|
* All :data:`typing.TypedDict` and :data:`typing.NamedTuple` classes now have the
|
|
``__orig_bases__`` attribute. (Contributed by Adrian Garcia Badaracco in
|
|
:gh:`103699`.)
|
|
|
|
* Add ``frozen_default`` parameter to :func:`typing.dataclass_transform`.
|
|
(Contributed by Erik De Bonte in :gh:`99957`.)
|
|
|
|
unicodedata
|
|
-----------
|
|
|
|
* The Unicode database has been updated to version 15.0.0. (Contributed by
|
|
Benjamin Peterson in :gh:`96734`).
|
|
|
|
unittest
|
|
--------
|
|
|
|
Added ``--durations`` command line option, showing the N slowest test cases::
|
|
|
|
python3 -m unittest --durations=3 lib.tests.test_threading
|
|
.....
|
|
Slowest test durations
|
|
----------------------------------------------------------------------
|
|
1.210s test_timeout (Lib.test.test_threading.BarrierTests)
|
|
1.003s test_default_timeout (Lib.test.test_threading.BarrierTests)
|
|
0.518s test_timeout (Lib.test.test_threading.EventTests)
|
|
|
|
(0.000 durations hidden. Use -v to show these durations.)
|
|
----------------------------------------------------------------------
|
|
Ran 158 tests in 9.869s
|
|
|
|
OK (skipped=3)
|
|
|
|
(Contributed by Giampaolo Rodola in :issue:`4080`)
|
|
|
|
uuid
|
|
----
|
|
|
|
* Add a :ref:`command-line interface <uuid-cli>`.
|
|
(Contributed by Adam Chhina in :gh:`88597`.)
|
|
|
|
|
|
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` and tuned by Dong-hee Na in :gh:`101525`)
|
|
|
|
* 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`.)
|
|
|
|
* Speed up :class:`asyncio.Task` creation by deferring expensive string formatting.
|
|
(Contributed by Itamar O in :gh:`103793`.)
|
|
|
|
* The :func:`tokenize.tokenize` and :func:`tokenize.generate_tokens` functions are
|
|
up to 64% faster as a side effect of the changes required to cover :pep:`701` in
|
|
the :mod:`tokenize` module. (Contributed by Marta Gómez Macías and Pablo Galindo
|
|
in :gh:`102856`.)
|
|
|
|
* Speed up :func:`super` method calls and attribute loads via the
|
|
new :opcode:`LOAD_SUPER_ATTR` instruction. (Contributed by Carl Meyer and
|
|
Vladimir Matveev in :gh:`103497`.)
|
|
|
|
|
|
CPython bytecode changes
|
|
========================
|
|
|
|
* Remove 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`.)
|
|
|
|
* Remove the :opcode:`!JUMP_IF_FALSE_OR_POP` and :opcode:`!JUMP_IF_TRUE_OR_POP`
|
|
instructions. (Contributed by Irit Katriel in :gh:`102859`.)
|
|
|
|
* Removed the :opcode:`!PRECALL` instruction. (Contributed by Mark Shannon in
|
|
:gh:`92925`.)
|
|
|
|
* Add the :opcode:`LOAD_FAST_AND_CLEAR` instruction as part of the
|
|
implementation of :pep:`709`. (Contributed by Carl Meyer in :gh:`101441`.)
|
|
|
|
* Add the :opcode:`LOAD_FROM_DICT_OR_DEREF`, :opcode:`LOAD_FROM_DICT_OR_GLOBALS`,
|
|
and :opcode:`LOAD_LOCALS` opcodes as part of the implementation of :pep:`695`.
|
|
Remove the :opcode:`!LOAD_CLASSDEREF` opcode, which can be replaced with
|
|
:opcode:`LOAD_LOCALS` plus :opcode:`LOAD_FROM_DICT_OR_DEREF`. (Contributed
|
|
by Jelle Zijlstra in :gh:`103764`.)
|
|
|
|
* Add the :opcode:`LOAD_SUPER_ATTR` instruction. (Contributed by Carl Meyer and
|
|
Vladimir Matveev in :gh:`103497`.)
|
|
|
|
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
|
|
==========
|
|
|
|
* :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:`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:`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
|
|
datetimes in UTC: respectively, call :meth:`~datetime.datetime.now` and
|
|
:meth:`~datetime.datetime.fromtimestamp` with the *tz* parameter set to
|
|
: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:`shutil`: The *onerror* argument of :func:`shutil.rmtree` is deprecated as 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`.)
|
|
|
|
* :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.
|
|
(Contributed by Irit Katriel in :gh:`102778`.)
|
|
|
|
* :mod:`tarfile`: Extracting tar archives without specifying *filter* is deprecated until
|
|
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:`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.
|
|
|
|
* 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`.)
|
|
|
|
* In accordance with :pep:`699`, the ``ma_version_tag`` field in :c:type:`PyDictObject`
|
|
is deprecated for extension modules. Accessing this field will generate a compiler
|
|
warning at compile time. This field will be removed in Python 3.14.
|
|
(Contributed by Ramvikrams and Kumar Aditya in :gh:`101193`. PEP by Ken Jin.)
|
|
|
|
* 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
|
|
in :gh:`103487`.)
|
|
|
|
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`
|
|
|
|
Other modules:
|
|
|
|
* :mod:`!lib2to3`, and the :program:`2to3` program (:gh:`84540`)
|
|
|
|
APIs:
|
|
|
|
* :class:`!configparser.LegacyInterpolation` (:gh:`90765`)
|
|
* :func:`locale.getdefaultlocale` (:gh:`90817`)
|
|
* ``locale.resetlocale()`` (:gh:`90817`)
|
|
* :meth:`!turtle.RawTurtle.settiltangle` (:gh:`50096`)
|
|
* :func:`!unittest.findTestCases` (:gh:`50096`)
|
|
* :func:`!unittest.getTestCaseNames` (:gh:`50096`)
|
|
* :func:`!unittest.makeSuite` (:gh:`50096`)
|
|
* :meth:`!unittest.TestProgram.usageExit` (:gh:`67048`)
|
|
* :class:`!webbrowser.MacOSX` (:gh:`86421`)
|
|
* :class:`classmethod` descriptor chaining (:gh:`89519`)
|
|
|
|
Pending Removal 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`.)
|
|
|
|
* :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 *msg* parameter of both
|
|
:meth:`asyncio.Future.cancel` and
|
|
:meth:`asyncio.Task.cancel` (:gh:`90985`)
|
|
|
|
* :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:`email`: Deprecated 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`: 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:`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`.
|
|
|
|
* :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`: 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.
|
|
|
|
* :mod:`shutil`: The *onerror* argument of :func:`shutil.rmtree` is deprecated in 3.12,
|
|
and will be removed in 3.14.
|
|
|
|
* :mod:`typing`: :class:`typing.ByteString`, deprecated since Python 3.9, now causes a
|
|
:exc:`DeprecationWarning` to be emitted when it is used.
|
|
|
|
* :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.
|
|
|
|
* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
|
|
bases using the C API (:gh:`95388`).
|
|
|
|
* ``__package__`` and ``__cached__`` will cease to be set or taken
|
|
into consideration by the import system (:gh:`97879`).
|
|
|
|
* 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`.)
|
|
|
|
* Creating :c:data:`immutable types <Py_TPFLAGS_IMMUTABLETYPE>` with mutable
|
|
bases using the C API (:gh:`95388`)
|
|
|
|
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.
|
|
|
|
* :mod:`array`'s ``'u'`` format code (:gh:`57281`)
|
|
|
|
* :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
|
|
=======
|
|
|
|
asynchat and asyncore
|
|
---------------------
|
|
|
|
* These two modules 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`.)
|
|
|
|
configparser
|
|
------------
|
|
|
|
* 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.
|
|
|
|
distutils
|
|
---------
|
|
|
|
* Remove the :py:mod:`!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`.)
|
|
|
|
ensurepip
|
|
---------
|
|
|
|
* Remove the bundled setuptools wheel from :mod:`ensurepip`,
|
|
and stop installing setuptools in environments created by :mod:`venv`.
|
|
|
|
``pip (>= 22.1)`` does not require setuptools to be installed in the
|
|
environment. ``setuptools``-based (and ``distutils``-based) packages
|
|
can still be used with ``pip install``, since pip will provide
|
|
``setuptools`` in the build environment it uses for building a
|
|
package.
|
|
|
|
``easy_install``, ``pkg_resources``, ``setuptools`` and ``distutils``
|
|
are no longer provided by default in environments created with
|
|
``venv`` or bootstrapped with ``ensurepip``, since they are part of
|
|
the ``setuptools`` package. For projects relying on these at runtime,
|
|
the ``setuptools`` project should be declared as a dependency and
|
|
installed separately (typically, using pip).
|
|
|
|
(Contributed by Pradyun Gedam in :gh:`95299`.)
|
|
|
|
enum
|
|
----
|
|
|
|
* Remove :mod:`enum`'s ``EnumMeta.__getattr__``, which is no longer needed for
|
|
enum attribute access.
|
|
(Contributed by Ethan Furman in :gh:`95083`.)
|
|
|
|
ftplib
|
|
------
|
|
|
|
* Remove :mod:`ftplib`'s ``FTP_TLS.ssl_version`` class attribute: use the
|
|
*context* parameter instead.
|
|
(Contributed by Victor Stinner in :gh:`94172`.)
|
|
|
|
gzip
|
|
----
|
|
|
|
* Remove the ``filename`` attribute of :mod:`gzip`'s :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`.)
|
|
|
|
hashlib
|
|
-------
|
|
|
|
* Remove the pure Python implementation of :mod:`hashlib`'s
|
|
: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`.)
|
|
|
|
importlib
|
|
---------
|
|
|
|
* Many previously deprecated cleanups in :mod:`importlib` have now been
|
|
completed:
|
|
|
|
* References to, and support for :meth:`!module_repr()` has been removed.
|
|
(Contributed by Barry Warsaw in :gh:`97850`.)
|
|
|
|
* ``importlib.util.set_package``, ``importlib.util.set_loader`` and
|
|
``importlib.util.module_for_loader`` have all been removed. (Contributed by
|
|
Brett Cannon and Nikita Sobolev in :gh:`65961` and :gh:`97850`.)
|
|
|
|
* Support for ``find_loader()`` and ``find_module()`` APIs have been
|
|
removed. (Contributed by Barry Warsaw in :gh:`98040`.)
|
|
|
|
* ``importlib.abc.Finder``, ``pkgutil.ImpImporter``, and ``pkgutil.ImpLoader``
|
|
have been removed. (Contributed by Barry Warsaw in :gh:`98040`.)
|
|
|
|
imp
|
|
---
|
|
|
|
* The :mod:`!imp` module has been removed. (Contributed by Barry Warsaw in
|
|
:gh:`98040`.)
|
|
|
|
* Replace removed :mod:`!imp` functions with :mod:`importlib` functions:
|
|
|
|
================================= =======================================
|
|
imp importlib
|
|
================================= =======================================
|
|
``imp.NullImporter`` Insert ``None`` into ``sys.path_importer_cache``
|
|
``imp.cache_from_source()`` :func:`importlib.util.cache_from_source`
|
|
``imp.find_module()`` :func:`importlib.util.find_spec`
|
|
``imp.get_magic()`` :attr:`importlib.util.MAGIC_NUMBER`
|
|
``imp.get_suffixes()`` :attr:`importlib.machinery.SOURCE_SUFFIXES`, :attr:`importlib.machinery.EXTENSION_SUFFIXES`, and :attr:`importlib.machinery.BYTECODE_SUFFIXES`
|
|
``imp.get_tag()`` :attr:`sys.implementation.cache_tag <sys.implementation>`
|
|
``imp.load_module()`` :func:`importlib.import_module`
|
|
``imp.new_module(name)`` ``types.ModuleType(name)``
|
|
``imp.reload()`` :func:`importlib.reload`
|
|
``imp.source_from_cache()`` :func:`importlib.util.source_from_cache`
|
|
================================= =======================================
|
|
|
|
* Replace ``imp.load_source()`` with::
|
|
|
|
import importlib.util
|
|
import importlib.machinery
|
|
|
|
def load_source(modname, filename):
|
|
loader = importlib.machinery.SourceFileLoader(modname, filename)
|
|
spec = importlib.util.spec_from_file_location(modname, filename, loader=loader)
|
|
module = importlib.util.module_from_spec(spec)
|
|
# The module is always executed and not cached in sys.modules.
|
|
# Uncomment the following line to cache the module.
|
|
# sys.modules[module.__name__] = module
|
|
loader.exec_module(module)
|
|
return module
|
|
|
|
* Removed :mod:`!imp` functions and attributes with no replacements:
|
|
|
|
* undocumented functions:
|
|
|
|
* ``imp.init_builtin()``
|
|
* ``imp.load_compiled()``
|
|
* ``imp.load_dynamic()``
|
|
* ``imp.load_package()``
|
|
|
|
* ``imp.lock_held()``, ``imp.acquire_lock()``, ``imp.release_lock()``:
|
|
the locking scheme has changed in Python 3.3 to per-module locks.
|
|
* ``imp.find_module()`` constants: ``SEARCH_ERROR``, ``PY_SOURCE``,
|
|
``PY_COMPILED``, ``C_EXTENSION``, ``PY_RESOURCE``, ``PKG_DIRECTORY``,
|
|
``C_BUILTIN``, ``PY_FROZEN``, ``PY_CODERESOURCE``, ``IMP_HOOK``.
|
|
|
|
io
|
|
--
|
|
|
|
* Remove :mod:`io`'s ``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`.)
|
|
|
|
locale
|
|
------
|
|
|
|
* Remove :mod:`locale`'s :func:`!locale.format` function, deprecated in Python 3.7:
|
|
use :func:`locale.format_string` instead.
|
|
(Contributed by Victor Stinner in :gh:`94226`.)
|
|
|
|
* ``smtpd``: The module 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/
|
|
|
|
sqlite3
|
|
-------
|
|
|
|
* 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`.)
|
|
|
|
ssl
|
|
---
|
|
|
|
* Remove :mod:`ssl`'s :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`.)
|
|
|
|
* Remove the :func:`!ssl.match_hostname` function.
|
|
It 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:`!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`.)
|
|
|
|
unittest
|
|
--------
|
|
|
|
* 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`.)
|
|
|
|
webbrowser
|
|
----------
|
|
|
|
* Remove support for obsolete browsers from :mod:`webbrowser`.
|
|
Removed browsers include: Grail, Mosaic, Netscape, Galeon, Skipstone,
|
|
Iceape, Firebird, and Firefox versions 35 and below (:gh:`102871`).
|
|
|
|
xml.etree.ElementTree
|
|
---------------------
|
|
|
|
* 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.ElementTree`
|
|
has no ``copy()`` method, only a ``__copy__()`` method.
|
|
(Contributed by Victor Stinner in :gh:`94383`.)
|
|
|
|
zipimport
|
|
---------
|
|
|
|
* Remove :mod:`zipimport`'s ``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`.)
|
|
|
|
Others
|
|
------
|
|
|
|
* 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* and *certfile* parameters from the
|
|
:mod:`ftplib`, :mod:`imaplib`, :mod:`poplib` and :mod:`smtplib` modules,
|
|
and the *key_file*, *cert_file* and *check_hostname* parameters from the
|
|
:mod:`http.client` module,
|
|
all deprecated since Python 3.6. Use the *context* parameter
|
|
(*ssl_context* in :mod:`imaplib`) instead.
|
|
(Contributed by Victor Stinner in :gh:`94172`.)
|
|
|
|
.. _whatsnew312-porting-to-python312:
|
|
|
|
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
|
|
:exc:`TypeError`. Also, the exception raised for non-integer values such as
|
|
``randrange(10.5)`` or ``randrange('10')`` has been changed from :exc:`ValueError` to
|
|
:exc:`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`.)
|
|
|
|
* :func:`syslog.openlog` and :func:`syslog.closelog` now fail if used in subinterpreters.
|
|
:func:`syslog.syslog` may still be used in subinterpreters,
|
|
but now only if :func:`syslog.openlog` has already been called in the main interpreter.
|
|
These new restrictions do not apply to the main interpreter,
|
|
so only a very small set of users might be affected.
|
|
This change helps with interpreter isolation. Furthermore, :mod:`syslog` is a wrapper
|
|
around process-global resources, which are best managed from the main interpreter.
|
|
(Contributed by Dong-hee Na in :gh:`99127`.)
|
|
|
|
* The undocumented locking behavior of :func:`~functools.cached_property`
|
|
is removed, because it locked across all instances of the class, leading to high
|
|
lock contention. This means that a cached property getter function could now run
|
|
more than once for a single instance, if two threads race. For most simple
|
|
cached properties (e.g. those that are idempotent and simply calculate a value
|
|
based on other attributes of the instance) this will be fine. If
|
|
synchronization is needed, implement locking within the cached property getter
|
|
function or around multi-threaded access points.
|
|
|
|
* :func:`sys._current_exceptions` now returns a mapping from thread-id to an
|
|
exception instance, rather than to a ``(typ, exc, tb)`` tuple.
|
|
(Contributed by Irit Katriel in :gh:`103176`.)
|
|
|
|
* When extracting tar files using :mod:`tarfile` or
|
|
:func:`shutil.unpack_archive`, pass the *filter* argument to limit features
|
|
that may be surprising or dangerous.
|
|
See :ref:`tarfile-extraction-filter` for details.
|
|
|
|
* The output of the :func:`tokenize.tokenize` and :func:`tokenize.generate_tokens`
|
|
functions is now changed due to the changes introduced in :pep:`701`. This
|
|
means that ``STRING`` tokens are not emitted any more for f-strings and the
|
|
tokens described in :pep:`701` are now produced instead: ``FSTRING_START``,
|
|
``FSTRING_MIDDLE`` and ``FSTRING_END`` are now emitted for f-string "string"
|
|
parts in addition to the appropriate tokens for the tokenization in the
|
|
expression components. For example for the f-string ``f"start {1+1} end"``
|
|
the old version of the tokenizer emitted::
|
|
|
|
1,0-1,18: STRING 'f"start {1+1} end"'
|
|
|
|
while the new version emits::
|
|
|
|
1,0-1,2: FSTRING_START 'f"'
|
|
1,2-1,8: FSTRING_MIDDLE 'start '
|
|
1,8-1,9: OP '{'
|
|
1,9-1,10: NUMBER '1'
|
|
1,10-1,11: OP '+'
|
|
1,11-1,12: NUMBER '1'
|
|
1,12-1,13: OP '}'
|
|
1,13-1,17: FSTRING_MIDDLE ' end'
|
|
1,17-1,18: FSTRING_END '"'
|
|
|
|
Additionally, there may be some minor behavioral changes as a consequence of the
|
|
changes required to support :pep:`701`. Some of these changes include:
|
|
|
|
* The ``type`` attribute of the tokens emitted when tokenizing some invalid Python
|
|
characters such as ``!`` has changed from ``ERRORTOKEN`` to ``OP``.
|
|
|
|
* Incomplete single-line strings now also raise :exc:`tokenize.TokenError` as incomplete
|
|
multiline strings do.
|
|
|
|
* Some incomplete or invalid Python code now raises :exc:`tokenize.TokenError` instead of
|
|
returning arbitrary ``ERRORTOKEN`` tokens when tokenizing it.
|
|
|
|
* Mixing tabs and spaces as indentation in the same file is not supported anymore and will
|
|
raise a :exc:`TabError`.
|
|
|
|
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`.)
|
|
|
|
* Add platform triplets for 64-bit LoongArch:
|
|
|
|
* loongarch64-linux-gnusf
|
|
* loongarch64-linux-gnuf32
|
|
* loongarch64-linux-gnu
|
|
|
|
(Contributed by Zhang Na in :gh:`90656`.)
|
|
|
|
* ``PYTHON_FOR_REGEN`` now require Python 3.10 or newer.
|
|
|
|
* Autoconf 2.71 and aclocal 1.16.4 is now required to regenerate
|
|
:file:`!configure`.
|
|
(Contributed by Christian Heimes in :gh:`89886`.)
|
|
|
|
|
|
C API Changes
|
|
=============
|
|
|
|
New Features
|
|
------------
|
|
|
|
|
|
* :pep:`697`: Introduced the :ref:`Unstable C API tier <unstable-c-api>`,
|
|
intended for low-level tools like debuggers and JIT compilers.
|
|
This API may change in each minor release of CPython without deprecation
|
|
warnings.
|
|
Its contents are marked by the ``PyUnstable_`` prefix in names.
|
|
|
|
Code object constructors:
|
|
|
|
- ``PyUnstable_Code_New()`` (renamed from ``PyCode_New``)
|
|
- ``PyUnstable_Code_NewWithPosOnlyArgs()`` (renamed from ``PyCode_NewWithPosOnlyArgs``)
|
|
|
|
Extra storage for code objects (:pep:`523`):
|
|
|
|
- ``PyUnstable_Eval_RequestCodeExtraIndex()`` (renamed from ``_PyEval_RequestCodeExtraIndex``)
|
|
- ``PyUnstable_Code_GetExtra()`` (renamed from ``_PyCode_GetExtra``)
|
|
- ``PyUnstable_Code_SetExtra()`` (renamed from ``_PyCode_SetExtra``)
|
|
|
|
The original names will continue to be available until the respective
|
|
API changes.
|
|
|
|
(Contributed by Petr Viktorin in :gh:`101101`.)
|
|
|
|
* :pep:`697`: Added API for extending types whose instance memory layout is
|
|
opaque:
|
|
|
|
- :c:member:`PyType_Spec.basicsize` can be zero or negative to specify
|
|
inheriting or extending the base class size.
|
|
- :c:func:`PyObject_GetTypeData` and :c:func:`PyType_GetTypeDataSize`
|
|
added to allow access to subclass-specific instance data.
|
|
- :c:macro:`Py_TPFLAGS_ITEMS_AT_END` and :c:func:`PyObject_GetItemData`
|
|
added to allow safely extending certain variable-sized types, including
|
|
:c:var:`PyType_Type`.
|
|
- :c:macro:`Py_RELATIVE_OFFSET` added to allow defining
|
|
:c:type:`members <PyMemberDef>` in terms of a subclass-specific struct.
|
|
|
|
(Contributed by Petr Viktorin in :gh:`103509`.)
|
|
|
|
* Added the new :ref:`limited C API <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>`:
|
|
|
|
* :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL`
|
|
* :c:func:`PyVectorcall_NARGS`
|
|
* :c:func:`PyVectorcall_Call`
|
|
* :c:type:`vectorcallfunc`
|
|
|
|
The :c:macro:`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 immutable flag, :c:macro:`Py_TPFLAGS_IMMUTABLETYPE`).
|
|
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 :c:macro:`Py_TPFLAGS_MANAGED_DICT` and :c:macro:`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`
|
|
* :c:macro:`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_Watch` 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`.)
|
|
|
|
* Added :c:func:`PyCode_AddWatcher` and :c:func:`PyCode_ClearWatcher`
|
|
APIs to register callbacks to receive notification on creation and
|
|
destruction of code objects.
|
|
(Contributed by Itamar Ostricher in :gh:`91054`.)
|
|
|
|
* 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`.)
|
|
|
|
* Add :c:func:`PyErr_GetRaisedException` and :c:func:`PyErr_SetRaisedException`
|
|
for saving and restoring the current exception.
|
|
These functions return and accept a single exception object,
|
|
rather than the triple arguments of the now-deprecated
|
|
:c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore`.
|
|
This is less error prone and a bit more efficient.
|
|
(Contributed by Mark Shannon in :gh:`101578`.)
|
|
|
|
* Add ``_PyErr_ChainExceptions1``, which takes an exception instance,
|
|
to replace the legacy-API ``_PyErr_ChainExceptions``, which is now
|
|
deprecated. (Contributed by Mark Shannon in :gh:`101578`.)
|
|
|
|
* Add :c:func:`PyException_GetArgs` and :c:func:`PyException_SetArgs`
|
|
as convenience functions for retrieving and modifying
|
|
the :attr:`~BaseException.args` passed to the exception's constructor.
|
|
(Contributed by Mark Shannon in :gh:`101578`.)
|
|
|
|
* Add :c:func:`PyErr_DisplayException`, which takes an exception instance,
|
|
to replace the legacy-api :c:func:`!PyErr_Display`. (Contributed by
|
|
Irit Katriel in :gh:`102755`).
|
|
|
|
* :pep:`683`: Introduced Immortal Objects to Python which allows objects
|
|
to bypass reference counts and introduced changes to the C-API:
|
|
|
|
- ``_Py_IMMORTAL_REFCNT``: The reference count that defines an object
|
|
as immortal.
|
|
- ``_Py_IsImmortal`` Checks if an object has the immortal reference count.
|
|
- ``PyObject_HEAD_INIT`` This will now initialize reference count to
|
|
``_Py_IMMORTAL_REFCNT`` when used with ``Py_BUILD_CORE``.
|
|
- ``SSTATE_INTERNED_IMMORTAL`` An identifier for interned unicode objects
|
|
that are immortal.
|
|
- ``SSTATE_INTERNED_IMMORTAL_STATIC`` An identifier for interned unicode
|
|
objects that are immortal and static
|
|
- ``sys.getunicodeinternedsize`` This returns the total number of unicode
|
|
objects that have been interned. This is now needed for refleak.py to
|
|
correctly track reference counts and allocated blocks
|
|
|
|
(Contributed by Eddie Elizondo in :gh:`84436`.)
|
|
|
|
* :pep:`684`: Added the new :c:func:`Py_NewInterpreterFromConfig`
|
|
function and :c:type:`PyInterpreterConfig`, which may be used
|
|
to create sub-interpreters with their own GILs.
|
|
(See :ref:`whatsnew312-pep684` for more info.)
|
|
(Contributed by Eric Snow in :gh:`104110`.)
|
|
|
|
* In the limited C API version 3.12, :c:func:`Py_INCREF` and
|
|
:c:func:`Py_DECREF` functions are now implemented as opaque function calls to
|
|
hide implementation details.
|
|
(Contributed by Victor Stinner in :gh:`105387`.)
|
|
|
|
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).
|
|
|
|
* Add support of more formatting options (left aligning, octals, uppercase
|
|
hexadecimals, :c:type:`intmax_t`, :c:type:`ptrdiff_t`, :c:type:`wchar_t` C
|
|
strings, variable width and precision) in :c:func:`PyUnicode_FromFormat` and
|
|
:c:func:`PyUnicode_FromFormatV`.
|
|
(Contributed by Serhiy Storchaka in :gh:`98836`.)
|
|
|
|
* 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 :c:macro:`Py_TPFLAGS_MANAGED_DICT` and
|
|
:c:macro:`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 :c:macro:`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 arguments once. If an argument has side
|
|
effects, these side effects are no longer duplicated.
|
|
(Contributed by Victor Stinner in :gh:`98724`.)
|
|
|
|
* The interpreter's error indicator is now always normalized. This means
|
|
that :c:func:`PyErr_SetObject`, :c:func:`PyErr_SetString` and the other
|
|
functions that set the error indicator now normalize the exception
|
|
before storing it. (Contributed by Mark Shannon in :gh:`101578`.)
|
|
|
|
* ``_Py_RefTotal`` is no longer authoritative and only kept around
|
|
for ABI compatibility. Note that it is an internal global and only
|
|
available on debug builds. If you happen to be using it then you'll
|
|
need to start using ``_Py_GetGlobalRefTotal()``.
|
|
|
|
* The following functions now select an appropriate metaclass for the newly
|
|
created type:
|
|
|
|
* :c:func:`PyType_FromSpec`
|
|
* :c:func:`PyType_FromSpecWithBases`
|
|
* :c:func:`PyType_FromModuleAndSpec`
|
|
|
|
Creating classes whose metaclass overrides :c:member:`~PyTypeObject.tp_new`
|
|
is deprecated, and in Python 3.14+ it will be disallowed.
|
|
Note that these functions ignore ``tp_new`` of the metaclass, possibly
|
|
allowing incomplete initialization.
|
|
|
|
Note that :c:func:`PyType_FromMetaclass` (added in Python 3.12)
|
|
already disallows creating classes whose metaclass overrides ``tp_new``
|
|
(:meth:`~object.__new__` in Python).
|
|
|
|
Since ``tp_new`` overrides almost everything ``PyType_From*`` functions do,
|
|
the two are incompatible with each other.
|
|
The existing behavior -- ignoring the metaclass for several steps
|
|
of type creation -- is unsafe in general, since (meta)classes assume that
|
|
``tp_new`` was called.
|
|
There is no simple general workaround. One of the following may work for you:
|
|
|
|
- If you control the metaclass, avoid using ``tp_new`` in it:
|
|
|
|
- If initialization can be skipped, it can be done in
|
|
:c:member:`~PyTypeObject.tp_init` instead.
|
|
- If the metaclass doesn't need to be instantiated from Python,
|
|
set its ``tp_new`` to ``NULL`` using
|
|
the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag.
|
|
This makes it acceptable for ``PyType_From*`` functions.
|
|
|
|
- Avoid ``PyType_From*`` functions: if you don't need C-specific features
|
|
(slots or setting the instance size), create types by :ref:`calling <call>`
|
|
the metaclass.
|
|
|
|
- If you *know* the ``tp_new`` can be skipped safely, filter the deprecation
|
|
warning out using :func:`warnings.catch_warnings` from Python.
|
|
|
|
* :c:var:`PyOS_InputHook` and :c:var:`PyOS_ReadlineFunctionPointer` are no
|
|
longer called in :ref:`subinterpreters <sub-interpreter-support>`. This is
|
|
because clients generally rely on process-wide global state (since these
|
|
callbacks have no way of recovering extension module state).
|
|
|
|
This also avoids situations where extensions may find themselves running in a
|
|
subinterpreter that they don't support (or haven't yet been loaded in). See
|
|
:gh:`104668` for more info.
|
|
|
|
* :c:struct:`PyLongObject` has had its internals changed for better performance.
|
|
Although the internals of :c:struct:`PyLongObject` are private, they are used
|
|
by some extension modules.
|
|
The internal fields should no longer be accessed directly, instead the API
|
|
functions beginning ``PyLong_...`` should be used instead.
|
|
Two new *unstable* API functions are provided for efficient access to the
|
|
value of :c:struct:`PyLongObject`\s which fit into a single machine word:
|
|
|
|
* :c:func:`PyUnstable_Long_IsCompact`
|
|
* :c:func:`PyUnstable_Long_CompactValue`
|
|
|
|
* Custom allocators, set via :c:func:`PyMem_SetAllocator`, are now
|
|
required to be thread-safe, regardless of memory domain. Allocators
|
|
that don't have their own state, including "hooks", are not affected.
|
|
If your custom allocator is not already thread-safe and you need
|
|
guidance then please create a new GitHub issue
|
|
and CC ``@ericsnowcurrently``.
|
|
|
|
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:`PyPreConfig.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_HasFileSystemDefaultEncoding`: 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 immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
|
|
bases is deprecated and will be disabled in Python 3.14.
|
|
|
|
* The ``structmember.h`` header is deprecated, though it continues to be
|
|
available and there are no plans to remove it.
|
|
|
|
Its contents are now available just by including ``Python.h``,
|
|
with a ``Py`` prefix added if it was missing:
|
|
|
|
- :c:struct:`PyMemberDef`, :c:func:`PyMember_GetOne` and
|
|
:c:func:`PyMember_SetOne`
|
|
- Type macros like :c:macro:`Py_T_INT`, :c:macro:`Py_T_DOUBLE`, etc.
|
|
(previously ``T_INT``, ``T_DOUBLE``, etc.)
|
|
- The flags :c:macro:`Py_READONLY` (previously ``READONLY``) and
|
|
:c:macro:`Py_AUDIT_READ` (previously all uppercase)
|
|
|
|
Several items are not exposed from ``Python.h``:
|
|
|
|
- :c:macro:`T_OBJECT` (use :c:macro:`Py_T_OBJECT_EX`)
|
|
- :c:macro:`T_NONE` (previously undocumented, and pretty quirky)
|
|
- The macro ``WRITE_RESTRICTED`` which does nothing.
|
|
- The macros ``RESTRICTED`` and ``READ_RESTRICTED``, equivalents of
|
|
:c:macro:`Py_AUDIT_READ`.
|
|
- In some configurations, ``<stddef.h>`` is not included from ``Python.h``.
|
|
It should be included manually when using ``offsetof()``.
|
|
|
|
The deprecated header continues to provide its original
|
|
contents under the original names.
|
|
Your old code can stay unchanged, unless the extra include and non-namespaced
|
|
macros bother you greatly.
|
|
|
|
(Contributed in :gh:`47146` by Petr Viktorin, based on
|
|
earlier work by Alexander Belopolsky and Matthias Braun.)
|
|
|
|
* :c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` are deprecated.
|
|
Use :c:func:`PyErr_GetRaisedException` and
|
|
:c:func:`PyErr_SetRaisedException` instead.
|
|
(Contributed by Mark Shannon in :gh:`101578`.)
|
|
|
|
* :c:func:`!PyErr_Display` is deprecated. Use :c:func:`PyErr_DisplayException`
|
|
instead. (Contributed by Irit Katriel in :gh:`102755`).
|
|
|
|
* ``_PyErr_ChainExceptions`` is deprecated. Use ``_PyErr_ChainExceptions1``
|
|
instead. (Contributed by Irit Katriel in :gh:`102192`.)
|
|
|
|
* Using :c:func:`PyType_FromSpec`, :c:func:`PyType_FromSpecWithBases`
|
|
or :c:func:`PyType_FromModuleAndSpec` to create a class whose metaclass
|
|
overrides :c:member:`~PyTypeObject.tp_new` is deprecated.
|
|
Call the metaclass instead.
|
|
|
|
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`.)
|
|
|
|
* Legacy Unicode APIs have 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 macro.
|
|
(Contributed by Victor Stinner in :gh:`85858`.)
|
|
|
|
* Remove ``Jython`` compatibility hacks from several stdlib modules and tests.
|
|
(Contributed by Nikita Sobolev in :gh:`99482`.)
|
|
|
|
* Remove ``_use_broken_old_ctypes_structure_semantics_`` flag
|
|
from :mod:`ctypes` module.
|
|
(Contributed by Nikita Sobolev in :gh:`99285`.)
|