summaryrefslogtreecommitdiffstats
path: root/Doc/whatsnew/3.10.rst
blob: 581d3a57e84573845f1cde8a494340f4b2e8160d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
****************************
  What's New In Python 3.10
****************************

:Release: |release|
:Date: |today|

.. Rules for maintenance:

   * Anyone can add text to this document.  Do not spend very much time
   on the wording of your changes, because your text will probably
   get rewritten to some degree.

   * The maintainer will go through Misc/NEWS periodically and add
   changes; it's therefore more important to add your changes to
   Misc/NEWS than to this file.

   * This is not a complete list of every single change; completeness
   is the purpose of Misc/NEWS.  Some changes I consider too small
   or esoteric to include.  If such a change is added to the text,
   I'll just remove it.  (This is another reason you shouldn't spend
   too much time on writing your addition.)

   * If you want to draw your new text to the attention of the
   maintainer, add 'XXX' to the beginning of the paragraph or
   section.

   * It's OK to just add a fragmentary note about a change.  For
   example: "XXX Describe the transmogrify() function added to the
   socket module."  The maintainer will research the change and
   write the necessary text.

   * You can comment out your additions if you like, but it's not
   necessary (especially when a final release is some months away).

   * Credit the author of a patch or bugfix.   Just the name is
   sufficient; the e-mail address isn't necessary.

   * It's helpful to add the bug/patch number as a comment:

   XXX Describe the transmogrify() function added to the socket
   module.
   (Contributed by P.Y. Developer in :issue:`12345`.)

   This saves the maintainer the effort of going through the Mercurial log
   when researching a change.

This article explains the new features in Python 3.10, compared to 3.9.

For full details, see the :ref:`changelog <changelog>`.

.. note::

   Prerelease users should be aware that this document is currently in draft
   form. It will be updated substantially as Python 3.10 moves towards release,
   so it's worth checking back even after reading earlier versions.


Summary -- Release highlights
=============================

.. This section singles out the most important changes in Python 3.10.
   Brevity is key.


.. PEP-sized items next.



New Features
============

.. _whatsnew310-pep563:

PEP 563: Postponed Evaluation of Annotations Becomes Default
------------------------------------------------------------

In Python 3.7, postponed evaluation of annotations was added,
to be enabled with a ``from __future__ import annotations``
directive.  In 3.10 this became the default behavior, even
without that future directive.  With this being default, all
annotations stored in :attr:`__annotations__` will be strings.
If needed, annotations can be resolved at runtime using
:func:`typing.get_type_hints`.  See :pep:`563` for a full
description.  Also, the :func:`inspect.signature` will try to
resolve types from now on, and when it fails it will fall back to
showing the string annotations.  (Contributed by Batuhan Taskaya
in :issue:`38605`.)

* The :class:`int` type has a new method :meth:`int.bit_count`, returning the
  number of ones in the binary expansion of a given integer, also known
  as the population count. (Contributed by Niklas Fiekas in :issue:`29882`.)

* The views returned by :meth:`dict.keys`, :meth:`dict.values` and
  :meth:`dict.items` now all have a ``mapping`` attribute that gives a
  :class:`types.MappingProxyType` object wrapping the original
  dictionary. (Contributed by Dennis Sweeney in :issue:`40890`.)

* :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used
  to require that all the iterables have an equal length.

PEP 613: TypeAlias Annotation
-----------------------------

:pep:`484` introduced the concept of type aliases, only requiring them to be
top-level unannotated assignments. This simplicity sometimes made it difficult
for type checkers to distinguish between type aliases and ordinary assignments,
especially when forward references or invalid types were involved. Compare::

   StrCache = 'Cache[str]'  # a type alias
   LOG_PREFIX = 'LOG[DEBUG]'  # a module constant

Now the :mod:`typing` module has a special annotation :data:`TypeAlias` to
declare type aliases more explicitly::

   StrCache: TypeAlias = 'Cache[str]'  # a type alias
   LOG_PREFIX = 'LOG[DEBUG]'  # a module constant

See :pep:`613` for more details.

(Contributed by Mikhail Golubev in :issue:`41923`.)

PEP604: New Type Union Operator
-------------------------------

A new type union operator was introduced which enables the syntax ``X | Y``.
This provides a cleaner way of expressing 'either type X or type Y' instead of
using :data:`typing.Union`, especially in type hints (annotations).

In previous versions of Python, to apply a type hint for functions accepting
arguments of multiple types, :data:`typing.Union` was used::

   def square(number: Union[int, float]) -> Union[int, float]:
       return number ** 2


Now, type hints can be written in a more succinct manner::

   def square(number: int | float) -> int | float:
       return number ** 2


See :pep:`604` for more details.

(Contributed by Maggie Moss and Philippe Prados in :issue:`41428`.)

Other Language Changes
======================

* Builtin and extension functions that take integer arguments no longer accept
  :class:`~decimal.Decimal`\ s, :class:`~fractions.Fraction`\ s and other
  objects that can be converted to integers only with a loss (e.g. that have
  the :meth:`~object.__int__` method but do not have the
  :meth:`~object.__index__` method).
  (Contributed by Serhiy Storchaka in :issue:`37999`.)


New Modules
===========

* None yet.


Improved Modules
================

base64
------

Add :func:`base64.b32hexencode` and :func:`base64.b32hexdecode` to support the
Base32 Encoding with Extended Hex Alphabet.

codecs
------

Add a :func:`codecs.unregister` function to unregister a codec search function.
(Contributed by Hai Shi in :issue:`41842`.)

curses
------

The extended color functions added in ncurses 6.1 will be used transparently
by :func:`curses.color_content`, :func:`curses.init_color`,
:func:`curses.init_pair`, and :func:`curses.pair_content`. A new function,
:func:`curses.has_extended_color_support`, indicates whether extended color
support is provided by the underlying ncurses library.
(Contributed by Jeffrey Kintscher and Hans Petter Jansson in :issue:`36982`.)

encodings
---------
:func:`encodings.normalize_encoding` now ignores non-ASCII characters.
(Contributed by Hai Shi in :issue:`39337`.)

glob
----

Added the *root_dir* and *dir_fd* parameters in :func:`~glob.glob` and
:func:`~glob.iglob` which allow to specify the root directory for searching.
(Contributed by Serhiy Storchaka in :issue:`38144`.)

os
--

Added :func:`os.cpu_count()` support for VxWorks RTOS.
(Contributed by Peixing Xin in :issue:`41440`.)

py_compile
----------

Added ``--quiet`` option to command-line interface of :mod:`py_compile`.
(Contributed by Gregory Schevchenko in :issue:`38731`.)

sys
---

Add :data:`sys.orig_argv` attribute: the list of the original command line
arguments passed to the Python executable.
(Contributed by Victor Stinner in :issue:`23427`.)

types
-----

Reintroduced the :data:`types.EllipsisType`, :data:`types.NoneType`
and :data:`types.NotImplementedType` classes, providing a new set
of types readily interpretable by type checkers.
(Contributed by Bas van Beek in :issue:`41810`.)

unittest
--------

Add new method :meth:`~unittest.TestCase.assertNoLogs` to complement the
existing :meth:`~unittest.TestCase.assertLogs`. (Contributed by Kit Yan Choi
in :issue:`39385`.)

xml
---

Add a :class:`~xml.sax.handler.LexicalHandler` class to the
:mod:`xml.sax.handler` module.
(Contributed by Jonathan Gossage and Zackery Spytz in :issue:`35018`.)


Optimizations
=============

* Constructors :func:`str`, :func:`bytes` and :func:`bytearray` are now faster
  (around 30--40% for small objects).
  (Contributed by Serhiy Storchaka in :issue:`41334`.)

* The :mod:`runpy` module now imports fewer modules.
  The ``python3 -m module-name`` command startup time is 1.3x faster in
  average.
  (Contributed by Victor Stinner in :issue:`41006`.)

* The ``LOAD_ATTR`` instruction now uses new "per opcode cache" mechanism.
  It is about 36% faster now.  (Contributed by Pablo Galindo and Yury Selivanov
  in :issue:`42093`.)

* When building Python with ``--enable-optimizations`` now
  ``-fno-semantic-interposition`` is added to both the compile and link line.
  This speeds builds of the Python interpreter created with ``--enable-shared``
  with ``gcc`` by up to 30%. See `this article
  <https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/>`_
  for more details. (Contributed by Victor Stinner and Pablo Galindo in
  :issue:`38980`)

Deprecated
==========

* Starting in this release, there will be a concerted effort to begin
  cleaning up old import semantics that were kept for Python 2.7
  compatibility. Specifically,
  :meth:`~importlib.abc.PathEntryFinder.find_loader`/:meth:`~importlib.abc.Finder.find_module`
  (superseded by :meth:`~importlib.abc.Finder.find_spec`),
  :meth:`~importlib.abc.Loader.load_module`
  (superseded by :meth:`~importlib.abc.Loader.exec_module`),
  :meth:`~importlib.abc.Loader.module_repr` (which the import system
  takes care of for you), the ``__package__`` attribute
  (superseded by ``__spec__.parent``), the ``__loader__`` attribute
  (superseded by ``__spec__.loader``), and the ``__cached__`` attribute
  (superseded by ``__spec__.cached``) will slowly be removed (as well
  as other classes and methods in :mod:`importlib`).
  :exc:`ImportWarning` and/or :exc:`DeprecationWarning` will be raised
  as appropriate to help identify code which needs updating during
  this transition.


Removed
=======

* Removed special methods ``__int__``, ``__float__``, ``__floordiv__``,
  ``__mod__``, ``__divmod__``, ``__rfloordiv__``, ``__rmod__`` and
  ``__rdivmod__`` of the :class:`complex` class.  They always raised
  a :exc:`TypeError`.
  (Contributed by Serhiy Storchaka in :issue:`41974`.)

* The ``ParserBase.error()`` method from the private and undocumented ``_markupbase``
  module has been removed.  :class:`html.parser.HTMLParser` is the only subclass of
  ``ParserBase`` and its ``error()`` implementation has already been removed in
  Python 3.5.
  (Contributed by Berker Peksag in :issue:`31844`.)


Porting to Python 3.10
======================

This section lists previously described changes and other bugfixes
that may require changes to your code.



Build Changes
=============


* The C99 functions :c:func:`snprintf` and :c:func:`vsnprintf` are now required
  to build Python.
  (Contributed by Victor Stinner in :issue:`36020`.)

* :mod:`sqlite3` requires SQLite 3.7.3 or higher.
  (Contributed by Sergey Fedoseev and Erlend E. Aasland :issue:`40744`.)



C API Changes
=============

New Features
------------

* The result of :c:func:`PyNumber_Index` now always has exact type :class:`int`.
  Previously, the result could have been an instance of a subclass of ``int``.
  (Contributed by Serhiy Storchaka in :issue:`40792`.)

* Add a new :c:member:`~PyConfig.orig_argv` member to the :c:type:`PyConfig`
  structure: the list of the original command line arguments passed to the
  Python executable.
  (Contributed by Victor Stinner in :issue:`23427`.)

* The :c:func:`PyDateTime_DATE_GET_TZINFO` and
  :c:func:`PyDateTime_TIME_GET_TZINFO` macros have been added for accessing
  the ``tzinfo`` attributes of :class:`datetime.datetime` and
  :class:`datetime.time` objects.
  (Contributed by Zackery Spytz in :issue:`30155`.)

* Add a :c:func:`PyCodec_Unregister` function to unregister a codec
  search function.
  (Contributed by Hai Shi in :issue:`41842`.)

* The :c:func:`PyIter_Send` function was added to allow
  sending value into iterator without raising ``StopIteration`` exception.
  (Contributed by Vladimir Matveev in :issue:`41756`.)

* Added :c:func:`PyUnicode_AsUTF8AndSize` to the limited C API.
  (Contributed by Alex Gaynor in :issue:`41784`.)


Porting to Python 3.10
----------------------

* The ``PY_SSIZE_T_CLEAN`` macro must now be defined to use
  :c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` formats which use
  ``#``: ``es#``, ``et#``, ``s#``, ``u#``, ``y#``, ``z#``, ``U#`` and ``Z#``.
  See :ref:`Parsing arguments and building values
  <arg-parsing>` and the :pep:`353`.
  (Contributed by Victor Stinner in :issue:`40943`.)

* Since :c:func:`Py_TYPE()` is changed to the inline static function,
  ``Py_TYPE(obj) = new_type`` must be replaced with ``Py_SET_TYPE(obj, new_type)``:
  see :c:func:`Py_SET_TYPE()` (available since Python 3.9). For backward
  compatibility, this macro can be used::

      #if PY_VERSION_HEX < 0x030900A4
      #  define Py_SET_TYPE(obj, type) ((Py_TYPE(obj) = (type)), (void)0)
      #endif

  (Contributed by Dong-hee Na in :issue:`39573`.)

* Since :c:func:`Py_REFCNT()` is changed to the inline static function,
  ``Py_REFCNT(obj) = new_refcnt`` must be replaced with ``Py_SET_REFCNT(obj, new_refcnt)``:
  see :c:func:`Py_SET_REFCNT()` (available since Python 3.9). For backward
  compatibility, this macro can be used::

      #if PY_VERSION_HEX < 0x030900A4
      #  define Py_SET_REFCNT(obj, refcnt) ((Py_REFCNT(obj) = (refcnt)), (void)0)
      #endif

  (Contributed by Victor Stinner in :issue:`39573`.)

* Since :c:func:`Py_SIZE()` is changed to the inline static function,
  ``Py_SIZE(obj) = new_size`` must be replaced with ``Py_SET_SIZE(obj, new_size)``:
  see :c:func:`Py_SET_SIZE()` (available since Python 3.9). For backward
  compatibility, this macro can be used::

      #if PY_VERSION_HEX < 0x030900A4
      #  define Py_SET_SIZE(obj, size) ((Py_SIZE(obj) = (size)), (void)0)
      #endif

  (Contributed by Victor Stinner in :issue:`39573`.)

* Calling :c:func:`PyDict_GetItem` without :term:`GIL` held had been allowed
  for historical reason. It is no longer allowed.
  (Contributed by Victor Stinner in :issue:`40839`.)

* ``PyUnicode_FromUnicode(NULL, size)`` and ``PyUnicode_FromStringAndSize(NULL, size)``
  raise ``DeprecationWarning`` now.  Use :c:func:`PyUnicode_New` to allocate
  Unicode object without initial data.
  (Contributed by Inada Naoki in :issue:`36346`.)

* The private ``_PyUnicode_Name_CAPI`` structure of the PyCapsule API
  ``unicodedata.ucnhash_CAPI`` moves to the internal C API. Moreover,
  the structure gets a new ``state`` member which must be passed to the
  ``getcode()`` and ``getname()`` functions.
  (Contributed by Victor Stinner in :issue:`1635741`.)

Deprecated
----------

* The ``PyUnicode_InternImmortal()`` function is now deprecated
  and will be removed in Python 3.12: use :c:func:`PyUnicode_InternInPlace`
  instead.
  (Contributed by Victor Stinner in :issue:`41692`.)

Removed
-------

* ``PyObject_AsCharBuffer()``, ``PyObject_AsReadBuffer()``, ``PyObject_CheckReadBuffer()``,
  and ``PyObject_AsWriteBuffer()`` are removed. Please migrate to new buffer protocol;
  :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release`.
  (Contributed by Inada Naoki in :issue:`41103`.)

* Removed ``Py_UNICODE_str*`` functions manipulating ``Py_UNICODE*`` strings.
  (Contributed by Inada Naoki in :issue:`41123`.)

   * ``Py_UNICODE_strlen``: use :c:func:`PyUnicode_GetLength` or
     :c:macro:`PyUnicode_GET_LENGTH`
   * ``Py_UNICODE_strcat``: use :c:func:`PyUnicode_CopyCharacters` or
     :c:func:`PyUnicode_FromFormat`
   * ``Py_UNICODE_strcpy``, ``Py_UNICODE_strncpy``: use
     :c:func:`PyUnicode_CopyCharacters` or :c:func:`PyUnicode_Substring`
   * ``Py_UNICODE_strcmp``: use :c:func:`PyUnicode_Compare`
   * ``Py_UNICODE_strncmp``: use :c:func:`PyUnicode_Tailmatch`
   * ``Py_UNICODE_strchr``, ``Py_UNICODE_strrchr``: use
     :c:func:`PyUnicode_FindChar`

* Removed ``PyUnicode_GetMax()``. Please migrate to new (:pep:`393`) APIs.
  (Contributed by Inada Naoki in :issue:`41103`.)

* Removed ``PyLong_FromUnicode()``. Please migrate to :c:func:`PyLong_FromUnicodeObject`.
  (Contributed by Inada Naoki in :issue:`41103`.)

* Removed ``PyUnicode_AsUnicodeCopy()``. Please use :c:func:`PyUnicode_AsUCS4Copy` or
  :c:func:`PyUnicode_AsWideCharString`
  (Contributed by Inada Naoki in :issue:`41103`.)

* Removed ``_Py_CheckRecursionLimit`` variable: it has been replaced by
  ``ceval.recursion_limit`` of the :c:type:`PyInterpreterState` structure.
  (Contributed by Victor Stinner in :issue:`41834`.)

* Removed undocumented macros ``Py_ALLOW_RECURSION`` and
  ``Py_END_ALLOW_RECURSION`` and the ``recursion_critical`` field of the
  :c:type:`PyInterpreterState` structure.
  (Contributed by Serhiy Storchaka in :issue:`41936`.)