blob: e464be6eb7e951b5786b06e4e26d8657aba2234d [file] [log] [blame]
Pablo Galindod4fe0982020-05-19 03:33:01 +01001****************************
2 What's New In Python 3.10
3****************************
4
5:Release: |release|
6:Date: |today|
7
8.. Rules for maintenance:
9
10 * Anyone can add text to this document. Do not spend very much time
11 on the wording of your changes, because your text will probably
12 get rewritten to some degree.
13
14 * The maintainer will go through Misc/NEWS periodically and add
15 changes; it's therefore more important to add your changes to
16 Misc/NEWS than to this file.
17
18 * This is not a complete list of every single change; completeness
19 is the purpose of Misc/NEWS. Some changes I consider too small
20 or esoteric to include. If such a change is added to the text,
21 I'll just remove it. (This is another reason you shouldn't spend
22 too much time on writing your addition.)
23
24 * If you want to draw your new text to the attention of the
25 maintainer, add 'XXX' to the beginning of the paragraph or
26 section.
27
28 * It's OK to just add a fragmentary note about a change. For
29 example: "XXX Describe the transmogrify() function added to the
30 socket module." The maintainer will research the change and
31 write the necessary text.
32
33 * You can comment out your additions if you like, but it's not
34 necessary (especially when a final release is some months away).
35
36 * Credit the author of a patch or bugfix. Just the name is
37 sufficient; the e-mail address isn't necessary.
38
39 * It's helpful to add the bug/patch number as a comment:
40
41 XXX Describe the transmogrify() function added to the socket
42 module.
43 (Contributed by P.Y. Developer in :issue:`12345`.)
44
45 This saves the maintainer the effort of going through the Mercurial log
46 when researching a change.
47
48This article explains the new features in Python 3.10, compared to 3.9.
49
Ned Deily29251b72020-05-19 07:39:29 -040050For full details, see the :ref:`changelog <changelog>`.
Pablo Galindod4fe0982020-05-19 03:33:01 +010051
52.. note::
53
54 Prerelease users should be aware that this document is currently in draft
55 form. It will be updated substantially as Python 3.10 moves towards release,
56 so it's worth checking back even after reading earlier versions.
57
58
59Summary -- Release highlights
60=============================
61
62.. This section singles out the most important changes in Python 3.10.
63 Brevity is key.
64
65
66.. PEP-sized items next.
67
68
69
70New Features
71============
72
Batuhan Taskaya044a1042020-10-06 23:03:02 +030073.. _whatsnew310-pep563:
74
75PEP 563: Postponed Evaluation of Annotations Becomes Default
76------------------------------------------------------------
77
78In Python 3.7, postponed evaluation of annotations was added,
79to be enabled with a ``from __future__ import annotations``
80directive. In 3.10 this became the default behavior, even
81without that future directive. With this being default, all
82annotations stored in :attr:`__annotations__` will be strings.
83If needed, annotations can be resolved at runtime using
84:func:`typing.get_type_hints`. See :pep:`563` for a full
85description. Also, the :func:`inspect.signature` will try to
86resolve types from now on, and when it fails it will fall back to
87showing the string annotations. (Contributed by Batuhan Taskaya
88in :issue:`38605`.)
89
Niklas Fiekas8bd216d2020-05-29 18:28:02 +020090* The :class:`int` type has a new method :meth:`int.bit_count`, returning the
91 number of ones in the binary expansion of a given integer, also known
92 as the population count. (Contributed by Niklas Fiekas in :issue:`29882`.)
Pablo Galindod4fe0982020-05-19 03:33:01 +010093
Dennis Sweeney3ee0e482020-06-12 13:19:25 -040094* The views returned by :meth:`dict.keys`, :meth:`dict.values` and
95 :meth:`dict.items` now all have a ``mapping`` attribute that gives a
96 :class:`types.MappingProxyType` object wrapping the original
97 dictionary. (Contributed by Dennis Sweeney in :issue:`40890`.)
98
Ram Rachum59cf8532020-06-19 23:39:22 +030099* :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used
100 to require that all the iterables have an equal length.
101
Mikhail Golubev4f3c2502020-10-08 00:44:31 +0300102PEP 613: TypeAlias Annotation
103-----------------------------
104
105:pep:`484` introduced the concept of type aliases, only requiring them to be
106top-level unannotated assignments. This simplicity sometimes made it difficult
107for type checkers to distinguish between type aliases and ordinary assignments,
108especially when forward references or invalid types were involved. Compare::
109
110 StrCache = 'Cache[str]' # a type alias
111 LOG_PREFIX = 'LOG[DEBUG]' # a module constant
112
113Now the :mod:`typing` module has a special annotation :data:`TypeAlias` to
114declare type aliases more explicitly::
115
116 StrCache: TypeAlias = 'Cache[str]' # a type alias
117 LOG_PREFIX = 'LOG[DEBUG]' # a module constant
118
119See :pep:`613` for more details.
120
121(Contributed by Mikhail Golubev in :issue:`41923`.)
122
123PEP604: New Type Union Operator
124-------------------------------
Fidget-Spinner8e1dd552020-10-05 12:40:52 +0800125
126A new type union operator was introduced which enables the syntax ``X | Y``.
127This provides a cleaner way of expressing 'either type X or type Y' instead of
128using :data:`typing.Union`, especially in type hints (annotations).
129
130In previous versions of Python, to apply a type hint for functions accepting
131arguments of multiple types, :data:`typing.Union` was used::
132
133 def square(number: Union[int, float]) -> Union[int, float]:
134 return number ** 2
135
136
137Now, type hints can be written in a more succinct manner::
138
139 def square(number: int | float) -> int | float:
140 return number ** 2
141
142
143See :pep:`604` for more details.
144
145(Contributed by Maggie Moss and Philippe Prados in :issue:`41428`.)
Pablo Galindod4fe0982020-05-19 03:33:01 +0100146
147Other Language Changes
148======================
149
Serhiy Storchaka578c3952020-05-26 18:43:38 +0300150* Builtin and extension functions that take integer arguments no longer accept
151 :class:`~decimal.Decimal`\ s, :class:`~fractions.Fraction`\ s and other
152 objects that can be converted to integers only with a loss (e.g. that have
153 the :meth:`~object.__int__` method but do not have the
154 :meth:`~object.__index__` method).
155 (Contributed by Serhiy Storchaka in :issue:`37999`.)
Pablo Galindod4fe0982020-05-19 03:33:01 +0100156
157
158New Modules
159===========
160
161* None yet.
162
163
164Improved Modules
165================
166
Filipe LaĆ­ns4ce6faa2020-08-10 15:48:20 +0100167base64
168------
169
170Add :func:`base64.b32hexencode` and :func:`base64.b32hexdecode` to support the
171Base32 Encoding with Extended Hex Alphabet.
172
Hai Shid332e7b2020-09-29 05:41:11 +0800173codecs
174------
175
176Add a :func:`codecs.unregister` function to unregister a codec search function.
177(Contributed by Hai Shi in :issue:`41842`.)
178
Hans Petter Janssonda4e09f2020-08-03 22:51:33 -0500179curses
180------
181
182The extended color functions added in ncurses 6.1 will be used transparently
183by :func:`curses.color_content`, :func:`curses.init_color`,
184:func:`curses.init_pair`, and :func:`curses.pair_content`. A new function,
185:func:`curses.has_extended_color_support`, indicates whether extended color
186support is provided by the underlying ncurses library.
187(Contributed by Jeffrey Kintscher and Hans Petter Jansson in :issue:`36982`.)
188
Hai Shic5b049b2020-10-14 23:43:31 +0800189encodings
190---------
191:func:`encodings.normalize_encoding` now ignores non-ASCII characters.
192(Contributed by Hai Shi in :issue:`39337`.)
193
Serhiy Storchaka8a64cea2020-06-18 22:08:27 +0300194glob
195----
196
197Added the *root_dir* and *dir_fd* parameters in :func:`~glob.glob` and
198:func:`~glob.iglob` which allow to specify the root directory for searching.
199(Contributed by Serhiy Storchaka in :issue:`38144`.)
200
pxinwr3405e052020-08-07 13:21:52 +0800201os
202--
203
204Added :func:`os.cpu_count()` support for VxWorks RTOS.
205(Contributed by Peixing Xin in :issue:`41440`.)
206
Gregory Schevchenkodaff3902020-07-25 22:58:45 +0300207py_compile
208----------
209
210Added ``--quiet`` option to command-line interface of :mod:`py_compile`.
211(Contributed by Gregory Schevchenko in :issue:`38731`.)
212
Victor Stinnerdd8a93e2020-06-30 00:49:03 +0200213sys
214---
215
216Add :data:`sys.orig_argv` attribute: the list of the original command line
217arguments passed to the Python executable.
218(Contributed by Victor Stinner in :issue:`23427`.)
219
Bas van Beek0d0e9fe2020-09-22 17:55:34 +0200220types
221-----
222
223Reintroduced the :data:`types.EllipsisType`, :data:`types.NoneType`
224and :data:`types.NotImplementedType` classes, providing a new set
225of types readily interpretable by type checkers.
226(Contributed by Bas van Beek in :issue:`41810`.)
227
Mark Dickinsonc8c70e72020-09-19 21:38:11 +0100228unittest
229--------
230
231Add new method :meth:`~unittest.TestCase.assertNoLogs` to complement the
232existing :meth:`~unittest.TestCase.assertLogs`. (Contributed by Kit Yan Choi
233in :issue:`39385`.)
234
Zackery Spytze28b8c92020-08-09 04:50:53 -0600235xml
236---
237
238Add a :class:`~xml.sax.handler.LexicalHandler` class to the
239:mod:`xml.sax.handler` module.
240(Contributed by Jonathan Gossage and Zackery Spytz in :issue:`35018`.)
241
Serhiy Storchaka8a64cea2020-06-18 22:08:27 +0300242
Pablo Galindod4fe0982020-05-19 03:33:01 +0100243Optimizations
244=============
245
Serhiy Storchaka12f43342020-07-20 15:53:55 +0300246* Constructors :func:`str`, :func:`bytes` and :func:`bytearray` are now faster
247 (around 30--40% for small objects).
248 (Contributed by Serhiy Storchaka in :issue:`41334`.)
249
Victor Stinner2c2a4f32020-06-18 01:20:51 +0200250* The :mod:`runpy` module now imports fewer modules.
Victor Stinner4c18fc82020-06-17 23:58:58 +0200251 The ``python3 -m module-name`` command startup time is 1.3x faster in
252 average.
253 (Contributed by Victor Stinner in :issue:`41006`.)
254
Pablo Galindo109826c2020-10-20 06:22:44 +0100255* The ``LOAD_ATTR`` instruction now uses new "per opcode cache" mechanism.
256 It is about 36% faster now. (Contributed by Pablo Galindo and Yury Selivanov
257 in :issue:`42093`.)
Pablo Galindod4fe0982020-05-19 03:33:01 +0100258
Pablo Galindob451b0e2020-10-21 22:46:52 +0100259* When building Python with ``--enable-optimizations`` now
260 ``-fno-semantic-interposition`` is added to both the compile and link line.
261 This speeds builds of the Python interpreter created with ``--enable-shared``
262 with ``gcc`` by up to 30%. See `this article
263 <https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/>`_
264 for more details. (Contributed by Victor Stinner and Pablo Galindo in
265 :issue:`38980`)
266
Pablo Galindod4fe0982020-05-19 03:33:01 +0100267Deprecated
268==========
269
270
Pablo Galindod4fe0982020-05-19 03:33:01 +0100271Removed
272=======
273
Serhiy Storchakae2ec0b22020-10-09 14:14:37 +0300274* Removed special methods ``__int__``, ``__float__``, ``__floordiv__``,
275 ``__mod__``, ``__divmod__``, ``__rfloordiv__``, ``__rmod__`` and
276 ``__rdivmod__`` of the :class:`complex` class. They always raised
277 a :exc:`TypeError`.
278 (Contributed by Serhiy Storchaka in :issue:`41974`.)
279
Berker Peksagd4d127f2020-07-16 09:38:58 +0300280* The ``ParserBase.error()`` method from the private and undocumented ``_markupbase``
281 module has been removed. :class:`html.parser.HTMLParser` is the only subclass of
282 ``ParserBase`` and its ``error()`` implementation has already been removed in
283 Python 3.5.
284 (Contributed by Berker Peksag in :issue:`31844`.)
285
Pablo Galindod4fe0982020-05-19 03:33:01 +0100286
Pablo Galindod4fe0982020-05-19 03:33:01 +0100287Porting to Python 3.10
288======================
289
290This section lists previously described changes and other bugfixes
291that may require changes to your code.
292
293
Dong-hee Naad3252b2020-05-26 01:52:54 +0900294
295Build Changes
296=============
297
Erlend Egeberg Aasland207c3212020-09-07 23:26:54 +0200298
Victor Stinner7ab92d52020-06-16 00:54:44 +0200299* The C99 functions :c:func:`snprintf` and :c:func:`vsnprintf` are now required
300 to build Python.
301 (Contributed by Victor Stinner in :issue:`36020`.)
302
Erlend Egeberg Aasland207c3212020-09-07 23:26:54 +0200303* :mod:`sqlite3` requires SQLite 3.7.3 or higher.
304 (Contributed by Sergey Fedoseev and Erlend E. Aasland :issue:`40744`.)
305
306
Dong-hee Naad3252b2020-05-26 01:52:54 +0900307
308C API Changes
309=============
310
311New Features
312------------
313
Victor Stinnerdd8a93e2020-06-30 00:49:03 +0200314* The result of :c:func:`PyNumber_Index` now always has exact type :class:`int`.
Serhiy Storchaka5f4b229d2020-05-28 10:33:45 +0300315 Previously, the result could have been an instance of a subclass of ``int``.
316 (Contributed by Serhiy Storchaka in :issue:`40792`.)
317
Victor Stinnerdd8a93e2020-06-30 00:49:03 +0200318* Add a new :c:member:`~PyConfig.orig_argv` member to the :c:type:`PyConfig`
319 structure: the list of the original command line arguments passed to the
320 Python executable.
321 (Contributed by Victor Stinner in :issue:`23427`.)
Dong-hee Naad3252b2020-05-26 01:52:54 +0900322
Zackery Spytz2e4dd332020-09-23 12:43:45 -0600323* The :c:func:`PyDateTime_DATE_GET_TZINFO` and
324 :c:func:`PyDateTime_TIME_GET_TZINFO` macros have been added for accessing
325 the ``tzinfo`` attributes of :class:`datetime.datetime` and
326 :class:`datetime.time` objects.
327 (Contributed by Zackery Spytz in :issue:`30155`.)
328
Hai Shid332e7b2020-09-29 05:41:11 +0800329* Add a :c:func:`PyCodec_Unregister` function to unregister a codec
330 search function.
331 (Contributed by Hai Shi in :issue:`41842`.)
332
Vladimir Matveev24a54c02020-10-12 12:10:42 -0700333* The :c:func:`PyIter_Send` function was added to allow
Vladimir Matveev037245c2020-10-09 17:15:15 -0700334 sending value into iterator without raising ``StopIteration`` exception.
335 (Contributed by Vladimir Matveev in :issue:`41756`.)
336
Alex Gaynor3a8fdb22020-10-19 18:17:50 -0400337* Added :c:func:`PyUnicode_AsUTF8AndSize` to the limited C API.
338 (Contributed by Alex Gaynor in :issue:`41784`.)
339
340
Dong-hee Naad3252b2020-05-26 01:52:54 +0900341Porting to Python 3.10
342----------------------
343
Victor Stinner37bb2892020-06-19 11:45:31 +0200344* The ``PY_SSIZE_T_CLEAN`` macro must now be defined to use
345 :c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` formats which use
346 ``#``: ``es#``, ``et#``, ``s#``, ``u#``, ``y#``, ``z#``, ``U#`` and ``Z#``.
347 See :ref:`Parsing arguments and building values
348 <arg-parsing>` and the :pep:`353`.
349 (Contributed by Victor Stinner in :issue:`40943`.)
350
Dong-hee Naad3252b2020-05-26 01:52:54 +0900351* Since :c:func:`Py_TYPE()` is changed to the inline static function,
352 ``Py_TYPE(obj) = new_type`` must be replaced with ``Py_SET_TYPE(obj, new_type)``:
Victor Stinnerdc24b8a2020-06-04 22:10:43 +0200353 see :c:func:`Py_SET_TYPE()` (available since Python 3.9). For backward
354 compatibility, this macro can be used::
355
356 #if PY_VERSION_HEX < 0x030900A4
357 # define Py_SET_TYPE(obj, type) ((Py_TYPE(obj) = (type)), (void)0)
358 #endif
359
Dong-hee Naad3252b2020-05-26 01:52:54 +0900360 (Contributed by Dong-hee Na in :issue:`39573`.)
361
Victor Stinnerfe2978b2020-05-27 14:55:10 +0200362* Since :c:func:`Py_REFCNT()` is changed to the inline static function,
363 ``Py_REFCNT(obj) = new_refcnt`` must be replaced with ``Py_SET_REFCNT(obj, new_refcnt)``:
Victor Stinnerdc24b8a2020-06-04 22:10:43 +0200364 see :c:func:`Py_SET_REFCNT()` (available since Python 3.9). For backward
365 compatibility, this macro can be used::
366
367 #if PY_VERSION_HEX < 0x030900A4
368 # define Py_SET_REFCNT(obj, refcnt) ((Py_REFCNT(obj) = (refcnt)), (void)0)
369 #endif
370
Victor Stinnerfe2978b2020-05-27 14:55:10 +0200371 (Contributed by Victor Stinner in :issue:`39573`.)
372
373* Since :c:func:`Py_SIZE()` is changed to the inline static function,
374 ``Py_SIZE(obj) = new_size`` must be replaced with ``Py_SET_SIZE(obj, new_size)``:
Victor Stinnerdc24b8a2020-06-04 22:10:43 +0200375 see :c:func:`Py_SET_SIZE()` (available since Python 3.9). For backward
376 compatibility, this macro can be used::
377
378 #if PY_VERSION_HEX < 0x030900A4
379 # define Py_SET_SIZE(obj, size) ((Py_SIZE(obj) = (size)), (void)0)
380 #endif
381
Victor Stinnerfe2978b2020-05-27 14:55:10 +0200382 (Contributed by Victor Stinner in :issue:`39573`.)
Dong-hee Naad3252b2020-05-26 01:52:54 +0900383
Victor Stinner59d3dce2020-06-02 14:03:25 +0200384* Calling :c:func:`PyDict_GetItem` without :term:`GIL` held had been allowed
385 for historical reason. It is no longer allowed.
386 (Contributed by Victor Stinner in :issue:`40839`.)
387
Inada Naoki038dd0f2020-06-30 15:26:56 +0900388* ``PyUnicode_FromUnicode(NULL, size)`` and ``PyUnicode_FromStringAndSize(NULL, size)``
389 raise ``DeprecationWarning`` now. Use :c:func:`PyUnicode_New` to allocate
390 Unicode object without initial data.
391 (Contributed by Inada Naoki in :issue:`36346`.)
392
Victor Stinner583ee5a2020-10-02 14:49:00 +0200393Deprecated
394----------
395
396* The ``PyUnicode_InternImmortal()`` function is now deprecated
397 and will be removed in Python 3.12: use :c:func:`PyUnicode_InternInPlace`
398 instead.
399 (Contributed by Victor Stinner in :issue:`41692`.)
400
Dong-hee Naad3252b2020-05-26 01:52:54 +0900401Removed
402-------
Inada Naoki6f8a6ee2020-06-26 08:07:22 +0900403
404* ``PyObject_AsCharBuffer()``, ``PyObject_AsReadBuffer()``, ``PyObject_CheckReadBuffer()``,
405 and ``PyObject_AsWriteBuffer()`` are removed. Please migrate to new buffer protocol;
406 :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release`.
Inada Naoki20a79022020-06-27 18:22:09 +0900407 (Contributed by Inada Naoki in :issue:`41103`.)
408
409* Removed ``Py_UNICODE_str*`` functions manipulating ``Py_UNICODE*`` strings.
410 (Contributed by Inada Naoki in :issue:`41123`.)
411
412 * ``Py_UNICODE_strlen``: use :c:func:`PyUnicode_GetLength` or
413 :c:macro:`PyUnicode_GET_LENGTH`
414 * ``Py_UNICODE_strcat``: use :c:func:`PyUnicode_CopyCharacters` or
415 :c:func:`PyUnicode_FromFormat`
416 * ``Py_UNICODE_strcpy``, ``Py_UNICODE_strncpy``: use
417 :c:func:`PyUnicode_CopyCharacters` or :c:func:`PyUnicode_Substring`
418 * ``Py_UNICODE_strcmp``: use :c:func:`PyUnicode_Compare`
419 * ``Py_UNICODE_strncmp``: use :c:func:`PyUnicode_Tailmatch`
420 * ``Py_UNICODE_strchr``, ``Py_UNICODE_strrchr``: use
421 :c:func:`PyUnicode_FindChar`
Inada Naokid9f2a132020-06-29 10:46:51 +0900422
423* Removed ``PyUnicode_GetMax()``. Please migrate to new (:pep:`393`) APIs.
424 (Contributed by Inada Naoki in :issue:`41103`.)
Inada Naokie4f1fe62020-06-29 13:00:43 +0900425
426* Removed ``PyLong_FromUnicode()``. Please migrate to :c:func:`PyLong_FromUnicodeObject`.
427 (Contributed by Inada Naoki in :issue:`41103`.)
Inada Naokib3332662020-06-30 12:23:07 +0900428
429* Removed ``PyUnicode_AsUnicodeCopy()``. Please use :c:func:`PyUnicode_AsUCS4Copy` or
430 :c:func:`PyUnicode_AsWideCharString`
431 (Contributed by Inada Naoki in :issue:`41103`.)
Victor Stinner19c3ac92020-09-23 14:04:57 +0200432
433* Removed ``_Py_CheckRecursionLimit`` variable: it has been replaced by
434 ``ceval.recursion_limit`` of the :c:type:`PyInterpreterState` structure.
435 (Contributed by Victor Stinner in :issue:`41834`.)
Serhiy Storchakadcc54212020-10-05 12:32:00 +0300436
437* Removed undocumented macros ``Py_ALLOW_RECURSION`` and
438 ``Py_END_ALLOW_RECURSION`` and the ``recursion_critical`` field of the
439 :c:type:`PyInterpreterState` structure.
440 (Contributed by Serhiy Storchaka in :issue:`41936`.)