Debian Codegraph @

Doc/whatsnew/3.10.rst

raw
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 :data:`types.EllipsisType`, :data:`types.NoneType`
1450 and :data:`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`.)