What’s New In Python 3.10¶
- Release
3.10.0a7
- Date
April 06, 2021
This article explains the new features in Python 3.10, compared to 3.9.
For full details, see the changelog.
Note
Prerelease users should be aware that this document is currently in draft form. It will be updated substantially as Python 3.10 moves towards release, so it’s worth checking back even after reading earlier versions.
Summary – Release highlights¶
New Features¶
Parenthesized context managers¶
Using enclosing parentheses for continuation across multiple lines in context managers is now supported. This allows formatting a long collection of context managers in multiple lines in a similar way as it was previously possible with import statements. For instance, all these examples are now valid:
with (CtxManager() as example):
...
with (
CtxManager1(),
CtxManager2()
):
...
with (CtxManager1() as example,
CtxManager2()):
...
with (CtxManager1(),
CtxManager2() as example):
...
with (
CtxManager1() as example1,
CtxManager2() as example2
):
...
it is also possible to use a trailing comma at the end of the enclosed group:
with (
CtxManager1() as example1,
CtxManager2() as example2,
CtxManager3() as example3,
):
...
This new syntax uses the non LL(1) capacities of the new parser. Check PEP 617 for more details.
(Contributed by Guido van Rossum, Pablo Galindo and Lysandros Nikolaou in bpo-12782 and bpo-40334.)
Better error messages in the parser¶
When parsing code that contains unclosed parentheses or brackets the interpreter now includes the location of the unclosed bracket of parentheses instead of displaying SyntaxError: unexpected EOF while parsing or pointing to some incorrect location. For instance, consider the following code (notice the unclosed ‘{‘):
expected = {9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4,
38: 4, 39: 4, 45: 5, 46: 5, 47: 5, 48: 5, 49: 5, 54: 6,
some_other_code = foo()
previous versions of the interpreter reported confusing places as the location of the syntax error:
File "example.py", line 3
some_other_code = foo()
^
SyntaxError: invalid syntax
but in Python3.10 a more informative error is emitted:
File "example.py", line 1
expected = {9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4,
^
SyntaxError: '{' was never closed
In a similar way, errors involving unclosed string literals (single and triple quoted) now point to the start of the string instead of reporting EOF/EOL.
These improvements are inspired by previous work in the PyPy interpreter.
(Contributed by Pablo Galindo in bpo-42864 and Batuhan Taskaya in bpo-40176.)
PEP 626: Precise line numbers for debugging and other tools¶
PEP 626 brings more precise and reliable line numbers for debugging, profiling and coverage tools. Tracing events, with the correct line number, are generated for all lines of code executed and only for lines of code that are executed.
The f_lineo
attribute of frame objects will always contain the expected line number.
The co_lnotab
attribute of code objects is deprecated and will be removed in 3.12.
Code that needs to convert from offset to line number should use the new co_lines()
method instead.
PEP 634: Structural Pattern Matching¶
Structural pattern matching has been added in the form of a match statement and case statements of patterns with associated actions. Patterns consist of sequences, mappings, primitive data types as well as class instances. Pattern matching enables programs to extract information from complex data types, branch on the structure of data, and apply specific actions based on different forms of data.
Syntax and operations¶
The generic syntax of pattern matching is:
match subject:
case <pattern_1>:
<action_1>
case <pattern_2>:
<action_2>
case <pattern_3>:
<action_3>
case _:
<action_wildcard>
A match statement takes an expression and compares its value to successive patterns given as one or more case blocks. Specifically, pattern matching operates by:
using data with type and shape (the
subject
)evaluating the
subject
in thematch
statementcomparing the subject with each pattern in a
case
statement from top to bottom until a match is confirmed.executing the action associated with the pattern of the confirmed match
If an exact match is not confirmed, the last case, a wildcard
_
, if provided, will be used as the matching case. If an exact match is not confirmed and a wildcard case does not exist, the entire match block is a no-op.
Declarative approach¶
Readers may be aware of pattern matching through the simple example of matching a subject (data object) to a literal (pattern) with the switch statement found in C, Java or JavaScript (and many other languages). Often the switch statement is used for comparison of an object/expression with case statements containing literals.
More powerful examples of pattern matching can be found in languages, such as Scala and Elixir. With structural pattern matching, the approach is “declarative” and explicitly states the conditions (the patterns) for data to match.
While an “imperative” series of instructions using nested “if” statements could be used to accomplish something similar to structural pattern matching, it is less clear than the “declarative” approach. Instead the “declarative” approach states the conditions to meet for a match and is more readable through its explicit patterns. While structural pattern matching can be used in its simplest form comparing a variable to a literal in a case statement, its true value for Python lies in its handling of the subject’s type and shape.
Simple pattern: match to a literal¶
Let’s look at this example as pattern matching in its simplest form: a value,
the subject, being matched to several literals, the patterns. In the example
below, status
is the subject of the match statement. The patterns are
each of the case statements, where literals represent request status codes.
The associated action to the case is executed after a match:
def http_error(status):
match status:
case 400:
return "Bad request"
case 404:
return "Not found"
case 418:
return "I'm a teapot"
case _:
return "Something's wrong with the Internet"
If the above function is passed a status
of 418, “I’m a teapot” is returned.
If the above function is passed a status
of 500, the case statement with
_
will match as a wildcard, and “Something’s wrong with the Internet” is
returned.
Note the last block: the variable name, _
, acts as a wildcard and insures
the subject will always match. The use of _
is optional.
You can combine several literals in a single pattern using |
(“or”):
case 401 | 403 | 404:
return "Not allowed"
Behavior without the wildcard¶
If we modify the above example by removing the last case block, the example becomes:
def http_error(status):
match status:
case 400:
return "Bad request"
case 404:
return "Not found"
case 418:
return "I'm a teapot"
Without the use of _
in a case statement, a match may not exist. If no
match exists, the behavior is a no-op. For example, if status
of 500 is
passed, a no-op occurs.
Patterns with a literal and variable¶
Patterns can look like unpacking assignments, and a pattern may be used to bind variables. In this example, a data point can be unpacked to its x-coordinate and y-coordinate:
# point is an (x, y) tuple
match point:
case (0, 0):
print("Origin")
case (0, y):
print(f"Y={y}")
case (x, 0):
print(f"X={x}")
case (x, y):
print(f"X={x}, Y={y}")
case _:
raise ValueError("Not a point")
The first pattern has two literals, (0, 0)
, and may be thought of as an
extension of the literal pattern shown above. The next two patterns combine a
literal and a variable, and the variable binds a value from the subject
(point
). The fourth pattern captures two values, which makes it
conceptually similar to the unpacking assignment (x, y) = point
.
Patterns and classes¶
If you are using classes to structure your data, you can use as a pattern the class name followed by an argument list resembling a constructor. This pattern has the ability to capture class attributes into variables:
class Point:
x: int
y: int
def location(point):
match point:
case Point(x=0, y=0):
print("Origin is the point's location.")
case Point(x=0, y=y):
print(f"Y={y} and the point is on the y-axis.")
case Point(x=x, y=0):
print(f"X={x} and the point is on the x-axis.")
case Point():
print("The point is located somewhere else on the plane.")
case _:
print("Not a point")
Patterns with positional parameters¶
You can use positional parameters with some builtin classes that provide an
ordering for their attributes (e.g. dataclasses). You can also define a specific
position for attributes in patterns by setting the __match_args__
special
attribute in your classes. If it’s set to (“x”, “y”), the following patterns
are all equivalent (and all bind the y
attribute to the var
variable):
Point(1, var)
Point(1, y=var)
Point(x=1, y=var)
Point(y=var, x=1)
Nested patterns¶
Patterns can be arbitrarily nested. For example, if our data is a short list of points, it could be matched like this:
match points:
case []:
print("No points in the list.")
case [Point(0, 0)]:
print("The origin is the only point in the list.")
case [Point(x, y)]:
print(f"A single point {x}, {y} is in the list.")
case [Point(0, y1), Point(0, y2)]:
print(f"Two points on the Y axis at {y1}, {y2} are in the list.")
case _:
print("Something else is found in the list.")
Complex patterns and the wildcard¶
To this point, the examples have used _
alone in the last case statement.
A wildcard can be used in more complex patterns, such as ('error', code, _)
.
For example:
match test_variable:
case ('warning', code, 40):
print("A warning has been received.")
case ('error', code, _):
print(f"An error {code} occured.")
In the above case, test_variable
will match for (‘error’, code, 100) and
(‘error’, code, 800).
Guard¶
We can add an if
clause to a pattern, known as a “guard”. If the
guard is false, match
goes on to try the next case block. Note
that value capture happens before the guard is evaluated:
match point:
case Point(x, y) if x == y:
print(f"The point is located on the diagonal Y=X at {x}.")
case Point(x, y):
print(f"Point is not on the diagonal.")
Other Key Features¶
Several other key features:
Like unpacking assignments, tuple and list patterns have exactly the same meaning and actually match arbitrary sequences. Technically, the subject must be an instance of
collections.abc.Sequence
. Therefore, an important exception is that patterns don’t match iterators. Also, to prevent a common mistake, sequence patterns don’t match strings.Sequence patterns support wildcards:
[x, y, *rest]
and(x, y, *rest)
work similar to wildcards in unpacking assignments. The name after*
may also be_
, so(x, y, *_)
matches a sequence of at least two items without binding the remaining items.Mapping patterns:
{"bandwidth": b, "latency": l}
captures the"bandwidth"
and"latency"
values from a dict. Unlike sequence patterns, extra keys are ignored. A wildcard**rest
is also supported. (But**_
would be redundant, so is not allowed.)Subpatterns may be captured using the
as
keyword:case (Point(x1, y1), Point(x2, y2) as p2): ...
This binds x1, y1, x2, y2 like you would expect without the
as
clause, and p2 to the entire second item of the subject.Most literals are compared by equality. However, the singletons
True
,False
andNone
are compared by identity.Named constants may be used in patterns. These named constants must be dotted names to prevent the constant from being interpreted as a capture variable:
from enum import Enum class Color(Enum): RED = 0 GREEN = 1 BLUE = 2 match color: case Color.RED: print("I see red!") case Color.GREEN: print("Grass is green") case Color.BLUE: print("I'm feeling the blues :(")
For the full specification see PEP 634. Motivation and rationale are in PEP 635, and a longer tutorial is in PEP 636.
Optional EncodingWarning
and encoding="locale"
option¶
The default encoding of TextIOWrapper
and open()
is
platform and locale dependent. Since UTF-8 is used on most Unix
platforms, omitting encoding
option when opening UTF-8 files
(e.g. JSON, YAML, TOML, Markdown) is a very common bug. For example:
# BUG: "rb" mode or encoding="utf-8" should be used.
with open("data.json") as f:
data = json.load(f)
To find this type of bug, optional EncodingWarning
is added.
It is emitted when sys.flags.warn_default_encoding
is true and locale-specific default encoding is used.
-X warn_default_encoding
option and PYTHONWARNDEFAULTENCODING
are added to enable the warning.
See Text Encoding for more information.
Other Language Changes¶
The
int
type has a new methodint.bit_count()
, returning the number of ones in the binary expansion of a given integer, also known as the population count. (Contributed by Niklas Fiekas in bpo-29882.)The views returned by
dict.keys()
,dict.values()
anddict.items()
now all have amapping
attribute that gives atypes.MappingProxyType
object wrapping the original dictionary. (Contributed by Dennis Sweeney in bpo-40890.)PEP 618: The
zip()
function now has an optionalstrict
flag, used to require that all the iterables have an equal length.Builtin and extension functions that take integer arguments no longer accept
Decimal
s,Fraction
s and other objects that can be converted to integers only with a loss (e.g. that have the__int__()
method but do not have the__index__()
method). (Contributed by Serhiy Storchaka in bpo-37999.)If
object.__ipow__()
returnsNotImplemented
, the operator will correctly fall back toobject.__pow__()
andobject.__rpow__()
as expected. (Contributed by Alex Shkop in bpo-38302.)Assignment expressions can now be used unparenthesized within set literals and set comprehensions, as well as in sequence indexes (but not slices).
Functions have a new
__builtins__
attribute which is used to look for builtin symbols when a function is executed, instead of looking into__globals__['__builtins__']
. The attribute is initialized from__globals__["__builtins__"]
if it exists, else from the current builtins. (Contributed by Mark Shannon in bpo-42990.)Two new builtin functions –
aiter()
andanext()
have been added to provide asynchronous counterparts toiter()
andnext()
, respectively. (Contributed by Joshua Bronson, Daniel Pope, and Justin Wang in bpo-31861.)
New Modules¶
None yet.
Improved Modules¶
argparse¶
Misleading phrase “optional arguments” was replaced with “options” in argparse help. Some tests might require adaptation if they rely on exact output match. (Contributed by Raymond Hettinger in bpo-9694.)
array¶
The index()
method of array.array
now has
optional start and stop parameters.
(Contributed by Anders Lorentsen and Zackery Spytz in bpo-31956.)
base64¶
Add base64.b32hexencode()
and base64.b32hexdecode()
to support the
Base32 Encoding with Extended Hex Alphabet.
codecs¶
Add a codecs.unregister()
function to unregister a codec search function.
(Contributed by Hai Shi in bpo-41842.)
collections.abc¶
The __args__
of the parameterized generic for
collections.abc.Callable
are now consistent with typing.Callable
.
collections.abc.Callable
generic now flattens type parameters, similar
to what typing.Callable
currently does. This means that
collections.abc.Callable[[int, str], str]
will have __args__
of
(int, str, str)
; previously this was ([int, str], str)
. To allow this
change, types.GenericAlias
can now be subclassed, and a subclass will
be returned when subscripting the collections.abc.Callable
type. Note
that a TypeError
may be raised for invalid forms of parameterizing
collections.abc.Callable
which may have passed silently in Python 3.9.
(Contributed by Ken Jin in bpo-42195.)
contextlib¶
Add a contextlib.aclosing()
context manager to safely close async generators
and objects representing asynchronously released resources.
(Contributed by Joongi Kim and John Belmonte in bpo-41229.)
Add asynchronous context manager support to contextlib.nullcontext()
.
(Contributed by Tom Gringauz in bpo-41543.)
curses¶
The extended color functions added in ncurses 6.1 will be used transparently
by curses.color_content()
, curses.init_color()
,
curses.init_pair()
, and curses.pair_content()
. A new function,
curses.has_extended_color_support()
, indicates whether extended color
support is provided by the underlying ncurses library.
(Contributed by Jeffrey Kintscher and Hans Petter Jansson in bpo-36982.)
The BUTTON5_*
constants are now exposed in the curses
module if
they are provided by the underlying curses library.
(Contributed by Zackery Spytz in bpo-39273.)
distutils¶
The entire distutils
package is deprecated, to be removed in Python
3.12. Its functionality for specifying package builds has already been
completely replaced by third-party packages setuptools
and
packaging
, and most other commonly used APIs are available elsewhere
in the standard library (such as platform
, shutil
,
subprocess
or sysconfig
). There are no plans to migrate
any other functionality from distutils
, and applications that are
using other functions should plan to make private copies of the code.
Refer to PEP 632 for discussion.
The bdist_wininst
command deprecated in Python 3.8 has been removed.
The bdist_wheel
command is now recommended to distribute binary packages
on Windows.
(Contributed by Victor Stinner in bpo-42802.)
doctest¶
When a module does not define __loader__
, fall back to __spec__.loader
.
(Contributed by Brett Cannon in bpo-42133.)
encodings¶
encodings.normalize_encoding()
now ignores non-ASCII characters.
(Contributed by Hai Shi in bpo-39337.)
enum¶
Enum
__repr__()
now returns enum_name.member_name
and
__str__()
now returns member_name
. Stdlib enums available as
module constants have a repr()
of module_name.member_name
.
(Contributed by Ethan Furman in bpo-40066.)
gc¶
Added audit hooks for gc.get_objects()
, gc.get_referrers()
and
gc.get_referents()
. (Contributed by Pablo Galindo in bpo-43439.)
glob¶
Added the root_dir and dir_fd parameters in glob()
and
iglob()
which allow to specify the root directory for searching.
(Contributed by Serhiy Storchaka in bpo-38144.)
importlib.metadata¶
Feature parity with importlib_metadata
3.7.
importlib.metadata.entry_points()
now provides a nicer experience
for selecting entry points by group and name through a new
importlib.metadata.EntryPoints
class.
Added importlib.metadata.packages_distributions()
for resolving
top-level Python modules and packages to their
importlib.metadata.Distribution
.
inspect¶
When a module does not define __loader__
, fall back to __spec__.loader
.
(Contributed by Brett Cannon in bpo-42133.)
Added globalns and localns parameters in signature()
and
inspect.Signature.from_callable()
to retrieve the annotations in given
local and global namespaces.
(Contributed by Batuhan Taskaya in bpo-41960.)
linecache¶
When a module does not define __loader__
, fall back to __spec__.loader
.
(Contributed by Brett Cannon in bpo-42133.)
os¶
Added os.cpu_count()
support for VxWorks RTOS.
(Contributed by Peixing Xin in bpo-41440.)
Added a new function os.eventfd()
and related helpers to wrap the
eventfd2
syscall on Linux.
(Contributed by Christian Heimes in bpo-41001.)
Added os.splice()
that allows to move data between two file
descriptors without copying between kernel address space and user
address space, where one of the file descriptors must refer to a
pipe. (Contributed by Pablo Galindo in bpo-41625.)
Added O_EVTONLY
, O_FSYNC
, O_SYMLINK
and O_NOFOLLOW_ANY
for macOS.
(Contributed by Dong-hee Na in bpo-43106.)
pathlib¶
Added slice support to PurePath.parents
.
(Contributed by Joshua Cannon in bpo-35498)
Added negative indexing support to PurePath.parents
.
(Contributed by Yaroslav Pankovych in bpo-21041)
platform¶
Added platform.freedesktop_os_release()
to retrieve operation system
identification from freedesktop.org os-release standard file.
(Contributed by Christian Heimes in bpo-28468)
py_compile¶
Added --quiet
option to command-line interface of py_compile
.
(Contributed by Gregory Schevchenko in bpo-38731.)
pyclbr¶
Added an end_lineno
attribute to the Function
and Class
objects in the tree returned by pyclbr.readline()
and
pyclbr.readline_ex()
. It matches the existing (start) lineno
.
(Contributed by Aviral Srivastava in bpo-38307.)
shelve¶
The shelve
module now uses pickle.DEFAULT_PROTOCOL
by default
instead of pickle
protocol 3
when creating shelves.
(Contributed by Zackery Spytz in bpo-34204.)
site¶
When a module does not define __loader__
, fall back to __spec__.loader
.
(Contributed by Brett Cannon in bpo-42133.)
socket¶
The exception socket.timeout
is now an alias of TimeoutError
.
(Contributed by Christian Heimes in bpo-42413.)
Added option to create MPTCP sockets with IPPROTO_MPTCP
(Contributed by Rui Cunha in bpo-43571.)
sys¶
Add sys.orig_argv
attribute: the list of the original command line
arguments passed to the Python executable.
(Contributed by Victor Stinner in bpo-23427.)
Add sys.stdlib_module_names
, containing the list of the standard library
module names.
(Contributed by Victor Stinner in bpo-42955.)
_thread¶
_thread.interrupt_main()
now takes an optional signal number to
simulate (the default is still signal.SIGINT
).
(Contributed by Antoine Pitrou in bpo-43356.)
threading¶
Added threading.gettrace()
and threading.getprofile()
to
retrieve the functions set by threading.settrace()
and
threading.setprofile()
respectively.
(Contributed by Mario Corchero in bpo-42251.)
Add threading.__excepthook__
to allow retrieving the original value
of threading.excepthook()
in case it is set to a broken or a different
value.
(Contributed by Mario Corchero in bpo-42308.)
traceback¶
The format_exception()
,
format_exception_only()
, and
print_exception()
functions can now take an exception object
as a positional-only argument.
(Contributed by Zackery Spytz and Matthias Bussonnier in bpo-26389.)
types¶
Reintroduced the types.EllipsisType
, types.NoneType
and types.NotImplementedType
classes, providing a new set
of types readily interpretable by type checkers.
(Contributed by Bas van Beek in bpo-41810.)
typing¶
For major changes, see New Features Related to Type Annotations.
The behavior of typing.Literal
was changed to conform with PEP 586
and to match the behavior of static type checkers specified in the PEP.
Literal
now de-duplicates parameters.Equality comparisons between
Literal
objects are now order independent.Literal
comparisons now respects types. For example,Literal[0] == Literal[False]
previously evaluated toTrue
. It is nowFalse
. To support this change, the internally used type cache now supports differentiating types.Literal
objects will now raise aTypeError
exception during equality comparisons if one of their parameters are not immutable. Note that declaringLiteral
with mutable parameters will not throw an error:>>> from typing import Literal >>> Literal[{0}] >>> Literal[{0}] == Literal[{False}] Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: unhashable type: 'set'
(Contributed by Yurii Karabas in bpo-42345.)
unittest¶
Add new method assertNoLogs()
to complement the
existing assertLogs()
. (Contributed by Kit Yan Choi
in bpo-39385.)
urllib.parse¶
Python versions earlier than Python 3.10 allowed using both ;
and &
as
query parameter separators in urllib.parse.parse_qs()
and
urllib.parse.parse_qsl()
. Due to security concerns, and to conform with
newer W3C recommendations, this has been changed to allow only a single
separator key, with &
as the default. This change also affects
cgi.parse()
and cgi.parse_multipart()
as they use the affected
functions internally. For more details, please see their respective
documentation.
(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in bpo-42967.)
xml¶
Add a LexicalHandler
class to the
xml.sax.handler
module.
(Contributed by Jonathan Gossage and Zackery Spytz in bpo-35018.)
zipimport¶
Add methods related to PEP 451: find_spec()
,
zipimport.zipimporter.create_module()
, and
zipimport.zipimporter.exec_module()
.
(Contributed by Brett Cannon in bpo-42131.
Optimizations¶
Constructors
str()
,bytes()
andbytearray()
are now faster (around 30–40% for small objects). (Contributed by Serhiy Storchaka in bpo-41334.)The
runpy
module now imports fewer modules. Thepython3 -m module-name
command startup time is 1.4x faster in average. On Linux,python3 -I -m module-name
imports 69 modules on Python 3.9, whereas it only imports 51 modules (-18) on Python 3.10. (Contributed by Victor Stinner in bpo-41006 and bpo-41718.)The
LOAD_ATTR
instruction now uses new “per opcode cache” mechanism. It is about 36% faster now for regular attributes and 44% faster for slots. (Contributed by Pablo Galindo and Yury Selivanov in bpo-42093 and Guido van Rossum in bpo-42927, based on ideas implemented originally in PyPy and MicroPython.)When building Python with
--enable-optimizations
now-fno-semantic-interposition
is added to both the compile and link line. This speeds builds of the Python interpreter created with--enable-shared
withgcc
by up to 30%. See this article for more details. (Contributed by Victor Stinner and Pablo Galindo in bpo-38980.)Function parameters and their annotations are no longer computed at runtime, but rather at compilation time. They are stored as a tuple of strings at the bytecode level. It is now around 2 times faster to create a function with parameter annotations. (Contributed by Yurii Karabas and Inada Naoki in bpo-42202)
Substring search functions such as
str1 in str2
andstr2.find(str1)
now sometimes use Crochemore & Perrin’s “Two-Way” string searching algorithm to avoid quadratic behavior on long strings. (Contributed by Dennis Sweeney in bpo-41972)Added micro-optimizations to
_PyType_Lookup()
to improve type attribute cache lookup performance in the common case of cache hits. This makes the interpreter 1.04 times faster in average (Contributed by Dino Viehland in bpo-43452)
Deprecated¶
Starting in this release, there will be a concerted effort to begin cleaning up old import semantics that were kept for Python 2.7 compatibility. Specifically,
find_loader()
/find_module()
(superseded byfind_spec()
),load_module()
(superseded byexec_module()
),module_repr()
(which the import system takes care of for you), the__package__
attribute (superseded by__spec__.parent
), the__loader__
attribute (superseded by__spec__.loader
), and the__cached__
attribute (superseded by__spec__.cached
) will slowly be removed (as well as other classes and methods inimportlib
).ImportWarning
and/orDeprecationWarning
will be raised as appropriate to help identify code which needs updating during this transition.The entire
distutils
namespace is deprecated, to be removed in Python 3.12. Refer to the module changes section for more information.Non-integer arguments to
random.randrange()
are deprecated. TheValueError
is deprecated in favor of aTypeError
. (Contributed by Serhiy Storchaka and Raymond Hettinger in bpo-37319.)The various
load_module()
methods ofimportlib
have been documented as deprecated since Python 3.6, but will now also trigger aDeprecationWarning
. Useexec_module()
instead. (Contributed by Brett Cannon in bpo-26131.)zimport.zipimporter.load_module()
has been deprecated in preference forexec_module()
. (Contributed by Brett Cannon in bpo-26131.)The use of
load_module()
by the import system now triggers anImportWarning
asexec_module()
is preferred. (Contributed by Brett Cannon in bpo-26131.)The use of
importlib.abc.MetaPathFinder.find_module()
andimportlib.abc.PathEntryFinder.find_module()
by the import system now trigger anImportWarning
asimportlib.abc.MetaPathFinder.find_spec()
andimportlib.abc.PathEntryFinder.find_spec()
are preferred, respectively. You can useimportlib.util.spec_from_loader()
to help in porting. (Contributed by Brett Cannon in bpo-42134.)The use of
importlib.abc.PathEntryFinder.find_loader()
by the import system now triggers anImportWarning
asimportlib.abc.PathEntryFinder.find_spec()
is preferred. You can useimportlib.util.spec_from_loader()
to help in porting. (Contributed by Brett Cannon in bpo-43672.)The import system now uses the
__spec__
attribute on modules before falling back onmodule_repr()
for a module’s__repr__()
method. Removal of the use ofmodule_repr()
is scheduled for Python 3.12. (Contributed by Brett Cannon in bpo-42137.)importlib.abc.Loader.module_repr()
,importlib.machinery.FrozenLoader.module_repr()
, andimportlib.machinery.BuiltinLoader.module_repr()
are deprecated and slated for removal in Python 3.12. (Contributed by Brett Cannon in bpo-42136.)sqlite3.OptimizedUnicode
has been undocumented and obsolete since Python 3.3, when it was made an alias tostr
. It is now deprecated, scheduled for removal in Python 3.12. (Contributed by Erlend E. Aasland in bpo-42264.)The undocumented built-in function
sqlite3.enable_shared_cache
is now deprecated, scheduled for removal in Python 3.12. Its use is strongly discouraged by the SQLite3 documentation. See the SQLite3 docs for more details. If shared cache must be used, open the database in URI mode using thecache=shared
query parameter. (Contributed by Erlend E. Aasland in bpo-24464.)
Removed¶
Removed special methods
__int__
,__float__
,__floordiv__
,__mod__
,__divmod__
,__rfloordiv__
,__rmod__
and__rdivmod__
of thecomplex
class. They always raised aTypeError
. (Contributed by Serhiy Storchaka in bpo-41974.)The
ParserBase.error()
method from the private and undocumented_markupbase
module has been removed.html.parser.HTMLParser
is the only subclass ofParserBase
and itserror()
implementation has already been removed in Python 3.5. (Contributed by Berker Peksag in bpo-31844.)Removed the
unicodedata.ucnhash_CAPI
attribute which was an internal PyCapsule object. The related private_PyUnicode_Name_CAPI
structure was moved to the internal C API. (Contributed by Victor Stinner in bpo-42157.)Removed the
parser
module, which was deprecated in 3.9 due to the switch to the new PEG parser, as well as all the C source and header files that were only being used by the old parser, includingnode.h
,parser.h
,graminit.h
andgrammar.h
.Removed the Public C API functions
PyParser_SimpleParseStringFlags()
,PyParser_SimpleParseStringFlagsFilename()
,PyParser_SimpleParseFileFlags()
andPyNode_Compile()
that were deprecated in 3.9 due to the switch to the new PEG parser.Removed the
formatter
module, which was deprecated in Python 3.4. It is somewhat obsolete, little used, and not tested. It was originally scheduled to be removed in Python 3.6, but such removals were delayed until after Python 2.7 EOL. Existing users should copy whatever classes they use into their code. (Contributed by Dong-hee Na and Terry J. Reedy in bpo-42299.)Removed the
PyModule_GetWarningsModule()
function that was useless now due to the _warnings module was converted to a builtin module in 2.6. (Contributed by Hai Shi in bpo-42599.)Remove deprecated aliases to Collections Abstract Base Classes from the
collections
module. (Contributed by Victor Stinner in bpo-37324.)The
loop
parameter has been removed from most ofasyncio
‘s high-level API following deprecation in Python 3.8. The motivation behind this change is multifold:This simplifies the high-level API.
The functions in the high-level API have been implicitly getting the current thread’s running event loop since Python 3.7. There isn’t a need to pass the event loop to the API in most normal use cases.
Event loop passing is error-prone especially when dealing with loops running in different threads.
Note that the low-level API will still accept
loop
. See Changes in the Python API for examples of how to replace existing code.(Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley in bpo-42392.)
Porting to Python 3.10¶
This section lists previously described changes and other bugfixes that may require changes to your code.
Changes in the Python API¶
The etype parameters of the
format_exception()
,format_exception_only()
, andprint_exception()
functions in thetraceback
module have been renamed to exc. (Contributed by Zackery Spytz and Matthias Bussonnier in bpo-26389.)atexit
: At Python exit, if a callback registered withatexit.register()
fails, its exception is now logged. Previously, only some exceptions were logged, and the last exception was always silently ignored. (Contributed by Victor Stinner in bpo-42639.)collections.abc.Callable
generic now flattens type parameters, similar to whattyping.Callable
currently does. This means thatcollections.abc.Callable[[int, str], str]
will have__args__
of(int, str, str)
; previously this was([int, str], str)
. Code which accesses the arguments viatyping.get_args()
or__args__
need to account for this change. Furthermore,TypeError
may be raised for invalid forms of parameterizingcollections.abc.Callable
which may have passed silently in Python 3.9. (Contributed by Ken Jin in bpo-42195.)socket.htons()
andsocket.ntohs()
now raiseOverflowError
instead ofDeprecationWarning
if the given parameter will not fit in a 16-bit unsigned integer. (Contributed by Erlend E. Aasland in bpo-42393.)The
loop
parameter has been removed from most ofasyncio
‘s high-level API following deprecation in Python 3.8.A coroutine that currently look like this:
async def foo(loop): await asyncio.sleep(1, loop=loop)
Should be replaced with this:
async def foo(): await asyncio.sleep(1)
If
foo()
was specifically designed not to run in the current thread’s running event loop (e.g. running in another thread’s event loop), consider usingasyncio.run_coroutine_threadsafe()
instead.(Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley in bpo-42392.)
The
types.FunctionType
constructor now inherits the current builtins if the globals dictionary has no"__builtins__"
key, rather than using{"None": None}
as builtins: same behavior aseval()
andexec()
functions. Defining a function withdef function(...): ...
in Python is not affected, globals cannot be overriden with this syntax: it also inherits the current builtins. (Contributed by Victor Stinner in bpo-42990.)
CPython bytecode changes¶
The
MAKE_FUNCTION
instruction accepts tuple of strings as annotations instead of dictionary. (Contributed by Yurii Karabas and Inada Naoki in bpo-42202)
Build Changes¶
The C99 functions
snprintf()
andvsnprintf()
are now required to build Python. (Contributed by Victor Stinner in bpo-36020.)sqlite3
requires SQLite 3.7.15 or higher. (Contributed by Sergey Fedoseev and Erlend E. Aasland bpo-40744 and bpo-40810.)The
atexit
module must now always be built as a built-in module. (Contributed by Victor Stinner in bpo-42639.)Added
--disable-test-modules
option to theconfigure
script: don’t build nor install test modules. (Contributed by Xavier de Gaye, Thomas Petazzoni and Peixing Xin in bpo-27640.)Add
--with-wheel-pkg-dir=PATH
option to the./configure
script. If specified, theensurepip
module looks forsetuptools
andpip
wheel packages in this directory: if both are present, these wheel packages are used instead of ensurepip bundled wheel packages.Some Linux distribution packaging policies recommend against bundling dependencies. For example, Fedora installs wheel packages in the
/usr/share/python-wheels/
directory and don’t install theensurepip._bundled
package.(Contributed by Victor Stinner in bpo-42856.)
NOTE: Reverted for now for the Debian/Ubuntu packages.
Add a new configure
--without-static-libpython
option to not build thelibpythonMAJOR.MINOR.a
static library and not install thepython.o
object file.(Contributed by Victor Stinner in bpo-43103.)
The
configure
script now uses thepkg-config
utility, if available, to detect the location of Tcl/Tk headers and libraries. As before, those locations can be explicitly specified with the--with-tcltk-includes
and--with-tcltk-libs
configuration options. (Contributed by Manolis Stamatogiannakis in bpo-42603.)Add
--with-openssl-rpath
option toconfigure
script. The option simplifies building Python with a custom OpenSSL installation, e.g../configure --with-openssl=/path/to/openssl --with-openssl-rpath=auto
. (Contributed by Christian Heimes in bpo-43466.)
C API Changes¶
New Features¶
The result of
PyNumber_Index()
now always has exact typeint
. Previously, the result could have been an instance of a subclass ofint
. (Contributed by Serhiy Storchaka in bpo-40792.)Add a new
orig_argv
member to thePyConfig
structure: the list of the original command line arguments passed to the Python executable. (Contributed by Victor Stinner in bpo-23427.)The
PyDateTime_DATE_GET_TZINFO()
andPyDateTime_TIME_GET_TZINFO()
macros have been added for accessing thetzinfo
attributes ofdatetime.datetime
anddatetime.time
objects. (Contributed by Zackery Spytz in bpo-30155.)Add a
PyCodec_Unregister()
function to unregister a codec search function. (Contributed by Hai Shi in bpo-41842.)The
PyIter_Send()
function was added to allow sending value into iterator without raisingStopIteration
exception. (Contributed by Vladimir Matveev in bpo-41756.)Added
PyUnicode_AsUTF8AndSize()
to the limited C API. (Contributed by Alex Gaynor in bpo-41784.)Added
PyModule_AddObjectRef()
function: similar toPyModule_AddObject()
but don’t steal a reference to the value on success. (Contributed by Victor Stinner in bpo-1635741.)Added
Py_NewRef()
andPy_XNewRef()
functions to increment the reference count of an object and return the object. (Contributed by Victor Stinner in bpo-42262.)The
PyType_FromSpecWithBases()
andPyType_FromModuleAndSpec()
functions now accept a single class as the bases argument. (Contributed by Serhiy Storchaka in bpo-42423.)The
PyType_FromModuleAndSpec()
function now accepts NULLtp_doc
slot. (Contributed by Hai Shi in bpo-41832.)The
PyType_GetSlot()
function can accept static types. (Contributed by Hai Shi and Petr Viktorin in bpo-41073.)Add a new
PySet_CheckExact()
function to the C-API to check if an object is an instance ofset
but not an instance of a subtype. (Contributed by Pablo Galindo in bpo-43277.)Added
PyErr_SetInterruptEx()
which allows passing a signal number to simulate. (Contributed by Antoine Pitrou in bpo-43356.)The limited C API is now supported if Python is built in debug mode (if the
Py_DEBUG
macro is defined). In the limited C API, thePy_INCREF()
andPy_DECREF()
functions are now implemented as opaque function calls, rather than accessing directly thePyObject.ob_refcnt
member, if Python is built in debug mode and thePy_LIMITED_API
macro targets Python 3.10 or newer. It became possible to support the limited C API in debug mode because thePyObject
structure is the same in release and debug mode since Python 3.8 (see bpo-36465).The limited C API is still not supported in the
--with-trace-refs
special build (Py_TRACE_REFS
macro). (Contributed by Victor Stinner in bpo-43688.)
Porting to Python 3.10¶
The
PY_SSIZE_T_CLEAN
macro must now be defined to usePyArg_ParseTuple()
andPy_BuildValue()
formats which use#
:es#
,et#
,s#
,u#
,y#
,z#
,U#
andZ#
. See Parsing arguments and building values and the PEP 353. (Contributed by Victor Stinner in bpo-40943.)Since
Py_REFCNT()
is changed to the inline static function,Py_REFCNT(obj) = new_refcnt
must be replaced withPy_SET_REFCNT(obj, new_refcnt)
: seePy_SET_REFCNT()
(available since Python 3.9). For backward compatibility, this macro can be used:#if PY_VERSION_HEX < 0x030900A4 # define Py_SET_REFCNT(obj, refcnt) ((Py_REFCNT(obj) = (refcnt)), (void)0) #endif
(Contributed by Victor Stinner in bpo-39573.)
Calling
PyDict_GetItem()
without GIL held had been allowed for historical reason. It is no longer allowed. (Contributed by Victor Stinner in bpo-40839.)PyUnicode_FromUnicode(NULL, size)
andPyUnicode_FromStringAndSize(NULL, size)
raiseDeprecationWarning
now. UsePyUnicode_New()
to allocate Unicode object without initial data. (Contributed by Inada Naoki in bpo-36346.)The private
_PyUnicode_Name_CAPI
structure of the PyCapsule APIunicodedata.ucnhash_CAPI
has been moved to the internal C API. (Contributed by Victor Stinner in bpo-42157.)Py_GetPath()
,Py_GetPrefix()
,Py_GetExecPrefix()
,Py_GetProgramFullPath()
,Py_GetPythonHome()
andPy_GetProgramName()
functions now returnNULL
if called beforePy_Initialize()
(before Python is initialized). Use the new Python Initialization Configuration API to get the Python Path Configuration.. (Contributed by Victor Stinner in bpo-42260.)PyList_SET_ITEM()
,PyTuple_SET_ITEM()
andPyCell_SET()
macros can no longer be used as l-value or r-value. For example,x = PyList_SET_ITEM(a, b, c)
andPyList_SET_ITEM(a, b, c) = x
now fail with a compiler error. It prevents bugs likeif (PyList_SET_ITEM (a, b, c) < 0) ...
test. (Contributed by Zackery Spytz and Victor Stinner in bpo-30459.)The non-limited API files
odictobject.h
,parser_interface.h
,picklebufobject.h
,pyarena.h
,pyctype.h
,pydebug.h
,pyfpe.h
, andpytime.h
have been moved to theInclude/cpython
directory. These files must not be included directly, as they are already included inPython.h
: Include Files. If they have been included directly, consider includingPython.h
instead. (Contributed by Nicholas Sim in bpo-35134)
Deprecated¶
The
PyUnicode_InternImmortal()
function is now deprecated and will be removed in Python 3.12: usePyUnicode_InternInPlace()
instead. (Contributed by Victor Stinner in bpo-41692.)
Removed¶
PyObject_AsCharBuffer()
,PyObject_AsReadBuffer()
,PyObject_CheckReadBuffer()
, andPyObject_AsWriteBuffer()
are removed. Please migrate to new buffer protocol;PyObject_GetBuffer()
andPyBuffer_Release()
. (Contributed by Inada Naoki in bpo-41103.)Removed
Py_UNICODE_str*
functions manipulatingPy_UNICODE*
strings. (Contributed by Inada Naoki in bpo-41123.)Py_UNICODE_strlen
: usePyUnicode_GetLength()
orPyUnicode_GET_LENGTH
Py_UNICODE_strcat
: usePyUnicode_CopyCharacters()
orPyUnicode_FromFormat()
Py_UNICODE_strcpy
,Py_UNICODE_strncpy
: usePyUnicode_CopyCharacters()
orPyUnicode_Substring()
Py_UNICODE_strcmp
: usePyUnicode_Compare()
Py_UNICODE_strncmp
: usePyUnicode_Tailmatch()
Py_UNICODE_strchr
,Py_UNICODE_strrchr
: usePyUnicode_FindChar()
Removed
PyUnicode_GetMax()
. Please migrate to new (PEP 393) APIs. (Contributed by Inada Naoki in bpo-41103.)Removed
PyLong_FromUnicode()
. Please migrate toPyLong_FromUnicodeObject()
. (Contributed by Inada Naoki in bpo-41103.)Removed
PyUnicode_AsUnicodeCopy()
. Please usePyUnicode_AsUCS4Copy()
orPyUnicode_AsWideCharString()
(Contributed by Inada Naoki in bpo-41103.)Removed
_Py_CheckRecursionLimit
variable: it has been replaced byceval.recursion_limit
of thePyInterpreterState
structure. (Contributed by Victor Stinner in bpo-41834.)Removed undocumented macros
Py_ALLOW_RECURSION
andPy_END_ALLOW_RECURSION
and therecursion_critical
field of thePyInterpreterState
structure. (Contributed by Serhiy Storchaka in bpo-41936.)Removed the undocumented
PyOS_InitInterrupts()
function. Initializing Python already implicitly installs signal handlers: seePyConfig.install_signal_handlers
. (Contributed by Victor Stinner in bpo-41713.)Remove the
PyAST_Validate()
function. It is no longer possible to build a AST object (mod_ty
type) with the public C API. The function was already excluded from the limited C API (PEP 384). (Contributed by Victor Stinner in bpo-43244.)Remove the
symtable.h
header file and the undocumented functions:PyST_GetScope()
PySymtable_Build()
PySymtable_BuildObject()
PySymtable_Free()
Py_SymtableString()
Py_SymtableStringObject()
The
Py_SymtableString()
function was part the stable ABI by mistake but it could not be used, because thesymtable.h
header file was excluded from the limited C API.Use Python
symtable
module instead. (Contributed by Victor Stinner in bpo-43244.)Remove
ast.h
,asdl.h
, andPython-ast.h
header files. These functions were undocumented and excluded from the limited C API. Most names defined by these header files were not prefixed byPy
and so could create names conflicts. For example,Python-ast.h
defined aYield
macro which was conflict with theYield
name used by the Windows<winbase.h>
header. Use the Pythonast
module instead. (Contributed by Victor Stinner in bpo-43244.)Remove the compiler and parser functions using
struct _mod
type, because the public AST C API was removed:PyAST_Compile()
PyAST_CompileEx()
PyAST_CompileObject()
PyFuture_FromAST()
PyFuture_FromASTObject()
PyParser_ASTFromFile()
PyParser_ASTFromFileObject()
PyParser_ASTFromFilename()
PyParser_ASTFromString()
PyParser_ASTFromStringObject()
These functions were undocumented and excluded from the limited C API. (Contributed by Victor Stinner in bpo-43244.)
Remove the
pyarena.h
header file with functions:PyArena_New()
PyArena_Free()
PyArena_Malloc()
PyArena_AddPyObject()
These functions were undocumented, excluded from the limited C API, and were only used internally by the compiler. (Contributed by Victor Stinner in bpo-43244.)