| 1 |
**************************** |
| 2 |
What's New In Python 3.10 |
| 3 |
**************************** |
| 4 |
|
| 5 |
:Editor: Pablo Galindo Salgado |
| 6 |
|
| 7 |
.. Rules for maintenance: |
| 8 |
|
| 9 |
* Anyone can add text to this document. Do not spend very much time |
| 10 |
on the wording of your changes, because your text will probably |
| 11 |
get rewritten to some degree. |
| 12 |
|
| 13 |
* The maintainer will go through Misc/NEWS periodically and add |
| 14 |
changes; it's therefore more important to add your changes to |
| 15 |
Misc/NEWS than to this file. |
| 16 |
|
| 17 |
* This is not a complete list of every single change; completeness |
| 18 |
is the purpose of Misc/NEWS. Some changes I consider too small |
| 19 |
or esoteric to include. If such a change is added to the text, |
| 20 |
I'll just remove it. (This is another reason you shouldn't spend |
| 21 |
too much time on writing your addition.) |
| 22 |
|
| 23 |
* If you want to draw your new text to the attention of the |
| 24 |
maintainer, add 'XXX' to the beginning of the paragraph or |
| 25 |
section. |
| 26 |
|
| 27 |
* It's OK to just add a fragmentary note about a change. For |
| 28 |
example: "XXX Describe the transmogrify() function added to the |
| 29 |
socket module." The maintainer will research the change and |
| 30 |
write the necessary text. |
| 31 |
|
| 32 |
* You can comment out your additions if you like, but it's not |
| 33 |
necessary (especially when a final release is some months away). |
| 34 |
|
| 35 |
* Credit the author of a patch or bugfix. Just the name is |
| 36 |
sufficient; the e-mail address isn't necessary. |
| 37 |
|
| 38 |
* It's helpful to add the bug/patch number as a comment: |
| 39 |
|
| 40 |
XXX Describe the transmogrify() function added to the socket |
| 41 |
module. |
| 42 |
(Contributed by P.Y. Developer in :issue:`12345`.) |
| 43 |
|
| 44 |
This saves the maintainer the effort of going through the git log |
| 45 |
when researching a change. |
| 46 |
|
| 47 |
This article explains the new features in Python 3.10, compared to 3.9. |
| 48 |
Python 3.10 was released on October 4, 2021. |
| 49 |
For full details, see the :ref:`changelog <changelog>`. |
| 50 |
|
| 51 |
Summary -- Release highlights |
| 52 |
============================= |
| 53 |
|
| 54 |
.. This section singles out the most important changes in Python 3.10. |
| 55 |
Brevity is key. |
| 56 |
|
| 57 |
|
| 58 |
.. PEP-sized items next. |
| 59 |
|
| 60 |
New syntax features: |
| 61 |
|
| 62 |
* :pep:`634`, Structural Pattern Matching: Specification |
| 63 |
* :pep:`635`, Structural Pattern Matching: Motivation and Rationale |
| 64 |
* :pep:`636`, Structural Pattern Matching: Tutorial |
| 65 |
* :issue:`12782`, Parenthesized context managers are now officially allowed. |
| 66 |
|
| 67 |
New features in the standard library: |
| 68 |
|
| 69 |
* :pep:`618`, Add Optional Length-Checking To zip. |
| 70 |
|
| 71 |
Interpreter improvements: |
| 72 |
|
| 73 |
* :pep:`626`, Precise line numbers for debugging and other tools. |
| 74 |
|
| 75 |
New typing features: |
| 76 |
|
| 77 |
* :pep:`604`, Allow writing union types as X | Y |
| 78 |
* :pep:`612`, Parameter Specification Variables |
| 79 |
* :pep:`613`, Explicit Type Aliases |
| 80 |
* :pep:`647`, User-Defined Type Guards |
| 81 |
|
| 82 |
Important deprecations, removals or restrictions: |
| 83 |
|
| 84 |
* :pep:`644`, Require OpenSSL 1.1.1 or newer |
| 85 |
* :pep:`632`, Deprecate distutils module. |
| 86 |
* :pep:`623`, Deprecate and prepare for the removal of the wstr member in PyUnicodeObject. |
| 87 |
* :pep:`624`, Remove Py_UNICODE encoder APIs |
| 88 |
* :pep:`597`, Add optional EncodingWarning |
| 89 |
|
| 90 |
|
| 91 |
New Features |
| 92 |
============ |
| 93 |
|
| 94 |
.. _whatsnew310-pep563: |
| 95 |
|
| 96 |
Parenthesized context managers |
| 97 |
------------------------------ |
| 98 |
|
| 99 |
Using enclosing parentheses for continuation across multiple lines |
| 100 |
in context managers is now supported. This allows formatting a long |
| 101 |
collection of context managers in multiple lines in a similar way |
| 102 |
as it was previously possible with import statements. For instance, |
| 103 |
all these examples are now valid: |
| 104 |
|
| 105 |
.. code-block:: python |
| 106 |
|
| 107 |
with (CtxManager() as example): |
| 108 |
... |
| 109 |
|
| 110 |
with ( |
| 111 |
CtxManager1(), |
| 112 |
CtxManager2() |
| 113 |
): |
| 114 |
... |
| 115 |
|
| 116 |
with (CtxManager1() as example, |
| 117 |
CtxManager2()): |
| 118 |
... |
| 119 |
|
| 120 |
with (CtxManager1(), |
| 121 |
CtxManager2() as example): |
| 122 |
... |
| 123 |
|
| 124 |
with ( |
| 125 |
CtxManager1() as example1, |
| 126 |
CtxManager2() as example2 |
| 127 |
): |
| 128 |
... |
| 129 |
|
| 130 |
it is also possible to use a trailing comma at the end of the |
| 131 |
enclosed group: |
| 132 |
|
| 133 |
.. code-block:: python |
| 134 |
|
| 135 |
with ( |
| 136 |
CtxManager1() as example1, |
| 137 |
CtxManager2() as example2, |
| 138 |
CtxManager3() as example3, |
| 139 |
): |
| 140 |
... |
| 141 |
|
| 142 |
This new syntax uses the non LL(1) capacities of the new parser. |
| 143 |
Check :pep:`617` for more details. |
| 144 |
|
| 145 |
(Contributed by Guido van Rossum, Pablo Galindo and Lysandros Nikolaou |
| 146 |
in :issue:`12782` and :issue:`40334`.) |
| 147 |
|
| 148 |
|
| 149 |
Better error messages |
| 150 |
--------------------- |
| 151 |
|
| 152 |
SyntaxErrors |
| 153 |
~~~~~~~~~~~~ |
| 154 |
|
| 155 |
When parsing code that contains unclosed parentheses or brackets the interpreter |
| 156 |
now includes the location of the unclosed bracket of parentheses instead of displaying |
| 157 |
*SyntaxError: unexpected EOF while parsing* or pointing to some incorrect location. |
| 158 |
For instance, consider the following code (notice the unclosed '{'): |
| 159 |
|
| 160 |
.. code-block:: python |
| 161 |
|
| 162 |
expected = {9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4, |
| 163 |
38: 4, 39: 4, 45: 5, 46: 5, 47: 5, 48: 5, 49: 5, 54: 6, |
| 164 |
some_other_code = foo() |
| 165 |
|
| 166 |
Previous versions of the interpreter reported confusing places as the location of |
| 167 |
the syntax error: |
| 168 |
|
| 169 |
.. code-block:: python |
| 170 |
|
| 171 |
File "example.py", line 3 |
| 172 |
some_other_code = foo() |
| 173 |
^ |
| 174 |
SyntaxError: invalid syntax |
| 175 |
|
| 176 |
but in Python 3.10 a more informative error is emitted: |
| 177 |
|
| 178 |
.. code-block:: python |
| 179 |
|
| 180 |
File "example.py", line 1 |
| 181 |
expected = {9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4, |
| 182 |
^ |
| 183 |
SyntaxError: '{' was never closed |
| 184 |
|
| 185 |
|
| 186 |
In a similar way, errors involving unclosed string literals (single and triple |
| 187 |
quoted) now point to the start of the string instead of reporting EOF/EOL. |
| 188 |
|
| 189 |
These improvements are inspired by previous work in the PyPy interpreter. |
| 190 |
|
| 191 |
(Contributed by Pablo Galindo in :issue:`42864` and Batuhan Taskaya in |
| 192 |
:issue:`40176`.) |
| 193 |
|
| 194 |
:exc:`SyntaxError` exceptions raised by the interpreter will now highlight the |
| 195 |
full error range of the expression that constitutes the syntax error itself, |
| 196 |
instead of just where the problem is detected. In this way, instead of displaying |
| 197 |
(before Python 3.10): |
| 198 |
|
| 199 |
.. code-block:: python |
| 200 |
|
| 201 |
>>> foo(x, z for z in range(10), t, w) |
| 202 |
File "<stdin>", line 1 |
| 203 |
foo(x, z for z in range(10), t, w) |
| 204 |
^ |
| 205 |
SyntaxError: Generator expression must be parenthesized |
| 206 |
|
| 207 |
now Python 3.10 will display the exception as: |
| 208 |
|
| 209 |
.. code-block:: python |
| 210 |
|
| 211 |
>>> foo(x, z for z in range(10), t, w) |
| 212 |
File "<stdin>", line 1 |
| 213 |
foo(x, z for z in range(10), t, w) |
| 214 |
^^^^^^^^^^^^^^^^^^^^ |
| 215 |
SyntaxError: Generator expression must be parenthesized |
| 216 |
|
| 217 |
This improvement was contributed by Pablo Galindo in :issue:`43914`. |
| 218 |
|
| 219 |
A considerable amount of new specialized messages for :exc:`SyntaxError` exceptions |
| 220 |
have been incorporated. Some of the most notable ones are as follows: |
| 221 |
|
| 222 |
* Missing ``:`` before blocks: |
| 223 |
|
| 224 |
.. code-block:: python |
| 225 |
|
| 226 |
>>> if rocket.position > event_horizon |
| 227 |
File "<stdin>", line 1 |
| 228 |
if rocket.position > event_horizon |
| 229 |
^ |
| 230 |
SyntaxError: expected ':' |
| 231 |
|
| 232 |
(Contributed by Pablo Galindo in :issue:`42997`.) |
| 233 |
|
| 234 |
* Unparenthesised tuples in comprehensions targets: |
| 235 |
|
| 236 |
.. code-block:: python |
| 237 |
|
| 238 |
>>> {x,y for x,y in zip('abcd', '1234')} |
| 239 |
File "<stdin>", line 1 |
| 240 |
{x,y for x,y in zip('abcd', '1234')} |
| 241 |
^ |
| 242 |
SyntaxError: did you forget parentheses around the comprehension target? |
| 243 |
|
| 244 |
(Contributed by Pablo Galindo in :issue:`43017`.) |
| 245 |
|
| 246 |
* Missing commas in collection literals and between expressions: |
| 247 |
|
| 248 |
.. code-block:: python |
| 249 |
|
| 250 |
>>> items = { |
| 251 |
... x: 1, |
| 252 |
... y: 2 |
| 253 |
... z: 3, |
| 254 |
File "<stdin>", line 3 |
| 255 |
y: 2 |
| 256 |
^ |
| 257 |
SyntaxError: invalid syntax. Perhaps you forgot a comma? |
| 258 |
|
| 259 |
(Contributed by Pablo Galindo in :issue:`43822`.) |
| 260 |
|
| 261 |
* Multiple Exception types without parentheses: |
| 262 |
|
| 263 |
.. code-block:: python |
| 264 |
|
| 265 |
>>> try: |
| 266 |
... build_dyson_sphere() |
| 267 |
... except NotEnoughScienceError, NotEnoughResourcesError: |
| 268 |
File "<stdin>", line 3 |
| 269 |
except NotEnoughScienceError, NotEnoughResourcesError: |
| 270 |
^ |
| 271 |
SyntaxError: multiple exception types must be parenthesized |
| 272 |
|
| 273 |
(Contributed by Pablo Galindo in :issue:`43149`.) |
| 274 |
|
| 275 |
* Missing ``:`` and values in dictionary literals: |
| 276 |
|
| 277 |
.. code-block:: python |
| 278 |
|
| 279 |
>>> values = { |
| 280 |
... x: 1, |
| 281 |
... y: 2, |
| 282 |
... z: |
| 283 |
... } |
| 284 |
File "<stdin>", line 4 |
| 285 |
z: |
| 286 |
^ |
| 287 |
SyntaxError: expression expected after dictionary key and ':' |
| 288 |
|
| 289 |
>>> values = {x:1, y:2, z w:3} |
| 290 |
File "<stdin>", line 1 |
| 291 |
values = {x:1, y:2, z w:3} |
| 292 |
^ |
| 293 |
SyntaxError: ':' expected after dictionary key |
| 294 |
|
| 295 |
(Contributed by Pablo Galindo in :issue:`43823`.) |
| 296 |
|
| 297 |
* ``try`` blocks without ``except`` or ``finally`` blocks: |
| 298 |
|
| 299 |
.. code-block:: python |
| 300 |
|
| 301 |
>>> try: |
| 302 |
... x = 2 |
| 303 |
... something = 3 |
| 304 |
File "<stdin>", line 3 |
| 305 |
something = 3 |
| 306 |
^^^^^^^^^ |
| 307 |
SyntaxError: expected 'except' or 'finally' block |
| 308 |
|
| 309 |
(Contributed by Pablo Galindo in :issue:`44305`.) |
| 310 |
|
| 311 |
* Usage of ``=`` instead of ``==`` in comparisons: |
| 312 |
|
| 313 |
.. code-block:: python |
| 314 |
|
| 315 |
>>> if rocket.position = event_horizon: |
| 316 |
File "<stdin>", line 1 |
| 317 |
if rocket.position = event_horizon: |
| 318 |
^ |
| 319 |
SyntaxError: cannot assign to attribute here. Maybe you meant '==' instead of '='? |
| 320 |
|
| 321 |
(Contributed by Pablo Galindo in :issue:`43797`.) |
| 322 |
|
| 323 |
* Usage of ``*`` in f-strings: |
| 324 |
|
| 325 |
.. code-block:: python |
| 326 |
|
| 327 |
>>> f"Black holes {*all_black_holes} and revelations" |
| 328 |
File "<stdin>", line 1 |
| 329 |
(*all_black_holes) |
| 330 |
^ |
| 331 |
SyntaxError: f-string: cannot use starred expression here |
| 332 |
|
| 333 |
(Contributed by Pablo Galindo in :issue:`41064`.) |
| 334 |
|
| 335 |
IndentationErrors |
| 336 |
~~~~~~~~~~~~~~~~~ |
| 337 |
|
| 338 |
Many :exc:`IndentationError` exceptions now have more context regarding what kind of block |
| 339 |
was expecting an indentation, including the location of the statement: |
| 340 |
|
| 341 |
.. code-block:: python |
| 342 |
|
| 343 |
>>> def foo(): |
| 344 |
... if lel: |
| 345 |
... x = 2 |
| 346 |
File "<stdin>", line 3 |
| 347 |
x = 2 |
| 348 |
^ |
| 349 |
IndentationError: expected an indented block after 'if' statement in line 2 |
| 350 |
|
| 351 |
|
| 352 |
AttributeErrors |
| 353 |
~~~~~~~~~~~~~~~ |
| 354 |
|
| 355 |
When printing :exc:`AttributeError`, :c:func:`!PyErr_Display` will offer |
| 356 |
suggestions of similar attribute names in the object that the exception was |
| 357 |
raised from: |
| 358 |
|
| 359 |
.. code-block:: python |
| 360 |
|
| 361 |
>>> collections.namedtoplo |
| 362 |
Traceback (most recent call last): |
| 363 |
File "<stdin>", line 1, in <module> |
| 364 |
AttributeError: module 'collections' has no attribute 'namedtoplo'. Did you mean: namedtuple? |
| 365 |
|
| 366 |
(Contributed by Pablo Galindo in :issue:`38530`.) |
| 367 |
|
| 368 |
.. warning:: |
| 369 |
Notice this won't work if :c:func:`!PyErr_Display` is not called to display the error |
| 370 |
which can happen if some other custom error display function is used. This is a common |
| 371 |
scenario in some REPLs like IPython. |
| 372 |
|
| 373 |
NameErrors |
| 374 |
~~~~~~~~~~ |
| 375 |
|
| 376 |
When printing :exc:`NameError` raised by the interpreter, :c:func:`!PyErr_Display` |
| 377 |
will offer suggestions of similar variable names in the function that the exception |
| 378 |
was raised from: |
| 379 |
|
| 380 |
.. code-block:: python |
| 381 |
|
| 382 |
>>> schwarzschild_black_hole = None |
| 383 |
>>> schwarschild_black_hole |
| 384 |
Traceback (most recent call last): |
| 385 |
File "<stdin>", line 1, in <module> |
| 386 |
NameError: name 'schwarschild_black_hole' is not defined. Did you mean: schwarzschild_black_hole? |
| 387 |
|
| 388 |
(Contributed by Pablo Galindo in :issue:`38530`.) |
| 389 |
|
| 390 |
.. warning:: |
| 391 |
Notice this won't work if :c:func:`!PyErr_Display` is not called to display the error, |
| 392 |
which can happen if some other custom error display function is used. This is a common |
| 393 |
scenario in some REPLs like IPython. |
| 394 |
|
| 395 |
|
| 396 |
PEP 626: Precise line numbers for debugging and other tools |
| 397 |
----------------------------------------------------------- |
| 398 |
|
| 399 |
PEP 626 brings more precise and reliable line numbers for debugging, profiling and coverage tools. |
| 400 |
Tracing events, with the correct line number, are generated for all lines of code executed and only for lines of code that are executed. |
| 401 |
|
| 402 |
The :attr:`~frame.f_lineno` attribute of frame objects will always contain the |
| 403 |
expected line number. |
| 404 |
|
| 405 |
The :attr:`~codeobject.co_lnotab` attribute of |
| 406 |
:ref:`code objects <code-objects>` is deprecated and |
| 407 |
will be removed in 3.12. |
| 408 |
Code that needs to convert from offset to line number should use the new |
| 409 |
:meth:`~codeobject.co_lines` method instead. |
| 410 |
|
| 411 |
PEP 634: Structural Pattern Matching |
| 412 |
------------------------------------ |
| 413 |
|
| 414 |
Structural pattern matching has been added in the form of a *match statement* |
| 415 |
and *case statements* of patterns with associated actions. Patterns |
| 416 |
consist of sequences, mappings, primitive data types as well as class instances. |
| 417 |
Pattern matching enables programs to extract information from complex data types, |
| 418 |
branch on the structure of data, and apply specific actions based on different |
| 419 |
forms of data. |
| 420 |
|
| 421 |
Syntax and operations |
| 422 |
~~~~~~~~~~~~~~~~~~~~~ |
| 423 |
|
| 424 |
The generic syntax of pattern matching is:: |
| 425 |
|
| 426 |
match subject: |
| 427 |
case <pattern_1>: |
| 428 |
<action_1> |
| 429 |
case <pattern_2>: |
| 430 |
<action_2> |
| 431 |
case <pattern_3>: |
| 432 |
<action_3> |
| 433 |
case _: |
| 434 |
<action_wildcard> |
| 435 |
|
| 436 |
A match statement takes an expression and compares its value to successive |
| 437 |
patterns given as one or more case blocks. Specifically, pattern matching |
| 438 |
operates by: |
| 439 |
|
| 440 |
1. using data with type and shape (the ``subject``) |
| 441 |
2. evaluating the ``subject`` in the ``match`` statement |
| 442 |
3. comparing the subject with each pattern in a ``case`` statement |
| 443 |
from top to bottom until a match is confirmed. |
| 444 |
4. executing the action associated with the pattern of the confirmed |
| 445 |
match |
| 446 |
5. If an exact match is not confirmed, the last case, a wildcard ``_``, |
| 447 |
if provided, will be used as the matching case. If an exact match is |
| 448 |
not confirmed and a wildcard case does not exist, the entire match |
| 449 |
block is a no-op. |
| 450 |
|
| 451 |
Declarative approach |
| 452 |
~~~~~~~~~~~~~~~~~~~~ |
| 453 |
|
| 454 |
Readers may be aware of pattern matching through the simple example of matching |
| 455 |
a subject (data object) to a literal (pattern) with the switch statement found |
| 456 |
in C, Java or JavaScript (and many other languages). Often the switch statement |
| 457 |
is used for comparison of an object/expression with case statements containing |
| 458 |
literals. |
| 459 |
|
| 460 |
More powerful examples of pattern matching can be found in languages such as |
| 461 |
Scala and Elixir. With structural pattern matching, the approach is "declarative" and |
| 462 |
explicitly states the conditions (the patterns) for data to match. |
| 463 |
|
| 464 |
While an "imperative" series of instructions using nested "if" statements |
| 465 |
could be used to accomplish something similar to structural pattern matching, |
| 466 |
it is less clear than the "declarative" approach. Instead the "declarative" |
| 467 |
approach states the conditions to meet for a match and is more readable through |
| 468 |
its explicit patterns. While structural pattern matching can be used in its |
| 469 |
simplest form comparing a variable to a literal in a case statement, its |
| 470 |
true value for Python lies in its handling of the subject's type and shape. |
| 471 |
|
| 472 |
Simple pattern: match to a literal |
| 473 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 474 |
|
| 475 |
Let's look at this example as pattern matching in its simplest form: a value, |
| 476 |
the subject, being matched to several literals, the patterns. In the example |
| 477 |
below, ``status`` is the subject of the match statement. The patterns are |
| 478 |
each of the case statements, where literals represent request status codes. |
| 479 |
The associated action to the case is executed after a match:: |
| 480 |
|
| 481 |
def http_error(status): |
| 482 |
match status: |
| 483 |
case 400: |
| 484 |
return "Bad request" |
| 485 |
case 404: |
| 486 |
return "Not found" |
| 487 |
case 418: |
| 488 |
return "I'm a teapot" |
| 489 |
case _: |
| 490 |
return "Something's wrong with the internet" |
| 491 |
|
| 492 |
If the above function is passed a ``status`` of 418, "I'm a teapot" is returned. |
| 493 |
If the above function is passed a ``status`` of 500, the case statement with |
| 494 |
``_`` will match as a wildcard, and "Something's wrong with the internet" is |
| 495 |
returned. |
| 496 |
Note the last block: the variable name, ``_``, acts as a *wildcard* and insures |
| 497 |
the subject will always match. The use of ``_`` is optional. |
| 498 |
|
| 499 |
You can combine several literals in a single pattern using ``|`` ("or"):: |
| 500 |
|
| 501 |
case 401 | 403 | 404: |
| 502 |
return "Not allowed" |
| 503 |
|
| 504 |
Behavior without the wildcard |
| 505 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 506 |
|
| 507 |
If we modify the above example by removing the last case block, the example |
| 508 |
becomes:: |
| 509 |
|
| 510 |
def http_error(status): |
| 511 |
match status: |
| 512 |
case 400: |
| 513 |
return "Bad request" |
| 514 |
case 404: |
| 515 |
return "Not found" |
| 516 |
case 418: |
| 517 |
return "I'm a teapot" |
| 518 |
|
| 519 |
Without the use of ``_`` in a case statement, a match may not exist. If no |
| 520 |
match exists, the behavior is a no-op. For example, if ``status`` of 500 is |
| 521 |
passed, a no-op occurs. |
| 522 |
|
| 523 |
Patterns with a literal and variable |
| 524 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 525 |
|
| 526 |
Patterns can look like unpacking assignments, and a pattern may be used to bind |
| 527 |
variables. In this example, a data point can be unpacked to its x-coordinate |
| 528 |
and y-coordinate:: |
| 529 |
|
| 530 |
# point is an (x, y) tuple |
| 531 |
match point: |
| 532 |
case (0, 0): |
| 533 |
print("Origin") |
| 534 |
case (0, y): |
| 535 |
print(f"Y={y}") |
| 536 |
case (x, 0): |
| 537 |
print(f"X={x}") |
| 538 |
case (x, y): |
| 539 |
print(f"X={x}, Y={y}") |
| 540 |
case _: |
| 541 |
raise ValueError("Not a point") |
| 542 |
|
| 543 |
The first pattern has two literals, ``(0, 0)``, and may be thought of as an |
| 544 |
extension of the literal pattern shown above. The next two patterns combine a |
| 545 |
literal and a variable, and the variable *binds* a value from the subject |
| 546 |
(``point``). The fourth pattern captures two values, which makes it |
| 547 |
conceptually similar to the unpacking assignment ``(x, y) = point``. |
| 548 |
|
| 549 |
Patterns and classes |
| 550 |
~~~~~~~~~~~~~~~~~~~~ |
| 551 |
|
| 552 |
If you are using classes to structure your data, you can use as a pattern |
| 553 |
the class name followed by an argument list resembling a constructor. This |
| 554 |
pattern has the ability to capture instance attributes into variables:: |
| 555 |
|
| 556 |
class Point: |
| 557 |
def __init__(self, x, y): |
| 558 |
self.x = x |
| 559 |
self.y = y |
| 560 |
|
| 561 |
def location(point): |
| 562 |
match point: |
| 563 |
case Point(x=0, y=0): |
| 564 |
print("Origin is the point's location.") |
| 565 |
case Point(x=0, y=y): |
| 566 |
print(f"Y={y} and the point is on the y-axis.") |
| 567 |
case Point(x=x, y=0): |
| 568 |
print(f"X={x} and the point is on the x-axis.") |
| 569 |
case Point(): |
| 570 |
print("The point is located somewhere else on the plane.") |
| 571 |
case _: |
| 572 |
print("Not a point") |
| 573 |
|
| 574 |
Patterns with positional parameters |
| 575 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 576 |
|
| 577 |
You can use positional parameters with some builtin classes that provide an |
| 578 |
ordering for their attributes (e.g. dataclasses). You can also define a specific |
| 579 |
position for attributes in patterns by setting the ``__match_args__`` special |
| 580 |
attribute in your classes. If it's set to ("x", "y"), the following patterns |
| 581 |
are all equivalent (and all bind the ``y`` attribute to the ``var`` variable):: |
| 582 |
|
| 583 |
Point(1, var) |
| 584 |
Point(1, y=var) |
| 585 |
Point(x=1, y=var) |
| 586 |
Point(y=var, x=1) |
| 587 |
|
| 588 |
Nested patterns |
| 589 |
~~~~~~~~~~~~~~~ |
| 590 |
|
| 591 |
Patterns can be arbitrarily nested. For example, if our data is a short |
| 592 |
list of points, it could be matched like this:: |
| 593 |
|
| 594 |
match points: |
| 595 |
case []: |
| 596 |
print("No points in the list.") |
| 597 |
case [Point(0, 0)]: |
| 598 |
print("The origin is the only point in the list.") |
| 599 |
case [Point(x, y)]: |
| 600 |
print(f"A single point {x}, {y} is in the list.") |
| 601 |
case [Point(0, y1), Point(0, y2)]: |
| 602 |
print(f"Two points on the Y axis at {y1}, {y2} are in the list.") |
| 603 |
case _: |
| 604 |
print("Something else is found in the list.") |
| 605 |
|
| 606 |
Complex patterns and the wildcard |
| 607 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 608 |
|
| 609 |
To this point, the examples have used ``_`` alone in the last case statement. |
| 610 |
A wildcard can be used in more complex patterns, such as ``('error', code, _)``. |
| 611 |
For example:: |
| 612 |
|
| 613 |
match test_variable: |
| 614 |
case ('warning', code, 40): |
| 615 |
print("A warning has been received.") |
| 616 |
case ('error', code, _): |
| 617 |
print(f"An error {code} occurred.") |
| 618 |
|
| 619 |
In the above case, ``test_variable`` will match for ('error', code, 100) and |
| 620 |
('error', code, 800). |
| 621 |
|
| 622 |
Guard |
| 623 |
~~~~~ |
| 624 |
|
| 625 |
We can add an ``if`` clause to a pattern, known as a "guard". If the |
| 626 |
guard is false, ``match`` goes on to try the next case block. Note |
| 627 |
that value capture happens before the guard is evaluated:: |
| 628 |
|
| 629 |
match point: |
| 630 |
case Point(x, y) if x == y: |
| 631 |
print(f"The point is located on the diagonal Y=X at {x}.") |
| 632 |
case Point(x, y): |
| 633 |
print(f"Point is not on the diagonal.") |
| 634 |
|
| 635 |
Other Key Features |
| 636 |
~~~~~~~~~~~~~~~~~~ |
| 637 |
|
| 638 |
Several other key features: |
| 639 |
|
| 640 |
- Like unpacking assignments, tuple and list patterns have exactly the |
| 641 |
same meaning and actually match arbitrary sequences. Technically, |
| 642 |
the subject must be a sequence. |
| 643 |
Therefore, an important exception is that patterns don't match iterators. |
| 644 |
Also, to prevent a common mistake, sequence patterns don't match strings. |
| 645 |
|
| 646 |
- Sequence patterns support wildcards: ``[x, y, *rest]`` and ``(x, y, |
| 647 |
*rest)`` work similar to wildcards in unpacking assignments. The |
| 648 |
name after ``*`` may also be ``_``, so ``(x, y, *_)`` matches a sequence |
| 649 |
of at least two items without binding the remaining items. |
| 650 |
|
| 651 |
- Mapping patterns: ``{"bandwidth": b, "latency": l}`` captures the |
| 652 |
``"bandwidth"`` and ``"latency"`` values from a dict. Unlike sequence |
| 653 |
patterns, extra keys are ignored. A wildcard ``**rest`` is also |
| 654 |
supported. (But ``**_`` would be redundant, so is not allowed.) |
| 655 |
|
| 656 |
- Subpatterns may be captured using the ``as`` keyword:: |
| 657 |
|
| 658 |
case (Point(x1, y1), Point(x2, y2) as p2): ... |
| 659 |
|
| 660 |
This binds x1, y1, x2, y2 like you would expect without the ``as`` clause, |
| 661 |
and p2 to the entire second item of the subject. |
| 662 |
|
| 663 |
- Most literals are compared by equality. However, the singletons ``True``, |
| 664 |
``False`` and ``None`` are compared by identity. |
| 665 |
|
| 666 |
- Named constants may be used in patterns. These named constants must be |
| 667 |
dotted names to prevent the constant from being interpreted as a capture |
| 668 |
variable:: |
| 669 |
|
| 670 |
from enum import Enum |
| 671 |
class Color(Enum): |
| 672 |
RED = 0 |
| 673 |
GREEN = 1 |
| 674 |
BLUE = 2 |
| 675 |
|
| 676 |
color = Color.GREEN |
| 677 |
match color: |
| 678 |
case Color.RED: |
| 679 |
print("I see red!") |
| 680 |
case Color.GREEN: |
| 681 |
print("Grass is green") |
| 682 |
case Color.BLUE: |
| 683 |
print("I'm feeling the blues :(") |
| 684 |
|
| 685 |
For the full specification see :pep:`634`. Motivation and rationale |
| 686 |
are in :pep:`635`, and a longer tutorial is in :pep:`636`. |
| 687 |
|
| 688 |
|
| 689 |
.. _whatsnew310-pep597: |
| 690 |
|
| 691 |
Optional ``EncodingWarning`` and ``encoding="locale"`` option |
| 692 |
------------------------------------------------------------- |
| 693 |
|
| 694 |
The default encoding of :class:`~io.TextIOWrapper` and :func:`open` is |
| 695 |
platform and locale dependent. Since UTF-8 is used on most Unix |
| 696 |
platforms, omitting ``encoding`` option when opening UTF-8 files |
| 697 |
(e.g. JSON, YAML, TOML, Markdown) is a very common bug. For example:: |
| 698 |
|
| 699 |
# BUG: "rb" mode or encoding="utf-8" should be used. |
| 700 |
with open("data.json") as f: |
| 701 |
data = json.load(f) |
| 702 |
|
| 703 |
To find this type of bug, an optional ``EncodingWarning`` is added. |
| 704 |
It is emitted when :data:`sys.flags.warn_default_encoding <sys.flags>` |
| 705 |
is true and locale-specific default encoding is used. |
| 706 |
|
| 707 |
``-X warn_default_encoding`` option and :envvar:`PYTHONWARNDEFAULTENCODING` |
| 708 |
are added to enable the warning. |
| 709 |
|
| 710 |
See :ref:`io-text-encoding` for more information. |
| 711 |
|
| 712 |
.. _new-feat-related-type-hints: |
| 713 |
|
| 714 |
New Features Related to Type Hints |
| 715 |
================================== |
| 716 |
|
| 717 |
This section covers major changes affecting :pep:`484` type hints and |
| 718 |
the :mod:`typing` module. |
| 719 |
|
| 720 |
|
| 721 |
PEP 604: New Type Union Operator |
| 722 |
-------------------------------- |
| 723 |
|
| 724 |
A new type union operator was introduced which enables the syntax ``X | Y``. |
| 725 |
This provides a cleaner way of expressing 'either type X or type Y' instead of |
| 726 |
using :class:`typing.Union`, especially in type hints. |
| 727 |
|
| 728 |
In previous versions of Python, to apply a type hint for functions accepting |
| 729 |
arguments of multiple types, :class:`typing.Union` was used:: |
| 730 |
|
| 731 |
def square(number: Union[int, float]) -> Union[int, float]: |
| 732 |
return number ** 2 |
| 733 |
|
| 734 |
|
| 735 |
Type hints can now be written in a more succinct manner:: |
| 736 |
|
| 737 |
def square(number: int | float) -> int | float: |
| 738 |
return number ** 2 |
| 739 |
|
| 740 |
|
| 741 |
This new syntax is also accepted as the second argument to :func:`isinstance` |
| 742 |
and :func:`issubclass`:: |
| 743 |
|
| 744 |
>>> isinstance(1, int | str) |
| 745 |
True |
| 746 |
|
| 747 |
See :ref:`types-union` and :pep:`604` for more details. |
| 748 |
|
| 749 |
(Contributed by Maggie Moss and Philippe Prados in :issue:`41428`, |
| 750 |
with additions by Yurii Karabas and Serhiy Storchaka in :issue:`44490`.) |
| 751 |
|
| 752 |
|
| 753 |
PEP 612: Parameter Specification Variables |
| 754 |
------------------------------------------ |
| 755 |
|
| 756 |
Two new options to improve the information provided to static type checkers for |
| 757 |
:pep:`484`\ 's ``Callable`` have been added to the :mod:`typing` module. |
| 758 |
|
| 759 |
The first is the parameter specification variable. They are used to forward the |
| 760 |
parameter types of one callable to another callable -- a pattern commonly |
| 761 |
found in higher order functions and decorators. Examples of usage can be found |
| 762 |
in :class:`typing.ParamSpec`. Previously, there was no easy way to type annotate |
| 763 |
dependency of parameter types in such a precise manner. |
| 764 |
|
| 765 |
The second option is the new ``Concatenate`` operator. It's used in conjunction |
| 766 |
with parameter specification variables to type annotate a higher order callable |
| 767 |
which adds or removes parameters of another callable. Examples of usage can |
| 768 |
be found in :class:`typing.Concatenate`. |
| 769 |
|
| 770 |
See :class:`typing.Callable`, :class:`typing.ParamSpec`, |
| 771 |
:class:`typing.Concatenate`, :class:`typing.ParamSpecArgs`, |
| 772 |
:class:`typing.ParamSpecKwargs`, and :pep:`612` for more details. |
| 773 |
|
| 774 |
(Contributed by Ken Jin in :issue:`41559`, with minor enhancements by Jelle |
| 775 |
Zijlstra in :issue:`43783`. PEP written by Mark Mendoza.) |
| 776 |
|
| 777 |
|
| 778 |
PEP 613: TypeAlias |
| 779 |
------------------ |
| 780 |
|
| 781 |
:pep:`484` introduced the concept of type aliases, only requiring them to be |
| 782 |
top-level unannotated assignments. This simplicity sometimes made it difficult |
| 783 |
for type checkers to distinguish between type aliases and ordinary assignments, |
| 784 |
especially when forward references or invalid types were involved. Compare:: |
| 785 |
|
| 786 |
StrCache = 'Cache[str]' # a type alias |
| 787 |
LOG_PREFIX = 'LOG[DEBUG]' # a module constant |
| 788 |
|
| 789 |
Now the :mod:`typing` module has a special value :data:`~typing.TypeAlias` |
| 790 |
which lets you declare type aliases more explicitly:: |
| 791 |
|
| 792 |
StrCache: TypeAlias = 'Cache[str]' # a type alias |
| 793 |
LOG_PREFIX = 'LOG[DEBUG]' # a module constant |
| 794 |
|
| 795 |
See :pep:`613` for more details. |
| 796 |
|
| 797 |
(Contributed by Mikhail Golubev in :issue:`41923`.) |
| 798 |
|
| 799 |
PEP 647: User-Defined Type Guards |
| 800 |
--------------------------------- |
| 801 |
|
| 802 |
:data:`~typing.TypeGuard` has been added to the :mod:`typing` module to annotate |
| 803 |
type guard functions and improve information provided to static type checkers |
| 804 |
during type narrowing. For more information, please see |
| 805 |
:data:`~typing.TypeGuard`\ 's documentation, and :pep:`647`. |
| 806 |
|
| 807 |
(Contributed by Ken Jin and Guido van Rossum in :issue:`43766`. |
| 808 |
PEP written by Eric Traut.) |
| 809 |
|
| 810 |
Other Language Changes |
| 811 |
====================== |
| 812 |
|
| 813 |
* The :class:`int` type has a new method :meth:`int.bit_count`, returning the |
| 814 |
number of ones in the binary expansion of a given integer, also known |
| 815 |
as the population count. (Contributed by Niklas Fiekas in :issue:`29882`.) |
| 816 |
|
| 817 |
* The views returned by :meth:`dict.keys`, :meth:`dict.values` and |
| 818 |
:meth:`dict.items` now all have a ``mapping`` attribute that gives a |
| 819 |
:class:`types.MappingProxyType` object wrapping the original |
| 820 |
dictionary. (Contributed by Dennis Sweeney in :issue:`40890`.) |
| 821 |
|
| 822 |
* :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used |
| 823 |
to require that all the iterables have an equal length. |
| 824 |
|
| 825 |
* Builtin and extension functions that take integer arguments no longer accept |
| 826 |
:class:`~decimal.Decimal`\ s, :class:`~fractions.Fraction`\ s and other |
| 827 |
objects that can be converted to integers only with a loss (e.g. that have |
| 828 |
the :meth:`~object.__int__` method but do not have the |
| 829 |
:meth:`~object.__index__` method). |
| 830 |
(Contributed by Serhiy Storchaka in :issue:`37999`.) |
| 831 |
|
| 832 |
* If :func:`object.__ipow__` returns :data:`NotImplemented`, the operator will |
| 833 |
correctly fall back to :func:`object.__pow__` and :func:`object.__rpow__` as expected. |
| 834 |
(Contributed by Alex Shkop in :issue:`38302`.) |
| 835 |
|
| 836 |
* Assignment expressions can now be used unparenthesized within set literals |
| 837 |
and set comprehensions, as well as in sequence indexes (but not slices). |
| 838 |
|
| 839 |
* Functions have a new ``__builtins__`` attribute which is used to look for |
| 840 |
builtin symbols when a function is executed, instead of looking into |
| 841 |
``__globals__['__builtins__']``. The attribute is initialized from |
| 842 |
``__globals__["__builtins__"]`` if it exists, else from the current builtins. |
| 843 |
(Contributed by Mark Shannon in :issue:`42990`.) |
| 844 |
|
| 845 |
* Two new builtin functions -- :func:`aiter` and :func:`anext` have been added |
| 846 |
to provide asynchronous counterparts to :func:`iter` and :func:`next`, |
| 847 |
respectively. |
| 848 |
(Contributed by Joshua Bronson, Daniel Pope, and Justin Wang in :issue:`31861`.) |
| 849 |
|
| 850 |
* Static methods (:deco:`staticmethod`) and class methods |
| 851 |
(:deco:`classmethod`) now inherit the method attributes |
| 852 |
(``__module__``, ``__name__``, ``__qualname__``, ``__doc__``, |
| 853 |
``__annotations__``) and have a new ``__wrapped__`` attribute. |
| 854 |
Moreover, static methods are now callable as regular functions. |
| 855 |
(Contributed by Victor Stinner in :issue:`43682`.) |
| 856 |
|
| 857 |
* Annotations for complex targets (everything beside ``simple name`` targets |
| 858 |
defined by :pep:`526`) no longer cause any runtime effects with ``from __future__ import annotations``. |
| 859 |
(Contributed by Batuhan Taskaya in :issue:`42737`.) |
| 860 |
|
| 861 |
* Class and module objects now lazy-create empty annotations dicts on demand. |
| 862 |
The annotations dicts are stored in the object’s ``__dict__`` for |
| 863 |
backwards compatibility. This improves the best practices for working |
| 864 |
with ``__annotations__``; for more information, please see |
| 865 |
:ref:`annotations-howto`. |
| 866 |
(Contributed by Larry Hastings in :issue:`43901`.) |
| 867 |
|
| 868 |
* Annotations consist of ``yield``, ``yield from``, ``await`` or named expressions |
| 869 |
are now forbidden under ``from __future__ import annotations`` due to their side |
| 870 |
effects. |
| 871 |
(Contributed by Batuhan Taskaya in :issue:`42725`.) |
| 872 |
|
| 873 |
* Usage of unbound variables, ``super()`` and other expressions that might |
| 874 |
alter the processing of symbol table as annotations are now rendered |
| 875 |
effectless under ``from __future__ import annotations``. |
| 876 |
(Contributed by Batuhan Taskaya in :issue:`42725`.) |
| 877 |
|
| 878 |
* Hashes of NaN values of both :class:`float` type and |
| 879 |
:class:`decimal.Decimal` type now depend on object identity. Formerly, they |
| 880 |
always hashed to ``0`` even though NaN values are not equal to one another. |
| 881 |
This caused potentially quadratic runtime behavior due to excessive hash |
| 882 |
collisions when creating dictionaries and sets containing multiple NaNs. |
| 883 |
(Contributed by Raymond Hettinger in :issue:`43475`.) |
| 884 |
|
| 885 |
* A :exc:`SyntaxError` (instead of a :exc:`NameError`) will be raised when deleting |
| 886 |
the :const:`__debug__` constant. (Contributed by Donghee Na in :issue:`45000`.) |
| 887 |
|
| 888 |
* :exc:`SyntaxError` exceptions now have ``end_lineno`` and |
| 889 |
``end_offset`` attributes. They will be ``None`` if not determined. |
| 890 |
(Contributed by Pablo Galindo in :issue:`43914`.) |
| 891 |
|
| 892 |
New Modules |
| 893 |
=========== |
| 894 |
|
| 895 |
* None. |
| 896 |
|
| 897 |
|
| 898 |
Improved Modules |
| 899 |
================ |
| 900 |
|
| 901 |
asyncio |
| 902 |
------- |
| 903 |
|
| 904 |
Add missing :meth:`~asyncio.loop.connect_accepted_socket` |
| 905 |
method. |
| 906 |
(Contributed by Alex Grönholm in :issue:`41332`.) |
| 907 |
|
| 908 |
argparse |
| 909 |
-------- |
| 910 |
|
| 911 |
Misleading phrase "optional arguments" was replaced with "options" in argparse help. Some tests might require adaptation if they rely on exact output match. |
| 912 |
(Contributed by Raymond Hettinger in :issue:`9694`.) |
| 913 |
|
| 914 |
array |
| 915 |
----- |
| 916 |
|
| 917 |
The :meth:`~array.array.index` method of :class:`array.array` now has |
| 918 |
optional *start* and *stop* parameters. |
| 919 |
(Contributed by Anders Lorentsen and Zackery Spytz in :issue:`31956`.) |
| 920 |
|
| 921 |
asynchat, asyncore, smtpd |
| 922 |
------------------------- |
| 923 |
These modules have been marked as deprecated in their module documentation |
| 924 |
since Python 3.6. An import-time :class:`DeprecationWarning` has now been |
| 925 |
added to all three of these modules. |
| 926 |
|
| 927 |
base64 |
| 928 |
------ |
| 929 |
|
| 930 |
Add :func:`base64.b32hexencode` and :func:`base64.b32hexdecode` to support the |
| 931 |
Base32 Encoding with Extended Hex Alphabet. |
| 932 |
|
| 933 |
bdb |
| 934 |
--- |
| 935 |
|
| 936 |
Add :meth:`!clearBreakpoints` to reset all set breakpoints. |
| 937 |
(Contributed by Irit Katriel in :issue:`24160`.) |
| 938 |
|
| 939 |
bisect |
| 940 |
------ |
| 941 |
|
| 942 |
Added the possibility of providing a *key* function to the APIs in the :mod:`bisect` |
| 943 |
module. (Contributed by Raymond Hettinger in :issue:`4356`.) |
| 944 |
|
| 945 |
codecs |
| 946 |
------ |
| 947 |
|
| 948 |
Add a :func:`codecs.unregister` function to unregister a codec search function. |
| 949 |
(Contributed by Hai Shi in :issue:`41842`.) |
| 950 |
|
| 951 |
collections.abc |
| 952 |
--------------- |
| 953 |
|
| 954 |
The ``__args__`` of the :ref:`parameterized generic <types-genericalias>` for |
| 955 |
:class:`collections.abc.Callable` are now consistent with :data:`typing.Callable`. |
| 956 |
:class:`collections.abc.Callable` generic now flattens type parameters, similar |
| 957 |
to what :data:`typing.Callable` currently does. This means that |
| 958 |
``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of |
| 959 |
``(int, str, str)``; previously this was ``([int, str], str)``. To allow this |
| 960 |
change, :class:`types.GenericAlias` can now be subclassed, and a subclass will |
| 961 |
be returned when subscripting the :class:`collections.abc.Callable` type. Note |
| 962 |
that a :exc:`TypeError` may be raised for invalid forms of parameterizing |
| 963 |
:class:`collections.abc.Callable` which may have passed silently in Python 3.9. |
| 964 |
(Contributed by Ken Jin in :issue:`42195`.) |
| 965 |
|
| 966 |
contextlib |
| 967 |
---------- |
| 968 |
|
| 969 |
Add a :func:`contextlib.aclosing` context manager to safely close async generators |
| 970 |
and objects representing asynchronously released resources. |
| 971 |
(Contributed by Joongi Kim and John Belmonte in :issue:`41229`.) |
| 972 |
|
| 973 |
Add asynchronous context manager support to :func:`contextlib.nullcontext`. |
| 974 |
(Contributed by Tom Gringauz in :issue:`41543`.) |
| 975 |
|
| 976 |
Add :class:`~contextlib.AsyncContextDecorator`, for supporting usage of async |
| 977 |
context managers as decorators. |
| 978 |
|
| 979 |
curses |
| 980 |
------ |
| 981 |
|
| 982 |
The extended color functions added in ncurses 6.1 will be used transparently |
| 983 |
by :func:`curses.color_content`, :func:`curses.init_color`, |
| 984 |
:func:`curses.init_pair`, and :func:`curses.pair_content`. A new function, |
| 985 |
:func:`curses.has_extended_color_support`, indicates whether extended color |
| 986 |
support is provided by the underlying ncurses library. |
| 987 |
(Contributed by Jeffrey Kintscher and Hans Petter Jansson in :issue:`36982`.) |
| 988 |
|
| 989 |
The ``BUTTON5_*`` constants are now exposed in the :mod:`curses` module if |
| 990 |
they are provided by the underlying curses library. |
| 991 |
(Contributed by Zackery Spytz in :issue:`39273`.) |
| 992 |
|
| 993 |
dataclasses |
| 994 |
----------- |
| 995 |
|
| 996 |
__slots__ |
| 997 |
~~~~~~~~~ |
| 998 |
|
| 999 |
Added ``slots`` parameter in :func:`dataclasses.dataclass` decorator. |
| 1000 |
(Contributed by Yurii Karabas in :issue:`42269`) |
| 1001 |
|
| 1002 |
Keyword-only fields |
| 1003 |
~~~~~~~~~~~~~~~~~~~ |
| 1004 |
|
| 1005 |
dataclasses now supports fields that are keyword-only in the |
| 1006 |
generated __init__ method. There are a number of ways of specifying |
| 1007 |
keyword-only fields. |
| 1008 |
|
| 1009 |
You can say that every field is keyword-only: |
| 1010 |
|
| 1011 |
.. code-block:: python |
| 1012 |
|
| 1013 |
from dataclasses import dataclass |
| 1014 |
|
| 1015 |
@dataclass(kw_only=True) |
| 1016 |
class Birthday: |
| 1017 |
name: str |
| 1018 |
birthday: datetime.date |
| 1019 |
|
| 1020 |
Both ``name`` and ``birthday`` are keyword-only parameters to the |
| 1021 |
generated __init__ method. |
| 1022 |
|
| 1023 |
You can specify keyword-only on a per-field basis: |
| 1024 |
|
| 1025 |
.. code-block:: python |
| 1026 |
|
| 1027 |
from dataclasses import dataclass, field |
| 1028 |
|
| 1029 |
@dataclass |
| 1030 |
class Birthday: |
| 1031 |
name: str |
| 1032 |
birthday: datetime.date = field(kw_only=True) |
| 1033 |
|
| 1034 |
Here only ``birthday`` is keyword-only. If you set ``kw_only`` on |
| 1035 |
individual fields, be aware that there are rules about re-ordering |
| 1036 |
fields due to keyword-only fields needing to follow non-keyword-only |
| 1037 |
fields. See the full dataclasses documentation for details. |
| 1038 |
|
| 1039 |
You can also specify that all fields following a KW_ONLY marker are |
| 1040 |
keyword-only. This will probably be the most common usage: |
| 1041 |
|
| 1042 |
.. code-block:: python |
| 1043 |
|
| 1044 |
from dataclasses import dataclass, KW_ONLY |
| 1045 |
|
| 1046 |
@dataclass |
| 1047 |
class Point: |
| 1048 |
x: float |
| 1049 |
y: float |
| 1050 |
_: KW_ONLY |
| 1051 |
z: float = 0.0 |
| 1052 |
t: float = 0.0 |
| 1053 |
|
| 1054 |
Here, ``z`` and ``t`` are keyword-only parameters, while ``x`` and |
| 1055 |
``y`` are not. |
| 1056 |
(Contributed by Eric V. Smith in :issue:`43532`.) |
| 1057 |
|
| 1058 |
.. _distutils-deprecated: |
| 1059 |
|
| 1060 |
distutils |
| 1061 |
--------- |
| 1062 |
|
| 1063 |
The entire ``distutils`` package is deprecated, to be removed in Python |
| 1064 |
3.12. Its functionality for specifying package builds has already been |
| 1065 |
completely replaced by third-party packages ``setuptools`` and |
| 1066 |
``packaging``, and most other commonly used APIs are available elsewhere |
| 1067 |
in the standard library (such as :mod:`platform`, :mod:`shutil`, |
| 1068 |
:mod:`subprocess` or :mod:`sysconfig`). There are no plans to migrate |
| 1069 |
any other functionality from ``distutils``, and applications that are |
| 1070 |
using other functions should plan to make private copies of the code. |
| 1071 |
Refer to :pep:`632` for discussion. |
| 1072 |
|
| 1073 |
The ``bdist_wininst`` command deprecated in Python 3.8 has been removed. |
| 1074 |
The ``bdist_wheel`` command is now recommended to distribute binary packages |
| 1075 |
on Windows. |
| 1076 |
(Contributed by Victor Stinner in :issue:`42802`.) |
| 1077 |
|
| 1078 |
doctest |
| 1079 |
------- |
| 1080 |
|
| 1081 |
When a module does not define ``__loader__``, fall back to ``__spec__.loader``. |
| 1082 |
(Contributed by Brett Cannon in :issue:`42133`.) |
| 1083 |
|
| 1084 |
encodings |
| 1085 |
--------- |
| 1086 |
|
| 1087 |
:func:`encodings.normalize_encoding` now ignores non-ASCII characters. |
| 1088 |
(Contributed by Hai Shi in :issue:`39337`.) |
| 1089 |
|
| 1090 |
enum |
| 1091 |
---- |
| 1092 |
|
| 1093 |
:class:`~enum.Enum` :func:`~object.__repr__` now returns ``enum_name.member_name`` and |
| 1094 |
:func:`~object.__str__` now returns ``member_name``. Stdlib enums available as |
| 1095 |
module constants have a :func:`repr` of ``module_name.member_name``. |
| 1096 |
(Contributed by Ethan Furman in :issue:`40066`.) |
| 1097 |
|
| 1098 |
Add :class:`enum.StrEnum` for enums where all members are strings. |
| 1099 |
(Contributed by Ethan Furman in :issue:`41816`.) |
| 1100 |
|
| 1101 |
fileinput |
| 1102 |
--------- |
| 1103 |
|
| 1104 |
Add *encoding* and *errors* parameters in :func:`fileinput.input` and |
| 1105 |
:class:`fileinput.FileInput`. |
| 1106 |
(Contributed by Inada Naoki in :issue:`43712`.) |
| 1107 |
|
| 1108 |
:func:`fileinput.hook_compressed` now returns :class:`~io.TextIOWrapper` object |
| 1109 |
when *mode* is "r" and file is compressed, like uncompressed files. |
| 1110 |
(Contributed by Inada Naoki in :issue:`5758`.) |
| 1111 |
|
| 1112 |
faulthandler |
| 1113 |
------------ |
| 1114 |
|
| 1115 |
The :mod:`faulthandler` module now detects if a fatal error occurs during a |
| 1116 |
garbage collector collection. |
| 1117 |
(Contributed by Victor Stinner in :issue:`44466`.) |
| 1118 |
|
| 1119 |
gc |
| 1120 |
-- |
| 1121 |
|
| 1122 |
Add audit hooks for :func:`gc.get_objects`, :func:`gc.get_referrers` and |
| 1123 |
:func:`gc.get_referents`. (Contributed by Pablo Galindo in :issue:`43439`.) |
| 1124 |
|
| 1125 |
glob |
| 1126 |
---- |
| 1127 |
|
| 1128 |
Add the *root_dir* and *dir_fd* parameters in :func:`~glob.glob` and |
| 1129 |
:func:`~glob.iglob` which allow to specify the root directory for searching. |
| 1130 |
(Contributed by Serhiy Storchaka in :issue:`38144`.) |
| 1131 |
|
| 1132 |
hashlib |
| 1133 |
------- |
| 1134 |
|
| 1135 |
The hashlib module requires OpenSSL 1.1.1 or newer. |
| 1136 |
(Contributed by Christian Heimes in :pep:`644` and :issue:`43669`.) |
| 1137 |
|
| 1138 |
The hashlib module has preliminary support for OpenSSL 3.0.0. |
| 1139 |
(Contributed by Christian Heimes in :issue:`38820` and other issues.) |
| 1140 |
|
| 1141 |
The pure-Python fallback of :func:`~hashlib.pbkdf2_hmac` is deprecated. In |
| 1142 |
the future PBKDF2-HMAC will only be available when Python has been built with |
| 1143 |
OpenSSL support. |
| 1144 |
(Contributed by Christian Heimes in :issue:`43880`.) |
| 1145 |
|
| 1146 |
hmac |
| 1147 |
---- |
| 1148 |
|
| 1149 |
The hmac module now uses OpenSSL's HMAC implementation internally. |
| 1150 |
(Contributed by Christian Heimes in :issue:`40645`.) |
| 1151 |
|
| 1152 |
IDLE and idlelib |
| 1153 |
---------------- |
| 1154 |
|
| 1155 |
Make IDLE invoke :func:`sys.excepthook` (when started without '-n'). |
| 1156 |
User hooks were previously ignored. (Contributed by Ken Hilton in |
| 1157 |
:issue:`43008`.) |
| 1158 |
|
| 1159 |
Rearrange the settings dialog. Split the General tab into Windows |
| 1160 |
and Shell/Ed tabs. Move help sources, which extend the Help menu, to the |
| 1161 |
Extensions tab. Make space for new options and shorten the dialog. The |
| 1162 |
latter makes the dialog better fit small screens. (Contributed by Terry Jan |
| 1163 |
Reedy in :issue:`40468`.) Move the indent space setting from the Font tab to |
| 1164 |
the new Windows tab. (Contributed by Mark Roseman and Terry Jan Reedy in |
| 1165 |
:issue:`33962`.) |
| 1166 |
|
| 1167 |
The changes above were backported to a 3.9 maintenance release. |
| 1168 |
|
| 1169 |
Add a Shell sidebar. Move the primary prompt ('>>>') to the sidebar. |
| 1170 |
Add secondary prompts ('...') to the sidebar. Left click and optional |
| 1171 |
drag selects one or more lines of text, as with the editor |
| 1172 |
line number sidebar. Right click after selecting text lines displays |
| 1173 |
a context menu with 'copy with prompts'. This zips together prompts |
| 1174 |
from the sidebar with lines from the selected text. This option also |
| 1175 |
appears on the context menu for the text. (Contributed by Tal Einat |
| 1176 |
in :issue:`37903`.) |
| 1177 |
|
| 1178 |
Use spaces instead of tabs to indent interactive code. This makes |
| 1179 |
interactive code entries 'look right'. Making this feasible was a |
| 1180 |
major motivation for adding the shell sidebar. (Contributed by |
| 1181 |
Terry Jan Reedy in :issue:`37892`.) |
| 1182 |
|
| 1183 |
Highlight the new :ref:`soft keywords <soft-keywords>` :keyword:`match`, |
| 1184 |
:keyword:`case <match>`, and :keyword:`_ <wildcard-patterns>` in |
| 1185 |
pattern-matching statements. However, this highlighting is not perfect |
| 1186 |
and will be incorrect in some rare cases, including some ``_``-s in |
| 1187 |
``case`` patterns. (Contributed by Tal Einat in :issue:`44010`.) |
| 1188 |
|
| 1189 |
New in 3.10 maintenance releases. |
| 1190 |
|
| 1191 |
Apply syntax highlighting to ``.pyi`` files. (Contributed by Alex |
| 1192 |
Waygood and Terry Jan Reedy in :issue:`45447`.) |
| 1193 |
|
| 1194 |
Include prompts when saving Shell with inputs and outputs. |
| 1195 |
(Contributed by Terry Jan Reedy in :gh:`95191`.) |
| 1196 |
|
| 1197 |
importlib.metadata |
| 1198 |
------------------ |
| 1199 |
|
| 1200 |
Feature parity with ``importlib_metadata`` 4.6 |
| 1201 |
(`history <https://importlib-metadata.readthedocs.io/en/latest/history.html>`_). |
| 1202 |
|
| 1203 |
:ref:`importlib.metadata entry points <entry-points>` |
| 1204 |
now provide a nicer experience |
| 1205 |
for selecting entry points by group and name through a new |
| 1206 |
:ref:`importlib.metadata.EntryPoints <entry-points>` class. See the Compatibility |
| 1207 |
Note in the docs for more info on the deprecation and usage. |
| 1208 |
|
| 1209 |
Added :ref:`importlib.metadata.packages_distributions() <package-distributions>` |
| 1210 |
for resolving top-level Python modules and packages to their |
| 1211 |
:ref:`importlib.metadata.Distribution <distributions>`. |
| 1212 |
|
| 1213 |
inspect |
| 1214 |
------- |
| 1215 |
|
| 1216 |
When a module does not define ``__loader__``, fall back to ``__spec__.loader``. |
| 1217 |
(Contributed by Brett Cannon in :issue:`42133`.) |
| 1218 |
|
| 1219 |
Add :func:`inspect.get_annotations`, which safely computes the annotations |
| 1220 |
defined on an object. It works around the quirks of accessing the annotations |
| 1221 |
on various types of objects, and makes very few assumptions about the object |
| 1222 |
it examines. :func:`inspect.get_annotations` can also correctly un-stringize |
| 1223 |
stringized annotations. :func:`inspect.get_annotations` is now considered |
| 1224 |
best practice for accessing the annotations dict defined on any Python object; |
| 1225 |
for more information on best practices for working with annotations, please see |
| 1226 |
:ref:`annotations-howto`. |
| 1227 |
Relatedly, :func:`inspect.signature`, |
| 1228 |
:func:`inspect.Signature.from_callable`, and :func:`!inspect.Signature.from_function` |
| 1229 |
now call :func:`inspect.get_annotations` to retrieve annotations. This means |
| 1230 |
:func:`inspect.signature` and :func:`inspect.Signature.from_callable` can |
| 1231 |
also now un-stringize stringized annotations. |
| 1232 |
(Contributed by Larry Hastings in :issue:`43817`.) |
| 1233 |
|
| 1234 |
itertools |
| 1235 |
--------- |
| 1236 |
|
| 1237 |
Add :func:`itertools.pairwise`. |
| 1238 |
(Contributed by Raymond Hettinger in :issue:`38200`.) |
| 1239 |
|
| 1240 |
linecache |
| 1241 |
--------- |
| 1242 |
|
| 1243 |
When a module does not define ``__loader__``, fall back to ``__spec__.loader``. |
| 1244 |
(Contributed by Brett Cannon in :issue:`42133`.) |
| 1245 |
|
| 1246 |
os |
| 1247 |
-- |
| 1248 |
|
| 1249 |
Add :func:`os.cpu_count` support for VxWorks RTOS. |
| 1250 |
(Contributed by Peixing Xin in :issue:`41440`.) |
| 1251 |
|
| 1252 |
Add a new function :func:`os.eventfd` and related helpers to wrap the |
| 1253 |
``eventfd2`` syscall on Linux. |
| 1254 |
(Contributed by Christian Heimes in :issue:`41001`.) |
| 1255 |
|
| 1256 |
Add :func:`os.splice` that allows to move data between two file |
| 1257 |
descriptors without copying between kernel address space and user |
| 1258 |
address space, where one of the file descriptors must refer to a |
| 1259 |
pipe. (Contributed by Pablo Galindo in :issue:`41625`.) |
| 1260 |
|
| 1261 |
Add :const:`~os.O_EVTONLY`, :const:`~os.O_FSYNC`, :const:`~os.O_SYMLINK` |
| 1262 |
and :const:`~os.O_NOFOLLOW_ANY` for macOS. |
| 1263 |
(Contributed by Donghee Na in :issue:`43106`.) |
| 1264 |
|
| 1265 |
os.path |
| 1266 |
------- |
| 1267 |
|
| 1268 |
:func:`os.path.realpath` now accepts a *strict* keyword-only argument. When set |
| 1269 |
to ``True``, :exc:`OSError` is raised if a path doesn't exist or a symlink loop |
| 1270 |
is encountered. |
| 1271 |
(Contributed by Barney Gale in :issue:`43757`.) |
| 1272 |
|
| 1273 |
pathlib |
| 1274 |
------- |
| 1275 |
|
| 1276 |
Add slice support to :attr:`PurePath.parents <pathlib.PurePath.parents>`. |
| 1277 |
(Contributed by Joshua Cannon in :issue:`35498`.) |
| 1278 |
|
| 1279 |
Add negative indexing support to :attr:`PurePath.parents |
| 1280 |
<pathlib.PurePath.parents>`. |
| 1281 |
(Contributed by Yaroslav Pankovych in :issue:`21041`.) |
| 1282 |
|
| 1283 |
Add :meth:`Path.hardlink_to <pathlib.Path.hardlink_to>` method that |
| 1284 |
supersedes :meth:`!link_to`. The new method has the same argument |
| 1285 |
order as :meth:`~pathlib.Path.symlink_to`. |
| 1286 |
(Contributed by Barney Gale in :issue:`39950`.) |
| 1287 |
|
| 1288 |
:meth:`pathlib.Path.stat` and :meth:`~pathlib.Path.chmod` now accept a |
| 1289 |
*follow_symlinks* keyword-only argument for consistency with corresponding |
| 1290 |
functions in the :mod:`os` module. |
| 1291 |
(Contributed by Barney Gale in :issue:`39906`.) |
| 1292 |
|
| 1293 |
platform |
| 1294 |
-------- |
| 1295 |
|
| 1296 |
Add :func:`platform.freedesktop_os_release` to retrieve operation system |
| 1297 |
identification from `freedesktop.org os-release |
| 1298 |
<https://www.freedesktop.org/software/systemd/man/os-release.html>`_ standard file. |
| 1299 |
(Contributed by Christian Heimes in :issue:`28468`.) |
| 1300 |
|
| 1301 |
pprint |
| 1302 |
------ |
| 1303 |
|
| 1304 |
:func:`pprint.pprint` now accepts a new ``underscore_numbers`` keyword argument. |
| 1305 |
(Contributed by sblondon in :issue:`42914`.) |
| 1306 |
|
| 1307 |
:mod:`pprint` can now pretty-print :class:`dataclasses.dataclass` instances. |
| 1308 |
(Contributed by Lewis Gaul in :issue:`43080`.) |
| 1309 |
|
| 1310 |
py_compile |
| 1311 |
---------- |
| 1312 |
|
| 1313 |
Add ``--quiet`` option to command-line interface of :mod:`py_compile`. |
| 1314 |
(Contributed by Gregory Schevchenko in :issue:`38731`.) |
| 1315 |
|
| 1316 |
pyclbr |
| 1317 |
------ |
| 1318 |
|
| 1319 |
Add an ``end_lineno`` attribute to the ``Function`` and ``Class`` |
| 1320 |
objects in the tree returned by :func:`pyclbr.readmodule` and |
| 1321 |
:func:`pyclbr.readmodule_ex`. It matches the existing (start) ``lineno``. |
| 1322 |
(Contributed by Aviral Srivastava in :issue:`38307`.) |
| 1323 |
|
| 1324 |
shelve |
| 1325 |
------ |
| 1326 |
|
| 1327 |
The :mod:`shelve` module now uses :const:`pickle.DEFAULT_PROTOCOL` by default |
| 1328 |
instead of :mod:`pickle` protocol ``3`` when creating shelves. |
| 1329 |
(Contributed by Zackery Spytz in :issue:`34204`.) |
| 1330 |
|
| 1331 |
statistics |
| 1332 |
---------- |
| 1333 |
|
| 1334 |
Add :func:`~statistics.covariance`, Pearson's |
| 1335 |
:func:`~statistics.correlation`, and simple |
| 1336 |
:func:`~statistics.linear_regression` functions. |
| 1337 |
(Contributed by Tymoteusz Wołodźko in :issue:`38490`.) |
| 1338 |
|
| 1339 |
site |
| 1340 |
---- |
| 1341 |
|
| 1342 |
When a module does not define ``__loader__``, fall back to ``__spec__.loader``. |
| 1343 |
(Contributed by Brett Cannon in :issue:`42133`.) |
| 1344 |
|
| 1345 |
socket |
| 1346 |
------ |
| 1347 |
|
| 1348 |
The exception :exc:`socket.timeout` is now an alias of :exc:`TimeoutError`. |
| 1349 |
(Contributed by Christian Heimes in :issue:`42413`.) |
| 1350 |
|
| 1351 |
Add option to create MPTCP sockets with ``IPPROTO_MPTCP`` |
| 1352 |
(Contributed by Rui Cunha in :issue:`43571`.) |
| 1353 |
|
| 1354 |
Add ``IP_RECVTOS`` option to receive the type of service (ToS) or DSCP/ECN fields |
| 1355 |
(Contributed by Georg Sauthoff in :issue:`44077`.) |
| 1356 |
|
| 1357 |
ssl |
| 1358 |
--- |
| 1359 |
|
| 1360 |
The ssl module requires OpenSSL 1.1.1 or newer. |
| 1361 |
(Contributed by Christian Heimes in :pep:`644` and :issue:`43669`.) |
| 1362 |
|
| 1363 |
The ssl module has preliminary support for OpenSSL 3.0.0 and new option |
| 1364 |
:const:`~ssl.OP_IGNORE_UNEXPECTED_EOF`. |
| 1365 |
(Contributed by Christian Heimes in :issue:`38820`, :issue:`43794`, |
| 1366 |
:issue:`43788`, :issue:`43791`, :issue:`43799`, :issue:`43920`, |
| 1367 |
:issue:`43789`, and :issue:`43811`.) |
| 1368 |
|
| 1369 |
Deprecated function and use of deprecated constants now result in |
| 1370 |
a :exc:`DeprecationWarning`. :attr:`ssl.SSLContext.options` has |
| 1371 |
:data:`~ssl.OP_NO_SSLv2` and :data:`~ssl.OP_NO_SSLv3` set by default and |
| 1372 |
therefore cannot warn about setting the flag again. The |
| 1373 |
:ref:`deprecation section <whatsnew310-deprecated>` has a list of deprecated |
| 1374 |
features. |
| 1375 |
(Contributed by Christian Heimes in :issue:`43880`.) |
| 1376 |
|
| 1377 |
The ssl module now has more secure default settings. Ciphers without forward |
| 1378 |
secrecy or SHA-1 MAC are disabled by default. Security level 2 prohibits |
| 1379 |
weak RSA, DH, and ECC keys with less than 112 bits of security. |
| 1380 |
:class:`~ssl.SSLContext` defaults to minimum protocol version TLS 1.2. |
| 1381 |
Settings are based on Hynek Schlawack's research. |
| 1382 |
(Contributed by Christian Heimes in :issue:`43998`.) |
| 1383 |
|
| 1384 |
The deprecated protocols SSL 3.0, TLS 1.0, and TLS 1.1 are no longer |
| 1385 |
officially supported. Python does not block them actively. However |
| 1386 |
OpenSSL build options, distro configurations, vendor patches, and cipher |
| 1387 |
suites may prevent a successful handshake. |
| 1388 |
|
| 1389 |
Add a *timeout* parameter to the :func:`ssl.get_server_certificate` function. |
| 1390 |
(Contributed by Zackery Spytz in :issue:`31870`.) |
| 1391 |
|
| 1392 |
The ssl module uses heap-types and multi-phase initialization. |
| 1393 |
(Contributed by Christian Heimes in :issue:`42333`.) |
| 1394 |
|
| 1395 |
A new verify flag :const:`~ssl.VERIFY_X509_PARTIAL_CHAIN` has been added. |
| 1396 |
(Contributed by l0x in :issue:`40849`.) |
| 1397 |
|
| 1398 |
sqlite3 |
| 1399 |
------- |
| 1400 |
|
| 1401 |
Add audit events for :func:`~sqlite3.connect`, |
| 1402 |
:meth:`~sqlite3.Connection.enable_load_extension`, and |
| 1403 |
:meth:`~sqlite3.Connection.load_extension`. |
| 1404 |
(Contributed by Erlend E. Aasland in :issue:`43762`.) |
| 1405 |
|
| 1406 |
sys |
| 1407 |
--- |
| 1408 |
|
| 1409 |
Add :data:`sys.orig_argv` attribute: the list of the original command line |
| 1410 |
arguments passed to the Python executable. |
| 1411 |
(Contributed by Victor Stinner in :issue:`23427`.) |
| 1412 |
|
| 1413 |
Add :data:`sys.stdlib_module_names`, containing the list of the standard library |
| 1414 |
module names. |
| 1415 |
(Contributed by Victor Stinner in :issue:`42955`.) |
| 1416 |
|
| 1417 |
_thread |
| 1418 |
------- |
| 1419 |
|
| 1420 |
:func:`_thread.interrupt_main` now takes an optional signal number to |
| 1421 |
simulate (the default is still :const:`signal.SIGINT`). |
| 1422 |
(Contributed by Antoine Pitrou in :issue:`43356`.) |
| 1423 |
|
| 1424 |
threading |
| 1425 |
--------- |
| 1426 |
|
| 1427 |
Add :func:`threading.gettrace` and :func:`threading.getprofile` to |
| 1428 |
retrieve the functions set by :func:`threading.settrace` and |
| 1429 |
:func:`threading.setprofile` respectively. |
| 1430 |
(Contributed by Mario Corchero in :issue:`42251`.) |
| 1431 |
|
| 1432 |
Add :data:`threading.__excepthook__` to allow retrieving the original value |
| 1433 |
of :func:`threading.excepthook` in case it is set to a broken or a different |
| 1434 |
value. |
| 1435 |
(Contributed by Mario Corchero in :issue:`42308`.) |
| 1436 |
|
| 1437 |
traceback |
| 1438 |
--------- |
| 1439 |
|
| 1440 |
The :func:`~traceback.format_exception`, |
| 1441 |
:func:`~traceback.format_exception_only`, and |
| 1442 |
:func:`~traceback.print_exception` functions can now take an exception object |
| 1443 |
as a positional-only argument. |
| 1444 |
(Contributed by Zackery Spytz and Matthias Bussonnier in :issue:`26389`.) |
| 1445 |
|
| 1446 |
types |
| 1447 |
----- |
| 1448 |
|
| 1449 |
Reintroduce the :class:`types.EllipsisType`, :class:`types.NoneType` |
| 1450 |
and :class:`types.NotImplementedType` classes, providing a new set |
| 1451 |
of types readily interpretable by type checkers. |
| 1452 |
(Contributed by Bas van Beek in :issue:`41810`.) |
| 1453 |
|
| 1454 |
typing |
| 1455 |
------ |
| 1456 |
|
| 1457 |
For major changes, see :ref:`new-feat-related-type-hints`. |
| 1458 |
|
| 1459 |
The behavior of :class:`typing.Literal` was changed to conform with :pep:`586` |
| 1460 |
and to match the behavior of static type checkers specified in the PEP. |
| 1461 |
|
| 1462 |
1. ``Literal`` now de-duplicates parameters. |
| 1463 |
2. Equality comparisons between ``Literal`` objects are now order independent. |
| 1464 |
3. ``Literal`` comparisons now respect types. For example, |
| 1465 |
``Literal[0] == Literal[False]`` previously evaluated to ``True``. It is |
| 1466 |
now ``False``. To support this change, the internally used type cache now |
| 1467 |
supports differentiating types. |
| 1468 |
4. ``Literal`` objects will now raise a :exc:`TypeError` exception during |
| 1469 |
equality comparisons if any of their parameters are not :term:`hashable`. |
| 1470 |
Note that declaring ``Literal`` with unhashable parameters will not throw |
| 1471 |
an error:: |
| 1472 |
|
| 1473 |
>>> from typing import Literal |
| 1474 |
>>> Literal[{0}] |
| 1475 |
>>> Literal[{0}] == Literal[{False}] |
| 1476 |
Traceback (most recent call last): |
| 1477 |
File "<stdin>", line 1, in <module> |
| 1478 |
TypeError: unhashable type: 'set' |
| 1479 |
|
| 1480 |
(Contributed by Yurii Karabas in :issue:`42345`.) |
| 1481 |
|
| 1482 |
Add new function :func:`typing.is_typeddict` to introspect if an annotation |
| 1483 |
is a :class:`typing.TypedDict`. |
| 1484 |
(Contributed by Patrick Reader in :issue:`41792`.) |
| 1485 |
|
| 1486 |
Subclasses of ``typing.Protocol`` which only have data variables declared |
| 1487 |
will now raise a ``TypeError`` when checked with ``isinstance`` unless they |
| 1488 |
are decorated with :func:`~typing.runtime_checkable`. Previously, these checks |
| 1489 |
passed silently. Users should decorate their |
| 1490 |
subclasses with the :func:`!runtime_checkable` decorator |
| 1491 |
if they want runtime protocols. |
| 1492 |
(Contributed by Yurii Karabas in :issue:`38908`.) |
| 1493 |
|
| 1494 |
Importing from the ``typing.io`` and ``typing.re`` submodules will now emit |
| 1495 |
:exc:`DeprecationWarning`. These submodules have been deprecated since |
| 1496 |
Python 3.8 and will be removed in a future version of Python. Anything |
| 1497 |
belonging to those submodules should be imported directly from |
| 1498 |
:mod:`typing` instead. |
| 1499 |
(Contributed by Sebastian Rittau in :issue:`38291`.) |
| 1500 |
|
| 1501 |
unittest |
| 1502 |
-------- |
| 1503 |
|
| 1504 |
Add new method :meth:`~unittest.TestCase.assertNoLogs` to complement the |
| 1505 |
existing :meth:`~unittest.TestCase.assertLogs`. (Contributed by Kit Yan Choi |
| 1506 |
in :issue:`39385`.) |
| 1507 |
|
| 1508 |
urllib.parse |
| 1509 |
------------ |
| 1510 |
|
| 1511 |
Python versions earlier than Python 3.10 allowed using both ``;`` and ``&`` as |
| 1512 |
query parameter separators in :func:`urllib.parse.parse_qs` and |
| 1513 |
:func:`urllib.parse.parse_qsl`. Due to security concerns, and to conform with |
| 1514 |
newer W3C recommendations, this has been changed to allow only a single |
| 1515 |
separator key, with ``&`` as the default. This change also affects |
| 1516 |
:func:`!cgi.parse` and :func:`!cgi.parse_multipart` as they use the affected |
| 1517 |
functions internally. For more details, please see their respective |
| 1518 |
documentation. |
| 1519 |
(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in :issue:`42967`.) |
| 1520 |
|
| 1521 |
The presence of newline or tab characters in parts of a URL allows for some |
| 1522 |
forms of attacks. Following the WHATWG specification that updates :rfc:`3986`, |
| 1523 |
ASCII newline ``\n``, ``\r`` and tab ``\t`` characters are stripped from the |
| 1524 |
URL by the parser in :mod:`urllib.parse` preventing such attacks. The removal |
| 1525 |
characters are controlled by a new module level variable |
| 1526 |
``urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE``. (See :gh:`88048`) |
| 1527 |
|
| 1528 |
xml |
| 1529 |
--- |
| 1530 |
|
| 1531 |
Add a :class:`~xml.sax.handler.LexicalHandler` class to the |
| 1532 |
:mod:`xml.sax.handler` module. |
| 1533 |
(Contributed by Jonathan Gossage and Zackery Spytz in :issue:`35018`.) |
| 1534 |
|
| 1535 |
zipimport |
| 1536 |
--------- |
| 1537 |
Add methods related to :pep:`451`: :meth:`~zipimport.zipimporter.find_spec`, |
| 1538 |
:meth:`zipimport.zipimporter.create_module`, and |
| 1539 |
:meth:`zipimport.zipimporter.exec_module`. |
| 1540 |
(Contributed by Brett Cannon in :issue:`42131`.) |
| 1541 |
|
| 1542 |
Add :meth:`~zipimport.zipimporter.invalidate_caches` method. |
| 1543 |
(Contributed by Desmond Cheong in :issue:`14678`.) |
| 1544 |
|
| 1545 |
|
| 1546 |
Optimizations |
| 1547 |
============= |
| 1548 |
|
| 1549 |
* Constructors :func:`str`, :func:`bytes` and :func:`bytearray` are now faster |
| 1550 |
(around 30--40% for small objects). |
| 1551 |
(Contributed by Serhiy Storchaka in :issue:`41334`.) |
| 1552 |
|
| 1553 |
* The :mod:`runpy` module now imports fewer modules. |
| 1554 |
The ``python3 -m module-name`` command startup time is 1.4x faster in |
| 1555 |
average. On Linux, ``python3 -I -m module-name`` imports 69 modules on Python |
| 1556 |
3.9, whereas it only imports 51 modules (-18) on Python 3.10. |
| 1557 |
(Contributed by Victor Stinner in :issue:`41006` and :issue:`41718`.) |
| 1558 |
|
| 1559 |
* The ``LOAD_ATTR`` instruction now uses new "per opcode cache" mechanism. It |
| 1560 |
is about 36% faster now for regular attributes and 44% faster for slots. |
| 1561 |
(Contributed by Pablo Galindo and Yury Selivanov in :issue:`42093` and Guido |
| 1562 |
van Rossum in :issue:`42927`, based on ideas implemented originally in PyPy |
| 1563 |
and MicroPython.) |
| 1564 |
|
| 1565 |
* When building Python with :option:`--enable-optimizations` now |
| 1566 |
``-fno-semantic-interposition`` is added to both the compile and link line. |
| 1567 |
This speeds builds of the Python interpreter created with :option:`--enable-shared` |
| 1568 |
with ``gcc`` by up to 30%. See `this article |
| 1569 |
<https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/>`_ |
| 1570 |
for more details. (Contributed by Victor Stinner and Pablo Galindo in |
| 1571 |
:issue:`38980`.) |
| 1572 |
|
| 1573 |
* Use a new output buffer management code for :mod:`bz2` / :mod:`lzma` / |
| 1574 |
:mod:`zlib` modules, and add ``.readall()`` function to |
| 1575 |
``_compression.DecompressReader`` class. bz2 decompression is now 1.09x ~ 1.17x |
| 1576 |
faster, lzma decompression 1.20x ~ 1.32x faster, ``GzipFile.read(-1)`` 1.11x |
| 1577 |
~ 1.18x faster. (Contributed by Ma Lin, reviewed by Gregory P. Smith, in :issue:`41486`) |
| 1578 |
|
| 1579 |
* When using stringized annotations, annotations dicts for functions are no longer |
| 1580 |
created when the function is created. Instead, they are stored as a tuple of |
| 1581 |
strings, and the function object lazily converts this into the annotations dict |
| 1582 |
on demand. This optimization cuts the CPU time needed to define an annotated |
| 1583 |
function by half. |
| 1584 |
(Contributed by Yurii Karabas and Inada Naoki in :issue:`42202`.) |
| 1585 |
|
| 1586 |
* Substring search functions such as ``str1 in str2`` and ``str2.find(str1)`` |
| 1587 |
now sometimes use Crochemore & Perrin's "Two-Way" string searching |
| 1588 |
algorithm to avoid quadratic behavior on long strings. (Contributed |
| 1589 |
by Dennis Sweeney in :issue:`41972`) |
| 1590 |
|
| 1591 |
* Add micro-optimizations to ``_PyType_Lookup()`` to improve type attribute cache lookup |
| 1592 |
performance in the common case of cache hits. This makes the interpreter 1.04 times faster |
| 1593 |
on average. (Contributed by Dino Viehland in :issue:`43452`.) |
| 1594 |
|
| 1595 |
* The following built-in functions now support the faster :pep:`590` vectorcall calling convention: |
| 1596 |
:func:`map`, :func:`filter`, :func:`reversed`, :func:`bool` and :func:`float`. |
| 1597 |
(Contributed by Donghee Na and Jeroen Demeyer in :issue:`43575`, :issue:`43287`, :issue:`41922`, :issue:`41873` and :issue:`41870`.) |
| 1598 |
|
| 1599 |
* :class:`~bz2.BZ2File` performance is improved by removing internal ``RLock``. |
| 1600 |
This makes :class:`!BZ2File` thread unsafe in the face of multiple simultaneous |
| 1601 |
readers or writers, just like its equivalent classes in :mod:`gzip` and |
| 1602 |
:mod:`lzma` have always been. (Contributed by Inada Naoki in :issue:`43785`.) |
| 1603 |
|
| 1604 |
.. _whatsnew310-deprecated: |
| 1605 |
|
| 1606 |
Deprecated |
| 1607 |
========== |
| 1608 |
|
| 1609 |
* Currently Python accepts numeric literals immediately followed by keywords, |
| 1610 |
for example ``0in x``, ``1or x``, ``0if 1else 2``. It allows confusing |
| 1611 |
and ambiguous expressions like ``[0x1for x in y]`` (which can be |
| 1612 |
interpreted as ``[0x1 for x in y]`` or ``[0x1f or x in y]``). Starting in |
| 1613 |
this release, a deprecation warning is raised if the numeric literal is |
| 1614 |
immediately followed by one of keywords :keyword:`and`, :keyword:`else`, |
| 1615 |
:keyword:`for`, :keyword:`if`, :keyword:`in`, :keyword:`is` and :keyword:`or`. |
| 1616 |
In future releases it will be changed to syntax warning, and finally to |
| 1617 |
syntax error. |
| 1618 |
(Contributed by Serhiy Storchaka in :issue:`43833`.) |
| 1619 |
|
| 1620 |
* Starting in this release, there will be a concerted effort to begin |
| 1621 |
cleaning up old import semantics that were kept for Python 2.7 |
| 1622 |
compatibility. Specifically, |
| 1623 |
:meth:`!find_loader`/:meth:`!find_module` |
| 1624 |
(superseded by :meth:`~importlib.abc.MetaPathFinder.find_spec`), |
| 1625 |
:meth:`~importlib.abc.Loader.load_module` |
| 1626 |
(superseded by :meth:`~importlib.abc.Loader.exec_module`), |
| 1627 |
:meth:`!module_repr` (which the import system |
| 1628 |
takes care of for you), the ``__package__`` attribute |
| 1629 |
(superseded by ``__spec__.parent``), the ``__loader__`` attribute |
| 1630 |
(superseded by ``__spec__.loader``), and the ``__cached__`` attribute |
| 1631 |
(superseded by ``__spec__.cached``) will slowly be removed (as well |
| 1632 |
as other classes and methods in :mod:`importlib`). |
| 1633 |
:exc:`ImportWarning` and/or :exc:`DeprecationWarning` will be raised |
| 1634 |
as appropriate to help identify code which needs updating during |
| 1635 |
this transition. |
| 1636 |
|
| 1637 |
* The entire ``distutils`` namespace is deprecated, to be removed in |
| 1638 |
Python 3.12. Refer to the :ref:`module changes <distutils-deprecated>` |
| 1639 |
section for more information. |
| 1640 |
|
| 1641 |
* Non-integer arguments to :func:`random.randrange` are deprecated. |
| 1642 |
The :exc:`ValueError` is deprecated in favor of a :exc:`TypeError`. |
| 1643 |
(Contributed by Serhiy Storchaka and Raymond Hettinger in :issue:`37319`.) |
| 1644 |
|
| 1645 |
* The various ``load_module()`` methods of :mod:`importlib` have been |
| 1646 |
documented as deprecated since Python 3.6, but will now also trigger |
| 1647 |
a :exc:`DeprecationWarning`. Use |
| 1648 |
:meth:`~importlib.abc.Loader.exec_module` instead. |
| 1649 |
(Contributed by Brett Cannon in :issue:`26131`.) |
| 1650 |
|
| 1651 |
* :meth:`!zimport.zipimporter.load_module` has been deprecated in |
| 1652 |
preference for :meth:`~zipimport.zipimporter.exec_module`. |
| 1653 |
(Contributed by Brett Cannon in :issue:`26131`.) |
| 1654 |
|
| 1655 |
* The use of :meth:`~importlib.abc.Loader.load_module` by the import |
| 1656 |
system now triggers an :exc:`ImportWarning` as |
| 1657 |
:meth:`~importlib.abc.Loader.exec_module` is preferred. |
| 1658 |
(Contributed by Brett Cannon in :issue:`26131`.) |
| 1659 |
|
| 1660 |
* The use of :meth:`!importlib.abc.MetaPathFinder.find_module` and |
| 1661 |
:meth:`!importlib.abc.PathEntryFinder.find_module` by the import system now |
| 1662 |
trigger an :exc:`ImportWarning` as |
| 1663 |
:meth:`importlib.abc.MetaPathFinder.find_spec` and |
| 1664 |
:meth:`importlib.abc.PathEntryFinder.find_spec` |
| 1665 |
are preferred, respectively. You can use |
| 1666 |
:func:`importlib.util.spec_from_loader` to help in porting. |
| 1667 |
(Contributed by Brett Cannon in :issue:`42134`.) |
| 1668 |
|
| 1669 |
* The use of :meth:`!importlib.abc.PathEntryFinder.find_loader` by the import |
| 1670 |
system now triggers an :exc:`ImportWarning` as |
| 1671 |
:meth:`importlib.abc.PathEntryFinder.find_spec` is preferred. You can use |
| 1672 |
:func:`importlib.util.spec_from_loader` to help in porting. |
| 1673 |
(Contributed by Brett Cannon in :issue:`43672`.) |
| 1674 |
|
| 1675 |
* The various implementations of |
| 1676 |
:meth:`!importlib.abc.MetaPathFinder.find_module` ( |
| 1677 |
:meth:`!importlib.machinery.BuiltinImporter.find_module`, |
| 1678 |
:meth:`!importlib.machinery.FrozenImporter.find_module`, |
| 1679 |
:meth:`!importlib.machinery.WindowsRegistryFinder.find_module`, |
| 1680 |
:meth:`!importlib.machinery.PathFinder.find_module`, |
| 1681 |
:meth:`!importlib.abc.MetaPathFinder.find_module` ), |
| 1682 |
:meth:`!importlib.abc.PathEntryFinder.find_module` ( |
| 1683 |
:meth:`!importlib.machinery.FileFinder.find_module` ), and |
| 1684 |
:meth:`!importlib.abc.PathEntryFinder.find_loader` ( |
| 1685 |
:meth:`!importlib.machinery.FileFinder.find_loader` ) |
| 1686 |
now raise :exc:`DeprecationWarning` and are slated for removal in |
| 1687 |
Python 3.12 (previously they were documented as deprecated in Python 3.4). |
| 1688 |
(Contributed by Brett Cannon in :issue:`42135`.) |
| 1689 |
|
| 1690 |
* :class:`!importlib.abc.Finder` is deprecated (including its sole method, |
| 1691 |
:meth:`!find_module`). Both |
| 1692 |
:class:`importlib.abc.MetaPathFinder` and :class:`importlib.abc.PathEntryFinder` |
| 1693 |
no longer inherit from the class. Users should inherit from one of these two |
| 1694 |
classes as appropriate instead. |
| 1695 |
(Contributed by Brett Cannon in :issue:`42135`.) |
| 1696 |
|
| 1697 |
* The deprecations of :mod:`!imp`, :func:`!importlib.find_loader`, |
| 1698 |
:func:`!importlib.util.set_package_wrapper`, |
| 1699 |
:func:`!importlib.util.set_loader_wrapper`, |
| 1700 |
:func:`!importlib.util.module_for_loader`, |
| 1701 |
:class:`!pkgutil.ImpImporter`, and |
| 1702 |
:class:`!pkgutil.ImpLoader` have all been updated to list Python 3.12 as the |
| 1703 |
slated version of removal (they began raising :exc:`DeprecationWarning` in |
| 1704 |
previous versions of Python). |
| 1705 |
(Contributed by Brett Cannon in :issue:`43720`.) |
| 1706 |
|
| 1707 |
* The import system now uses the ``__spec__`` attribute on modules before |
| 1708 |
falling back on :meth:`!module_repr` for a module's |
| 1709 |
``__repr__()`` method. Removal of the use of ``module_repr()`` is scheduled |
| 1710 |
for Python 3.12. |
| 1711 |
(Contributed by Brett Cannon in :issue:`42137`.) |
| 1712 |
|
| 1713 |
* :meth:`!importlib.abc.Loader.module_repr`, |
| 1714 |
:meth:`!importlib.machinery.FrozenLoader.module_repr`, and |
| 1715 |
:meth:`!importlib.machinery.BuiltinLoader.module_repr` are deprecated and |
| 1716 |
slated for removal in Python 3.12. |
| 1717 |
(Contributed by Brett Cannon in :issue:`42136`.) |
| 1718 |
|
| 1719 |
* ``sqlite3.OptimizedUnicode`` has been undocumented and obsolete since Python |
| 1720 |
3.3, when it was made an alias to :class:`str`. It is now deprecated, |
| 1721 |
scheduled for removal in Python 3.12. |
| 1722 |
(Contributed by Erlend E. Aasland in :issue:`42264`.) |
| 1723 |
|
| 1724 |
* The undocumented built-in function ``sqlite3.enable_shared_cache`` is now |
| 1725 |
deprecated, scheduled for removal in Python 3.12. Its use is strongly |
| 1726 |
discouraged by the SQLite3 documentation. See `the SQLite3 docs |
| 1727 |
<https://sqlite.org/c3ref/enable_shared_cache.html>`_ for more details. |
| 1728 |
If a shared cache must be used, open the database in URI mode using the |
| 1729 |
``cache=shared`` query parameter. |
| 1730 |
(Contributed by Erlend E. Aasland in :issue:`24464`.) |
| 1731 |
|
| 1732 |
* The following ``threading`` methods are now deprecated: |
| 1733 |
|
| 1734 |
* ``threading.currentThread`` => :func:`threading.current_thread` |
| 1735 |
|
| 1736 |
* ``threading.activeCount`` => :func:`threading.active_count` |
| 1737 |
|
| 1738 |
* ``threading.Condition.notifyAll`` => |
| 1739 |
:meth:`threading.Condition.notify_all` |
| 1740 |
|
| 1741 |
* ``threading.Event.isSet`` => :meth:`threading.Event.is_set` |
| 1742 |
|
| 1743 |
* ``threading.Thread.setName`` => :attr:`threading.Thread.name` |
| 1744 |
|
| 1745 |
* ``threading.thread.getName`` => :attr:`threading.Thread.name` |
| 1746 |
|
| 1747 |
* ``threading.Thread.isDaemon`` => :attr:`threading.Thread.daemon` |
| 1748 |
|
| 1749 |
* ``threading.Thread.setDaemon`` => :attr:`threading.Thread.daemon` |
| 1750 |
|
| 1751 |
(Contributed by Jelle Zijlstra in :gh:`87889`.) |
| 1752 |
|
| 1753 |
* :meth:`!pathlib.Path.link_to` is deprecated and slated for removal in |
| 1754 |
Python 3.12. Use :meth:`pathlib.Path.hardlink_to` instead. |
| 1755 |
(Contributed by Barney Gale in :issue:`39950`.) |
| 1756 |
|
| 1757 |
* ``cgi.log()`` is deprecated and slated for removal in Python 3.12. |
| 1758 |
(Contributed by Inada Naoki in :issue:`41139`.) |
| 1759 |
|
| 1760 |
* The following :mod:`ssl` features have been deprecated since Python 3.6, |
| 1761 |
Python 3.7, or OpenSSL 1.1.0 and will be removed in 3.11: |
| 1762 |
|
| 1763 |
* :data:`!OP_NO_SSLv2`, :data:`!OP_NO_SSLv3`, :data:`!OP_NO_TLSv1`, |
| 1764 |
:data:`!OP_NO_TLSv1_1`, :data:`!OP_NO_TLSv1_2`, and |
| 1765 |
:data:`!OP_NO_TLSv1_3` are replaced by |
| 1766 |
:attr:`~ssl.SSLContext.minimum_version` and |
| 1767 |
:attr:`~ssl.SSLContext.maximum_version`. |
| 1768 |
|
| 1769 |
* :data:`!PROTOCOL_SSLv2`, :data:`!PROTOCOL_SSLv3`, |
| 1770 |
:data:`!PROTOCOL_SSLv23`, :data:`!PROTOCOL_TLSv1`, |
| 1771 |
:data:`!PROTOCOL_TLSv1_1`, :data:`!PROTOCOL_TLSv1_2`, and |
| 1772 |
:const:`!PROTOCOL_TLS` are deprecated in favor of |
| 1773 |
:const:`~ssl.PROTOCOL_TLS_CLIENT` and :const:`~ssl.PROTOCOL_TLS_SERVER` |
| 1774 |
|
| 1775 |
* :func:`!wrap_socket` is replaced by :meth:`ssl.SSLContext.wrap_socket` |
| 1776 |
|
| 1777 |
* :func:`!match_hostname` |
| 1778 |
|
| 1779 |
* :func:`!RAND_pseudo_bytes`, :func:`!RAND_egd` |
| 1780 |
|
| 1781 |
* NPN features like :meth:`ssl.SSLSocket.selected_npn_protocol` and |
| 1782 |
:meth:`ssl.SSLContext.set_npn_protocols` are replaced by ALPN. |
| 1783 |
|
| 1784 |
* The threading debug (:envvar:`!PYTHONTHREADDEBUG` environment variable) is |
| 1785 |
deprecated in Python 3.10 and will be removed in Python 3.12. This feature |
| 1786 |
requires a :ref:`debug build of Python <debug-build>`. |
| 1787 |
(Contributed by Victor Stinner in :issue:`44584`.) |
| 1788 |
|
| 1789 |
* Importing from the ``typing.io`` and ``typing.re`` submodules will now emit |
| 1790 |
:exc:`DeprecationWarning`. These submodules will be removed in a future version |
| 1791 |
of Python. Anything belonging to these submodules should be imported directly |
| 1792 |
from :mod:`typing` instead. |
| 1793 |
(Contributed by Sebastian Rittau in :issue:`38291`.) |
| 1794 |
|
| 1795 |
.. _whatsnew310-removed: |
| 1796 |
|
| 1797 |
Removed |
| 1798 |
======= |
| 1799 |
|
| 1800 |
* Removed special methods ``__int__``, ``__float__``, ``__floordiv__``, |
| 1801 |
``__mod__``, ``__divmod__``, ``__rfloordiv__``, ``__rmod__`` and |
| 1802 |
``__rdivmod__`` of the :class:`complex` class. They always raised |
| 1803 |
a :exc:`TypeError`. |
| 1804 |
(Contributed by Serhiy Storchaka in :issue:`41974`.) |
| 1805 |
|
| 1806 |
* The ``ParserBase.error()`` method from the private and undocumented ``_markupbase`` |
| 1807 |
module has been removed. :class:`html.parser.HTMLParser` is the only subclass of |
| 1808 |
``ParserBase`` and its ``error()`` implementation was already removed in |
| 1809 |
Python 3.5. |
| 1810 |
(Contributed by Berker Peksag in :issue:`31844`.) |
| 1811 |
|
| 1812 |
* Removed the ``unicodedata.ucnhash_CAPI`` attribute which was an internal |
| 1813 |
PyCapsule object. The related private ``_PyUnicode_Name_CAPI`` structure was |
| 1814 |
moved to the internal C API. |
| 1815 |
(Contributed by Victor Stinner in :issue:`42157`.) |
| 1816 |
|
| 1817 |
* Removed the ``parser`` module, which was deprecated in 3.9 due to the |
| 1818 |
switch to the new PEG parser, as well as all the C source and header files |
| 1819 |
that were only being used by the old parser, including ``node.h``, ``parser.h``, |
| 1820 |
``graminit.h`` and ``grammar.h``. |
| 1821 |
|
| 1822 |
* Removed the Public C API functions ``PyParser_SimpleParseStringFlags``, |
| 1823 |
``PyParser_SimpleParseStringFlagsFilename``, |
| 1824 |
``PyParser_SimpleParseFileFlags`` and ``PyNode_Compile`` |
| 1825 |
that were deprecated in 3.9 due to the switch to the new PEG parser. |
| 1826 |
|
| 1827 |
* Removed the ``formatter`` module, which was deprecated in Python 3.4. |
| 1828 |
It is somewhat obsolete, little used, and not tested. It was originally |
| 1829 |
scheduled to be removed in Python 3.6, but such removals were delayed until |
| 1830 |
after Python 2.7 EOL. Existing users should copy whatever classes they use |
| 1831 |
into their code. |
| 1832 |
(Contributed by Donghee Na and Terry J. Reedy in :issue:`42299`.) |
| 1833 |
|
| 1834 |
* Removed the :c:func:`!PyModule_GetWarningsModule` function that was useless |
| 1835 |
now due to the :mod:`!_warnings` module was converted to a builtin module in 2.6. |
| 1836 |
(Contributed by Hai Shi in :issue:`42599`.) |
| 1837 |
|
| 1838 |
* Remove deprecated aliases to :ref:`collections-abstract-base-classes` from |
| 1839 |
the :mod:`collections` module. |
| 1840 |
(Contributed by Victor Stinner in :issue:`37324`.) |
| 1841 |
|
| 1842 |
* The ``loop`` parameter has been removed from most of :mod:`asyncio`\ 's |
| 1843 |
:doc:`high-level API <../library/asyncio-api-index>` following deprecation |
| 1844 |
in Python 3.8. The motivation behind this change is multifold: |
| 1845 |
|
| 1846 |
1. This simplifies the high-level API. |
| 1847 |
2. The functions in the high-level API have been implicitly getting the |
| 1848 |
current thread's running event loop since Python 3.7. There isn't a need to |
| 1849 |
pass the event loop to the API in most normal use cases. |
| 1850 |
3. Event loop passing is error-prone especially when dealing with loops |
| 1851 |
running in different threads. |
| 1852 |
|
| 1853 |
Note that the low-level API will still accept ``loop``. |
| 1854 |
See :ref:`changes-python-api` for examples of how to replace existing code. |
| 1855 |
|
| 1856 |
(Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley |
| 1857 |
in :issue:`42392`.) |
| 1858 |
|
| 1859 |
|
| 1860 |
Porting to Python 3.10 |
| 1861 |
====================== |
| 1862 |
|
| 1863 |
This section lists previously described changes and other bugfixes |
| 1864 |
that may require changes to your code. |
| 1865 |
|
| 1866 |
|
| 1867 |
Changes in the Python syntax |
| 1868 |
---------------------------- |
| 1869 |
|
| 1870 |
* Deprecation warning is now emitted when compiling previously valid syntax |
| 1871 |
if the numeric literal is immediately followed by a keyword (like in ``0in x``). |
| 1872 |
In future releases it will be changed to syntax warning, and finally to a |
| 1873 |
syntax error. To get rid of the warning and make the code compatible with |
| 1874 |
future releases just add a space between the numeric literal and the |
| 1875 |
following keyword. |
| 1876 |
(Contributed by Serhiy Storchaka in :issue:`43833`.) |
| 1877 |
|
| 1878 |
.. _changes-python-api: |
| 1879 |
|
| 1880 |
Changes in the Python API |
| 1881 |
------------------------- |
| 1882 |
|
| 1883 |
* The *etype* parameters of the :func:`~traceback.format_exception`, |
| 1884 |
:func:`~traceback.format_exception_only`, and |
| 1885 |
:func:`~traceback.print_exception` functions in the :mod:`traceback` module |
| 1886 |
have been renamed to *exc*. |
| 1887 |
(Contributed by Zackery Spytz and Matthias Bussonnier in :issue:`26389`.) |
| 1888 |
|
| 1889 |
* :mod:`atexit`: At Python exit, if a callback registered with |
| 1890 |
:func:`atexit.register` fails, its exception is now logged. Previously, only |
| 1891 |
some exceptions were logged, and the last exception was always silently |
| 1892 |
ignored. |
| 1893 |
(Contributed by Victor Stinner in :issue:`42639`.) |
| 1894 |
|
| 1895 |
* :class:`collections.abc.Callable` generic now flattens type parameters, similar |
| 1896 |
to what :data:`typing.Callable` currently does. This means that |
| 1897 |
``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of |
| 1898 |
``(int, str, str)``; previously this was ``([int, str], str)``. Code which |
| 1899 |
accesses the arguments via :func:`typing.get_args` or ``__args__`` need to account |
| 1900 |
for this change. Furthermore, :exc:`TypeError` may be raised for invalid forms |
| 1901 |
of parameterizing :class:`collections.abc.Callable` which may have passed |
| 1902 |
silently in Python 3.9. |
| 1903 |
(Contributed by Ken Jin in :issue:`42195`.) |
| 1904 |
|
| 1905 |
* :meth:`socket.htons` and :meth:`socket.ntohs` now raise :exc:`OverflowError` |
| 1906 |
instead of :exc:`DeprecationWarning` if the given parameter will not fit in |
| 1907 |
a 16-bit unsigned integer. |
| 1908 |
(Contributed by Erlend E. Aasland in :issue:`42393`.) |
| 1909 |
|
| 1910 |
* The ``loop`` parameter has been removed from most of :mod:`asyncio`\ 's |
| 1911 |
:doc:`high-level API <../library/asyncio-api-index>` following deprecation |
| 1912 |
in Python 3.8. |
| 1913 |
|
| 1914 |
A coroutine that currently looks like this:: |
| 1915 |
|
| 1916 |
async def foo(loop): |
| 1917 |
await asyncio.sleep(1, loop=loop) |
| 1918 |
|
| 1919 |
Should be replaced with this:: |
| 1920 |
|
| 1921 |
async def foo(): |
| 1922 |
await asyncio.sleep(1) |
| 1923 |
|
| 1924 |
If ``foo()`` was specifically designed *not* to run in the current thread's |
| 1925 |
running event loop (e.g. running in another thread's event loop), consider |
| 1926 |
using :func:`asyncio.run_coroutine_threadsafe` instead. |
| 1927 |
|
| 1928 |
(Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley |
| 1929 |
in :issue:`42392`.) |
| 1930 |
|
| 1931 |
* The :data:`types.FunctionType` constructor now inherits the current builtins |
| 1932 |
if the *globals* dictionary has no ``"__builtins__"`` key, rather than using |
| 1933 |
``{"None": None}`` as builtins: same behavior as :func:`eval` and |
| 1934 |
:func:`exec` functions. Defining a function with ``def function(...): ...`` |
| 1935 |
in Python is not affected, globals cannot be overridden with this syntax: it |
| 1936 |
also inherits the current builtins. |
| 1937 |
(Contributed by Victor Stinner in :issue:`42990`.) |
| 1938 |
|
| 1939 |
Changes in the C API |
| 1940 |
-------------------- |
| 1941 |
|
| 1942 |
* The C API functions ``PyParser_SimpleParseStringFlags``, |
| 1943 |
``PyParser_SimpleParseStringFlagsFilename``, |
| 1944 |
``PyParser_SimpleParseFileFlags``, ``PyNode_Compile`` and the type |
| 1945 |
used by these functions, ``struct _node``, were removed due to the switch |
| 1946 |
to the new PEG parser. |
| 1947 |
|
| 1948 |
Source should be now be compiled directly to a code object using, for |
| 1949 |
example, :c:func:`Py_CompileString`. The resulting code object can then be |
| 1950 |
evaluated using, for example, :c:func:`PyEval_EvalCode`. |
| 1951 |
|
| 1952 |
Specifically: |
| 1953 |
|
| 1954 |
* A call to ``PyParser_SimpleParseStringFlags`` followed by |
| 1955 |
``PyNode_Compile`` can be replaced by calling :c:func:`Py_CompileString`. |
| 1956 |
|
| 1957 |
* There is no direct replacement for ``PyParser_SimpleParseFileFlags``. |
| 1958 |
To compile code from a ``FILE *`` argument, you will need to read |
| 1959 |
the file in C and pass the resulting buffer to :c:func:`Py_CompileString`. |
| 1960 |
|
| 1961 |
* To compile a file given a ``char *`` filename, explicitly open the file, read |
| 1962 |
it and compile the result. One way to do this is using the :py:mod:`io` |
| 1963 |
module with :c:func:`PyImport_ImportModule`, :c:func:`PyObject_CallMethod`, |
| 1964 |
:c:func:`PyBytes_AsString` and :c:func:`Py_CompileString`, |
| 1965 |
as sketched below. (Declarations and error handling are omitted.) :: |
| 1966 |
|
| 1967 |
io_module = Import_ImportModule("io"); |
| 1968 |
fileobject = PyObject_CallMethod(io_module, "open", "ss", filename, "rb"); |
| 1969 |
source_bytes_object = PyObject_CallMethod(fileobject, "read", ""); |
| 1970 |
result = PyObject_CallMethod(fileobject, "close", ""); |
| 1971 |
source_buf = PyBytes_AsString(source_bytes_object); |
| 1972 |
code = Py_CompileString(source_buf, filename, Py_file_input); |
| 1973 |
|
| 1974 |
* For ``FrameObject`` objects, the :attr:`~frame.f_lasti` member now represents a wordcode |
| 1975 |
offset instead of a simple offset into the bytecode string. This means that this |
| 1976 |
number needs to be multiplied by 2 to be used with APIs that expect a byte offset |
| 1977 |
instead (like :c:func:`PyCode_Addr2Line` for example). Notice as well that the |
| 1978 |
:attr:`!f_lasti` member of ``FrameObject`` objects is not considered stable: please |
| 1979 |
use :c:func:`PyFrame_GetLineNumber` instead. |
| 1980 |
|
| 1981 |
CPython bytecode changes |
| 1982 |
======================== |
| 1983 |
|
| 1984 |
* The ``MAKE_FUNCTION`` instruction now accepts either a dict or a tuple of |
| 1985 |
strings as the function's annotations. |
| 1986 |
(Contributed by Yurii Karabas and Inada Naoki in :issue:`42202`.) |
| 1987 |
|
| 1988 |
Build Changes |
| 1989 |
============= |
| 1990 |
|
| 1991 |
* :pep:`644`: Python now requires OpenSSL 1.1.1 or newer. OpenSSL 1.0.2 is no |
| 1992 |
longer supported. |
| 1993 |
(Contributed by Christian Heimes in :issue:`43669`.) |
| 1994 |
|
| 1995 |
* The C99 functions :c:func:`snprintf` and :c:func:`vsnprintf` are now required |
| 1996 |
to build Python. |
| 1997 |
(Contributed by Victor Stinner in :issue:`36020`.) |
| 1998 |
|
| 1999 |
* :mod:`sqlite3` requires SQLite 3.7.15 or higher. (Contributed by Sergey Fedoseev |
| 2000 |
and Erlend E. Aasland in :issue:`40744` and :issue:`40810`.) |
| 2001 |
|
| 2002 |
* The :mod:`atexit` module must now always be built as a built-in module. |
| 2003 |
(Contributed by Victor Stinner in :issue:`42639`.) |
| 2004 |
|
| 2005 |
* Add :option:`--disable-test-modules` option to the ``configure`` script: |
| 2006 |
don't build nor install test modules. |
| 2007 |
(Contributed by Xavier de Gaye, Thomas Petazzoni and Peixing Xin in :issue:`27640`.) |
| 2008 |
|
| 2009 |
* Add :option:`--with-wheel-pkg-dir=PATH option <--with-wheel-pkg-dir>` |
| 2010 |
to the ``./configure`` script. If |
| 2011 |
specified, the :mod:`ensurepip` module looks for ``setuptools`` and ``pip`` |
| 2012 |
wheel packages in this directory: if both are present, these wheel packages |
| 2013 |
are used instead of ensurepip bundled wheel packages. |
| 2014 |
|
| 2015 |
Some Linux distribution packaging policies recommend against bundling |
| 2016 |
dependencies. For example, Fedora installs wheel packages in the |
| 2017 |
``/usr/share/python-wheels/`` directory and don't install the |
| 2018 |
``ensurepip._bundled`` package. |
| 2019 |
|
| 2020 |
(Contributed by Victor Stinner in :issue:`42856`.) |
| 2021 |
|
| 2022 |
* Add a new :option:`configure --without-static-libpython option |
| 2023 |
<--without-static-libpython>` to not build the ``libpythonMAJOR.MINOR.a`` |
| 2024 |
static library and not install the ``python.o`` object file. |
| 2025 |
|
| 2026 |
(Contributed by Victor Stinner in :issue:`43103`.) |
| 2027 |
|
| 2028 |
* The ``configure`` script now uses the ``pkg-config`` utility, if available, |
| 2029 |
to detect the location of Tcl/Tk headers and libraries. As before, those |
| 2030 |
locations can be explicitly specified with the ``--with-tcltk-includes`` |
| 2031 |
and ``--with-tcltk-libs`` configuration options. |
| 2032 |
(Contributed by Manolis Stamatogiannakis in :issue:`42603`.) |
| 2033 |
|
| 2034 |
* Add :option:`--with-openssl-rpath` option to ``configure`` script. The option |
| 2035 |
simplifies building Python with a custom OpenSSL installation, e.g. |
| 2036 |
``./configure --with-openssl=/path/to/openssl --with-openssl-rpath=auto``. |
| 2037 |
(Contributed by Christian Heimes in :issue:`43466`.) |
| 2038 |
|
| 2039 |
|
| 2040 |
C API Changes |
| 2041 |
============= |
| 2042 |
|
| 2043 |
PEP 652: Maintaining the Stable ABI |
| 2044 |
----------------------------------- |
| 2045 |
|
| 2046 |
The Stable ABI (Application Binary Interface) for extension modules or |
| 2047 |
embedding Python is now explicitly defined. |
| 2048 |
:ref:`stable` describes C API and ABI stability guarantees along with best |
| 2049 |
practices for using the Stable ABI. |
| 2050 |
|
| 2051 |
(Contributed by Petr Viktorin in :pep:`652` and :issue:`43795`.) |
| 2052 |
|
| 2053 |
New Features |
| 2054 |
------------ |
| 2055 |
|
| 2056 |
* The result of :c:func:`PyNumber_Index` now always has exact type :class:`int`. |
| 2057 |
Previously, the result could have been an instance of a subclass of ``int``. |
| 2058 |
(Contributed by Serhiy Storchaka in :issue:`40792`.) |
| 2059 |
|
| 2060 |
* Add a new :c:member:`~PyConfig.orig_argv` member to the :c:type:`PyConfig` |
| 2061 |
structure: the list of the original command line arguments passed to the |
| 2062 |
Python executable. |
| 2063 |
(Contributed by Victor Stinner in :issue:`23427`.) |
| 2064 |
|
| 2065 |
* The :c:func:`PyDateTime_DATE_GET_TZINFO` and |
| 2066 |
:c:func:`PyDateTime_TIME_GET_TZINFO` macros have been added for accessing |
| 2067 |
the ``tzinfo`` attributes of :class:`datetime.datetime` and |
| 2068 |
:class:`datetime.time` objects. |
| 2069 |
(Contributed by Zackery Spytz in :issue:`30155`.) |
| 2070 |
|
| 2071 |
* Add a :c:func:`PyCodec_Unregister` function to unregister a codec |
| 2072 |
search function. |
| 2073 |
(Contributed by Hai Shi in :issue:`41842`.) |
| 2074 |
|
| 2075 |
* The :c:func:`PyIter_Send` function was added to allow |
| 2076 |
sending value into iterator without raising ``StopIteration`` exception. |
| 2077 |
(Contributed by Vladimir Matveev in :issue:`41756`.) |
| 2078 |
|
| 2079 |
* Add :c:func:`PyUnicode_AsUTF8AndSize` to the limited C API. |
| 2080 |
(Contributed by Alex Gaynor in :issue:`41784`.) |
| 2081 |
|
| 2082 |
* Add :c:func:`PyModule_AddObjectRef` function: similar to |
| 2083 |
:c:func:`PyModule_AddObject` but don't steal a reference to the value on |
| 2084 |
success. |
| 2085 |
(Contributed by Victor Stinner in :issue:`1635741`.) |
| 2086 |
|
| 2087 |
* Add :c:func:`Py_NewRef` and :c:func:`Py_XNewRef` functions to increment the |
| 2088 |
reference count of an object and return the object. |
| 2089 |
(Contributed by Victor Stinner in :issue:`42262`.) |
| 2090 |
|
| 2091 |
* The :c:func:`PyType_FromSpecWithBases` and :c:func:`PyType_FromModuleAndSpec` |
| 2092 |
functions now accept a single class as the *bases* argument. |
| 2093 |
(Contributed by Serhiy Storchaka in :issue:`42423`.) |
| 2094 |
|
| 2095 |
* The :c:func:`PyType_FromModuleAndSpec` function now accepts NULL ``tp_doc`` |
| 2096 |
slot. |
| 2097 |
(Contributed by Hai Shi in :issue:`41832`.) |
| 2098 |
|
| 2099 |
* The :c:func:`PyType_GetSlot` function can accept |
| 2100 |
:ref:`static types <static-types>`. |
| 2101 |
(Contributed by Hai Shi and Petr Viktorin in :issue:`41073`.) |
| 2102 |
|
| 2103 |
* Add a new :c:func:`PySet_CheckExact` function to the C-API to check if an |
| 2104 |
object is an instance of :class:`set` but not an instance of a subtype. |
| 2105 |
(Contributed by Pablo Galindo in :issue:`43277`.) |
| 2106 |
|
| 2107 |
* Add :c:func:`PyErr_SetInterruptEx` which allows passing a signal number |
| 2108 |
to simulate. |
| 2109 |
(Contributed by Antoine Pitrou in :issue:`43356`.) |
| 2110 |
|
| 2111 |
* The limited C API is now supported if :ref:`Python is built in debug mode |
| 2112 |
<debug-build>` (if the ``Py_DEBUG`` macro is defined). In the limited C API, |
| 2113 |
the :c:func:`Py_INCREF` and :c:func:`Py_DECREF` functions are now implemented |
| 2114 |
as opaque function |
| 2115 |
calls, rather than accessing directly the :c:member:`PyObject.ob_refcnt` |
| 2116 |
member, if Python is built in debug mode and the ``Py_LIMITED_API`` macro |
| 2117 |
targets Python 3.10 or newer. It became possible to support the limited C API |
| 2118 |
in debug mode because the :c:type:`PyObject` structure is the same in release |
| 2119 |
and debug mode since Python 3.8 (see :issue:`36465`). |
| 2120 |
|
| 2121 |
The limited C API is still not supported in the :option:`--with-trace-refs` |
| 2122 |
special build (``Py_TRACE_REFS`` macro). |
| 2123 |
(Contributed by Victor Stinner in :issue:`43688`.) |
| 2124 |
|
| 2125 |
* Add the :c:func:`Py_Is(x, y) <Py_Is>` function to test if the *x* object is |
| 2126 |
the *y* object, the same as ``x is y`` in Python. Add also the |
| 2127 |
:c:func:`Py_IsNone`, :c:func:`Py_IsTrue`, :c:func:`Py_IsFalse` functions to |
| 2128 |
test if an object is, respectively, the ``None`` singleton, the ``True`` |
| 2129 |
singleton or the ``False`` singleton. |
| 2130 |
(Contributed by Victor Stinner in :issue:`43753`.) |
| 2131 |
|
| 2132 |
* Add new functions to control the garbage collector from C code: |
| 2133 |
:c:func:`PyGC_Enable()`, |
| 2134 |
:c:func:`PyGC_Disable()`, |
| 2135 |
:c:func:`PyGC_IsEnabled()`. |
| 2136 |
These functions allow to activate, deactivate and query the state of the garbage collector from C code without |
| 2137 |
having to import the :mod:`gc` module. |
| 2138 |
|
| 2139 |
* Add a new :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` type flag to disallow |
| 2140 |
creating type instances. |
| 2141 |
(Contributed by Victor Stinner in :issue:`43916`.) |
| 2142 |
|
| 2143 |
* Add a new :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` type flag for creating immutable |
| 2144 |
type objects: type attributes cannot be set nor deleted. |
| 2145 |
(Contributed by Victor Stinner and Erlend E. Aasland in :issue:`43908`.) |
| 2146 |
|
| 2147 |
Porting to Python 3.10 |
| 2148 |
---------------------- |
| 2149 |
|
| 2150 |
* The ``PY_SSIZE_T_CLEAN`` macro must now be defined to use |
| 2151 |
:c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` formats which use |
| 2152 |
``#``: ``es#``, ``et#``, ``s#``, ``u#``, ``y#``, ``z#``, ``U#`` and ``Z#``. |
| 2153 |
See :ref:`arg-parsing` and :pep:`353`. |
| 2154 |
(Contributed by Victor Stinner in :issue:`40943`.) |
| 2155 |
|
| 2156 |
* Since :c:func:`Py_REFCNT()` is changed to the inline static function, |
| 2157 |
``Py_REFCNT(obj) = new_refcnt`` must be replaced with ``Py_SET_REFCNT(obj, new_refcnt)``: |
| 2158 |
see :c:func:`Py_SET_REFCNT()` (available since Python 3.9). For backward |
| 2159 |
compatibility, this macro can be used:: |
| 2160 |
|
| 2161 |
#if PY_VERSION_HEX < 0x030900A4 |
| 2162 |
# define Py_SET_REFCNT(obj, refcnt) ((Py_REFCNT(obj) = (refcnt)), (void)0) |
| 2163 |
#endif |
| 2164 |
|
| 2165 |
(Contributed by Victor Stinner in :issue:`39573`.) |
| 2166 |
|
| 2167 |
* Calling :c:func:`PyDict_GetItem` without :term:`GIL` held had been allowed |
| 2168 |
for historical reason. It is no longer allowed. |
| 2169 |
(Contributed by Victor Stinner in :issue:`40839`.) |
| 2170 |
|
| 2171 |
* ``PyUnicode_FromUnicode(NULL, size)`` and ``PyUnicode_FromStringAndSize(NULL, size)`` |
| 2172 |
raise ``DeprecationWarning`` now. Use :c:func:`PyUnicode_New` to allocate |
| 2173 |
Unicode object without initial data. |
| 2174 |
(Contributed by Inada Naoki in :issue:`36346`.) |
| 2175 |
|
| 2176 |
* The private ``_PyUnicode_Name_CAPI`` structure of the PyCapsule API |
| 2177 |
``unicodedata.ucnhash_CAPI`` has been moved to the internal C API. |
| 2178 |
(Contributed by Victor Stinner in :issue:`42157`.) |
| 2179 |
|
| 2180 |
* :c:func:`Py_GetPath`, :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, |
| 2181 |
:c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome` and |
| 2182 |
:c:func:`Py_GetProgramName` functions now return ``NULL`` if called before |
| 2183 |
:c:func:`Py_Initialize` (before Python is initialized). Use the new |
| 2184 |
:ref:`init-config` API to get the :ref:`init-path-config`. |
| 2185 |
(Contributed by Victor Stinner in :issue:`42260`.) |
| 2186 |
|
| 2187 |
* :c:func:`PyList_SET_ITEM`, :c:func:`PyTuple_SET_ITEM` and |
| 2188 |
:c:func:`PyCell_SET` macros can no longer be used as l-value or r-value. |
| 2189 |
For example, ``x = PyList_SET_ITEM(a, b, c)`` and |
| 2190 |
``PyList_SET_ITEM(a, b, c) = x`` now fail with a compiler error. It prevents |
| 2191 |
bugs like ``if (PyList_SET_ITEM (a, b, c) < 0) ...`` test. |
| 2192 |
(Contributed by Zackery Spytz and Victor Stinner in :issue:`30459`.) |
| 2193 |
|
| 2194 |
* The non-limited API files ``odictobject.h``, ``parser_interface.h``, |
| 2195 |
``picklebufobject.h``, ``pyarena.h``, ``pyctype.h``, ``pydebug.h``, |
| 2196 |
``pyfpe.h``, and ``pytime.h`` have been moved to the ``Include/cpython`` |
| 2197 |
directory. These files must not be included directly, as they are already |
| 2198 |
included in ``Python.h``; see :ref:`api-includes`. If they have |
| 2199 |
been included directly, consider including ``Python.h`` instead. |
| 2200 |
(Contributed by Nicholas Sim in :issue:`35134`.) |
| 2201 |
|
| 2202 |
* Use the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` type flag to create immutable type |
| 2203 |
objects. Do not rely on :c:macro:`Py_TPFLAGS_HEAPTYPE` to decide if a type |
| 2204 |
object is mutable or not; check if :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` is set |
| 2205 |
instead. |
| 2206 |
(Contributed by Victor Stinner and Erlend E. Aasland in :issue:`43908`.) |
| 2207 |
|
| 2208 |
* The undocumented function ``Py_FrozenMain`` has been removed from the |
| 2209 |
limited API. The function is mainly useful for custom builds of Python. |
| 2210 |
(Contributed by Petr Viktorin in :issue:`26241`.) |
| 2211 |
|
| 2212 |
Deprecated |
| 2213 |
---------- |
| 2214 |
|
| 2215 |
* The ``PyUnicode_InternImmortal()`` function is now deprecated |
| 2216 |
and will be removed in Python 3.12: use :c:func:`PyUnicode_InternInPlace` |
| 2217 |
instead. |
| 2218 |
(Contributed by Victor Stinner in :issue:`41692`.) |
| 2219 |
|
| 2220 |
Removed |
| 2221 |
------- |
| 2222 |
|
| 2223 |
* Removed ``Py_UNICODE_str*`` functions manipulating ``Py_UNICODE*`` strings. |
| 2224 |
(Contributed by Inada Naoki in :issue:`41123`.) |
| 2225 |
|
| 2226 |
* ``Py_UNICODE_strlen``: use :c:func:`PyUnicode_GetLength` or |
| 2227 |
:c:macro:`PyUnicode_GET_LENGTH` |
| 2228 |
* ``Py_UNICODE_strcat``: use :c:func:`PyUnicode_CopyCharacters` or |
| 2229 |
:c:func:`PyUnicode_FromFormat` |
| 2230 |
* ``Py_UNICODE_strcpy``, ``Py_UNICODE_strncpy``: use |
| 2231 |
:c:func:`PyUnicode_CopyCharacters` or :c:func:`PyUnicode_Substring` |
| 2232 |
* ``Py_UNICODE_strcmp``: use :c:func:`PyUnicode_Compare` |
| 2233 |
* ``Py_UNICODE_strncmp``: use :c:func:`PyUnicode_Tailmatch` |
| 2234 |
* ``Py_UNICODE_strchr``, ``Py_UNICODE_strrchr``: use |
| 2235 |
:c:func:`PyUnicode_FindChar` |
| 2236 |
|
| 2237 |
* Removed ``PyUnicode_GetMax()``. Please migrate to new (:pep:`393`) APIs. |
| 2238 |
(Contributed by Inada Naoki in :issue:`41103`.) |
| 2239 |
|
| 2240 |
* Removed ``PyLong_FromUnicode()``. Please migrate to :c:func:`PyLong_FromUnicodeObject`. |
| 2241 |
(Contributed by Inada Naoki in :issue:`41103`.) |
| 2242 |
|
| 2243 |
* Removed ``PyUnicode_AsUnicodeCopy()``. Please use :c:func:`PyUnicode_AsUCS4Copy` or |
| 2244 |
:c:func:`PyUnicode_AsWideCharString` |
| 2245 |
(Contributed by Inada Naoki in :issue:`41103`.) |
| 2246 |
|
| 2247 |
* Removed ``_Py_CheckRecursionLimit`` variable: it has been replaced by |
| 2248 |
``ceval.recursion_limit`` of the :c:type:`PyInterpreterState` structure. |
| 2249 |
(Contributed by Victor Stinner in :issue:`41834`.) |
| 2250 |
|
| 2251 |
* Removed undocumented macros ``Py_ALLOW_RECURSION`` and |
| 2252 |
``Py_END_ALLOW_RECURSION`` and the ``recursion_critical`` field of the |
| 2253 |
:c:type:`PyInterpreterState` structure. |
| 2254 |
(Contributed by Serhiy Storchaka in :issue:`41936`.) |
| 2255 |
|
| 2256 |
* Removed the undocumented ``PyOS_InitInterrupts()`` function. Initializing |
| 2257 |
Python already implicitly installs signal handlers: see |
| 2258 |
:c:member:`PyConfig.install_signal_handlers`. |
| 2259 |
(Contributed by Victor Stinner in :issue:`41713`.) |
| 2260 |
|
| 2261 |
* Remove the ``PyAST_Validate()`` function. It is no longer possible to build a |
| 2262 |
AST object (``mod_ty`` type) with the public C API. The function was already |
| 2263 |
excluded from the limited C API (:pep:`384`). |
| 2264 |
(Contributed by Victor Stinner in :issue:`43244`.) |
| 2265 |
|
| 2266 |
* Remove the ``symtable.h`` header file and the undocumented functions: |
| 2267 |
|
| 2268 |
* ``PyST_GetScope()`` |
| 2269 |
* ``PySymtable_Build()`` |
| 2270 |
* ``PySymtable_BuildObject()`` |
| 2271 |
* ``PySymtable_Free()`` |
| 2272 |
* ``Py_SymtableString()`` |
| 2273 |
* ``Py_SymtableStringObject()`` |
| 2274 |
|
| 2275 |
The ``Py_SymtableString()`` function was part the stable ABI by mistake but |
| 2276 |
it could not be used, because the ``symtable.h`` header file was excluded |
| 2277 |
from the limited C API. |
| 2278 |
|
| 2279 |
Use Python :mod:`symtable` module instead. |
| 2280 |
(Contributed by Victor Stinner in :issue:`43244`.) |
| 2281 |
|
| 2282 |
* Remove :c:func:`PyOS_ReadlineFunctionPointer` from the limited C API headers |
| 2283 |
and from ``python3.dll``, the library that provides the stable ABI on |
| 2284 |
Windows. Since the function takes a ``FILE*`` argument, its ABI stability |
| 2285 |
cannot be guaranteed. |
| 2286 |
(Contributed by Petr Viktorin in :issue:`43868`.) |
| 2287 |
|
| 2288 |
* Remove ``ast.h``, ``asdl.h``, and ``Python-ast.h`` header files. |
| 2289 |
These functions were undocumented and excluded from the limited C API. |
| 2290 |
Most names defined by these header files were not prefixed by ``Py`` and so |
| 2291 |
could create names conflicts. For example, ``Python-ast.h`` defined a |
| 2292 |
``Yield`` macro which was conflict with the ``Yield`` name used by the |
| 2293 |
Windows ``<winbase.h>`` header. Use the Python :mod:`ast` module instead. |
| 2294 |
(Contributed by Victor Stinner in :issue:`43244`.) |
| 2295 |
|
| 2296 |
* Remove the compiler and parser functions using ``struct _mod`` type, because |
| 2297 |
the public AST C API was removed: |
| 2298 |
|
| 2299 |
* ``PyAST_Compile()`` |
| 2300 |
* ``PyAST_CompileEx()`` |
| 2301 |
* ``PyAST_CompileObject()`` |
| 2302 |
* ``PyFuture_FromAST()`` |
| 2303 |
* ``PyFuture_FromASTObject()`` |
| 2304 |
* ``PyParser_ASTFromFile()`` |
| 2305 |
* ``PyParser_ASTFromFileObject()`` |
| 2306 |
* ``PyParser_ASTFromFilename()`` |
| 2307 |
* ``PyParser_ASTFromString()`` |
| 2308 |
* ``PyParser_ASTFromStringObject()`` |
| 2309 |
|
| 2310 |
These functions were undocumented and excluded from the limited C API. |
| 2311 |
(Contributed by Victor Stinner in :issue:`43244`.) |
| 2312 |
|
| 2313 |
* Remove the ``pyarena.h`` header file with functions: |
| 2314 |
|
| 2315 |
* ``PyArena_New()`` |
| 2316 |
* ``PyArena_Free()`` |
| 2317 |
* ``PyArena_Malloc()`` |
| 2318 |
* ``PyArena_AddPyObject()`` |
| 2319 |
|
| 2320 |
These functions were undocumented, excluded from the limited C API, and were |
| 2321 |
only used internally by the compiler. |
| 2322 |
(Contributed by Victor Stinner in :issue:`43244`.) |
| 2323 |
|
| 2324 |
* The ``PyThreadState.use_tracing`` member has been removed to optimize Python. |
| 2325 |
(Contributed by Mark Shannon in :issue:`43760`.) |
| 2326 |
|
| 2327 |
|
| 2328 |
Notable security feature in 3.10.7 |
| 2329 |
================================== |
| 2330 |
|
| 2331 |
Converting between :class:`int` and :class:`str` in bases other than 2 |
| 2332 |
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal) |
| 2333 |
now raises a :exc:`ValueError` if the number of digits in string form is |
| 2334 |
above a limit to avoid potential denial of service attacks due to the |
| 2335 |
algorithmic complexity. This is a mitigation for :cve:`2020-10735`. |
| 2336 |
This limit can be configured or disabled by environment variable, command |
| 2337 |
line flag, or :mod:`sys` APIs. See the :ref:`integer string conversion |
| 2338 |
length limitation <int_max_str_digits>` documentation. The default limit |
| 2339 |
is 4300 digits in string form. |
| 2340 |
|
| 2341 |
Notable security feature in 3.10.8 |
| 2342 |
================================== |
| 2343 |
|
| 2344 |
The deprecated :mod:`!mailcap` module now refuses to inject unsafe text |
| 2345 |
(filenames, MIME types, parameters) into shell commands. Instead of using such |
| 2346 |
text, it will warn and act as if a match was not found (or for test commands, |
| 2347 |
as if the test failed). |
| 2348 |
(Contributed by Petr Viktorin in :gh:`98966`.) |
| 2349 |
|
| 2350 |
Notable changes in 3.10.12 |
| 2351 |
========================== |
| 2352 |
|
| 2353 |
tarfile |
| 2354 |
------- |
| 2355 |
|
| 2356 |
* The extraction methods in :mod:`tarfile`, and :func:`shutil.unpack_archive`, |
| 2357 |
have a new a *filter* argument that allows limiting tar features than may be |
| 2358 |
surprising or dangerous, such as creating files outside the destination |
| 2359 |
directory. |
| 2360 |
See :ref:`tarfile-extraction-filter` for details. |
| 2361 |
In Python 3.12, use without the *filter* argument will show a |
| 2362 |
:exc:`DeprecationWarning`. |
| 2363 |
In Python 3.14, the default will switch to ``'data'``. |
| 2364 |
(Contributed by Petr Viktorin in :pep:`706`.) |