1 2**************************** 3 What's New In Python 3.13 4**************************** 5 6:Editors: Adam Turner and Thomas Wouters 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 issue number as a comment: 40 41 XXX Describe the transmogrify() function added to the socket 42 module. 43 (Contributed by P.Y. Developer in :gh:`12345`.) 44 45 This saves the maintainer the effort of going through the VCS log 46 when researching a change. 47 48This article explains the new features in Python 3.13, compared to 3.12. 49Python 3.13 was released on October 7, 2024. 50For full details, see the :ref:`changelog <changelog>`. 51 52.. seealso:: 53 54 :pep:`719` -- Python 3.13 Release Schedule 55 56 57Summary -- Release Highlights 58============================= 59 60.. This section singles out the most important changes in Python 3.13. 61 Brevity is key. 62 63Python 3.13 is the latest stable release of the Python programming 64language, with a mix of changes to the language, the implementation 65and the standard library. 66The biggest changes include a new `interactive interpreter 67<whatsnew313-better-interactive-interpreter_>`_, 68experimental support for running in a `free-threaded mode 69<whatsnew313-free-threaded-cpython_>`_ (:pep:`703`), 70and a `Just-In-Time compiler <whatsnew313-jit-compiler_>`_ (:pep:`744`). 71 72Error messages continue to improve, with tracebacks now highlighted in color 73by default. The :func:`locals` builtin now has :ref:`defined semantics 74<whatsnew313-locals-semantics>` for changing the returned mapping, 75and type parameters now support default values. 76 77The library changes contain removal of deprecated APIs and modules, 78as well as the usual improvements in user-friendliness and correctness. 79Several legacy standard library modules have now `been removed 80<whatsnew313-pep594_>`_ following their deprecation in Python 3.11 (:pep:`594`). 81 82This article doesn't attempt to provide a complete specification 83of all new features, but instead gives a convenient overview. 84For full details refer to the documentation, 85such as the :ref:`Library Reference <library-index>` 86and :ref:`Language Reference <reference-index>`. 87To understand the complete implementation and design rationale for a change, 88refer to the PEP for a particular new feature; 89but note that PEPs usually are not kept up-to-date 90once a feature has been fully implemented. 91See `Porting to Python 3.13`_ for guidance on upgrading from 92earlier versions of Python. 93 94-------------- 95 96.. PEP-sized items next. 97 98Interpreter improvements: 99 100* A greatly improved :ref:`interactive interpreter 101 <whatsnew313-better-interactive-interpreter>` and 102 :ref:`improved error messages <whatsnew313-improved-error-messages>`. 103* :pep:`667`: The :func:`locals` builtin now has 104 :ref:`defined semantics <whatsnew313-locals-semantics>` when mutating the 105 returned mapping. Python debuggers and similar tools may now more reliably 106 update local variables in optimized scopes even during concurrent code 107 execution. 108* :pep:`703`: CPython 3.13 has experimental support for running with the 109 :term:`global interpreter lock` disabled. See :ref:`Free-threaded CPython 110 <whatsnew313-free-threaded-cpython>` for more details. 111* :pep:`744`: A basic :ref:`JIT compiler <whatsnew313-jit-compiler>` was added. 112 It is currently disabled by default (though we may turn it on later). 113 Performance improvements are modest -- we expect to improve this 114 over the next few releases. 115* Color support in the new :ref:`interactive interpreter 116 <whatsnew313-better-interactive-interpreter>`, 117 as well as in :ref:`tracebacks <whatsnew313-improved-error-messages>` 118 and :ref:`doctest <whatsnew313-doctest>` output. 119 This can be disabled through the :envvar:`PYTHON_COLORS` and |NO_COLOR|_ 120 environment variables. 121 122Python data model improvements: 123 124* :attr:`~type.__static_attributes__` stores the names of attributes accessed 125 through ``self.X`` in any function in a class body. 126* :attr:`~type.__firstlineno__` records the first line number of a class 127 definition. 128 129Significant improvements in the standard library: 130 131* Add a new :exc:`PythonFinalizationError` exception, raised when an operation 132 is blocked during :term:`finalization <interpreter shutdown>`. 133* The :mod:`argparse` module now supports deprecating command-line options, 134 positional arguments, and subcommands. 135* The new functions :func:`base64.z85encode` and :func:`base64.z85decode` 136 support encoding and decoding `Z85 data`_. 137* The :mod:`copy` module now has a :func:`copy.replace` function, 138 with support for many builtin types and any class defining 139 the :func:`~object.__replace__` method. 140* The new :mod:`dbm.sqlite3` module is now the default :mod:`dbm` backend. 141* The :mod:`os` module has a :ref:`suite of new functions <os-timerfd>` 142 for working with Linux's timer notification file descriptors. 143* The :mod:`random` module now has a :ref:`command-line interface <random-cli>`. 144 145Security improvements: 146 147* :func:`ssl.create_default_context` sets :data:`ssl.VERIFY_X509_PARTIAL_CHAIN` 148 and :data:`ssl.VERIFY_X509_STRICT` as default flags. 149 150C API improvements: 151 152* The :c:data:`Py_mod_gil` slot is now used to indicate that 153 an extension module supports running with the :term:`GIL` disabled. 154* The :doc:`PyTime C API </c-api/time>` has been added, 155 providing access to system clocks. 156* :c:type:`PyMutex` is a new lightweight mutex that occupies a single byte. 157* There is a new :ref:`suite of functions <c-api-monitoring>` 158 for generating :pep:`669` monitoring events in the C API. 159 160New typing features: 161 162* :pep:`696`: Type parameters (:data:`typing.TypeVar`, :data:`typing.ParamSpec`, 163 and :data:`typing.TypeVarTuple`) now support defaults. 164* :pep:`702`: The new :func:`warnings.deprecated` decorator adds support 165 for marking deprecations in the type system and at runtime. 166* :pep:`705`: :data:`typing.ReadOnly` can be used to mark an item of a 167 :class:`typing.TypedDict` as read-only for type checkers. 168* :pep:`742`: :data:`typing.TypeIs` provides more intuitive 169 type narrowing behavior, as an alternative to :data:`typing.TypeGuard`. 170 171Platform support: 172 173* :pep:`730`: Apple's iOS is now an :ref:`officially supported platform 174 <whatsnew313-platform-support>`, at :pep:`tier 3 <11#tier-3>`. 175* :pep:`738`: Android is now an :ref:`officially supported platform 176 <whatsnew313-platform-support>`, at :pep:`tier 3 <11#tier-3>`. 177* ``wasm32-wasi`` is now supported as a :pep:`tier 2 <11#tier-2>` platform. 178* ``wasm32-emscripten`` is no longer an officially supported platform. 179 180Important removals: 181 182* :ref:`PEP 594 <whatsnew313-pep594>`: The remaining 19 "dead batteries" 183 (legacy stdlib modules) have been removed from the standard library: 184 :mod:`!aifc`, :mod:`!audioop`, :mod:`!cgi`, :mod:`!cgitb`, :mod:`!chunk`, 185 :mod:`!crypt`, :mod:`!imghdr`, :mod:`!mailcap`, :mod:`!msilib`, :mod:`!nis`, 186 :mod:`!nntplib`, :mod:`!ossaudiodev`, :mod:`!pipes`, :mod:`!sndhdr`, 187 :mod:`!spwd`, :mod:`!sunau`, :mod:`!telnetlib`, :mod:`!uu` and :mod:`!xdrlib`. 188* Remove the :program:`2to3` tool and :mod:`!lib2to3` module 189 (deprecated in Python 3.11). 190* Remove the :mod:`!tkinter.tix` module (deprecated in Python 3.6). 191* Remove the :func:`!locale.resetlocale` function. 192* Remove the :mod:`!typing.io` and :mod:`!typing.re` namespaces. 193* Remove chained :class:`classmethod` descriptors. 194 195Release schedule changes: 196 197:pep:`602` ("Annual Release Cycle for Python") has been updated 198to extend the full support ('bugfix') period for new releases to two years. 199This updated policy means that: 200 201* Python 3.9--3.12 have one and a half years of full support, 202 followed by three and a half years of security fixes. 203* Python 3.13 and later have two years of full support, 204 followed by three years of security fixes. 205 206 207New Features 208============ 209 210 211.. _whatsnew313-better-interactive-interpreter: 212 213A better interactive interpreter 214-------------------------------- 215 216Python now uses a new :term:`interactive` shell by default, based on code 217from the `PyPy project`_. 218When the user starts the :term:`REPL` from an interactive terminal, 219the following new features are now supported: 220 221* Multiline editing with history preservation. 222* Direct support for REPL-specific commands like :kbd:`help`, :kbd:`exit`, 223 and :kbd:`quit`, without the need to call them as functions. 224* Prompts and tracebacks with :ref:`color enabled by default 225 <using-on-controlling-color>`. 226* Interactive help browsing using :kbd:`F1` with a separate command 227 history. 228* History browsing using :kbd:`F2` that skips output as well as the 229 :term:`>>>` and :term:`...` prompts. 230* "Paste mode" with :kbd:`F3` that makes pasting larger blocks of code 231 easier (press :kbd:`F3` again to return to the regular prompt). 232 233To disable the new interactive shell, 234set the :envvar:`PYTHON_BASIC_REPL` environment variable. 235For more on interactive mode, see :ref:`tut-interac`. 236 237(Contributed by Pablo Galindo Salgado, Łukasz Langa, and 238Lysandros Nikolaou in :gh:`111201` based on code from the PyPy project. 239Windows support contributed by Dino Viehland and Anthony Shaw.) 240 241.. _`PyPy project`: https://pypy.org/ 242 243 244.. _whatsnew313-improved-error-messages: 245 246Improved error messages 247----------------------- 248 249* The interpreter now uses color by default when displaying tracebacks in the 250 terminal. This feature :ref:`can be controlled <using-on-controlling-color>` 251 via the new :envvar:`PYTHON_COLORS` environment variable as well as 252 the canonical |NO_COLOR|_ and |FORCE_COLOR|_ environment variables. 253 (Contributed by Pablo Galindo Salgado in :gh:`112730`.) 254 255.. Apparently this how you hack together a formatted link: 256 (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text) 257 258.. |FORCE_COLOR| replace:: ``FORCE_COLOR`` 259.. _FORCE_COLOR: https://force-color.org/ 260 261.. |NO_COLOR| replace:: ``NO_COLOR`` 262.. _NO_COLOR: https://no-color.org/ 263 264* A common mistake is to write a script with the same name as a 265 standard library module. When this results in errors, we now 266 display a more helpful error message: 267 268 .. code-block:: pytb 269 270 $ python random.py 271 Traceback (most recent call last): 272 File "/home/me/random.py", line 1, in <module> 273 import random 274 File "/home/me/random.py", line 3, in <module> 275 print(random.randint(5)) 276 ^^^^^^^^^^^^^^ 277 AttributeError: module 'random' has no attribute 'randint' (consider renaming '/home/me/random.py' since it has the same name as the standard library module named 'random' and prevents importing that standard library module) 278 279 Similarly, if a script has the same name as a third-party 280 module that it attempts to import and this results in errors, 281 we also display a more helpful error message: 282 283 .. code-block:: pytb 284 285 $ python numpy.py 286 Traceback (most recent call last): 287 File "/home/me/numpy.py", line 1, in <module> 288 import numpy as np 289 File "/home/me/numpy.py", line 3, in <module> 290 np.array([1, 2, 3]) 291 ^^^^^^^^ 292 AttributeError: module 'numpy' has no attribute 'array' (consider renaming '/home/me/numpy.py' if it has the same name as a library you intended to import) 293 294 (Contributed by Shantanu Jain in :gh:`95754`.) 295 296* The error message now tries to suggest the correct keyword argument 297 when an incorrect keyword argument is passed to a function. 298 299 .. code-block:: pycon 300 301 >>> "Better error messages!".split(max_split=1) 302 Traceback (most recent call last): 303 File "<python-input-0>", line 1, in <module> 304 "Better error messages!".split(max_split=1) 305 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^ 306 TypeError: split() got an unexpected keyword argument 'max_split'. Did you mean 'maxsplit'? 307 308 (Contributed by Pablo Galindo Salgado and Shantanu Jain in :gh:`107944`.) 309 310 311.. _whatsnew313-free-threaded-cpython: 312 313Free-threaded CPython 314--------------------- 315 316CPython now has experimental support for running in a free-threaded mode, 317with the :term:`global interpreter lock` (GIL) disabled. 318This is an experimental feature and therefore is not enabled by default. 319The free-threaded mode requires a different executable, 320usually called ``python3.13t`` or ``python3.13t.exe``. 321Pre-built binaries marked as *free-threaded* can be installed as part of 322the official :ref:`Windows <install-freethreaded-windows>` 323and :ref:`macOS <install-freethreaded-macos>` installers, 324or CPython can be built from source with the :option:`--disable-gil` option. 325 326Free-threaded execution allows for full utilization of the available 327processing power by running threads in parallel on available CPU cores. 328While not all software will benefit from this automatically, programs 329designed with threading in mind will run faster on multi-core hardware. 330**The free-threaded mode is experimental** and work is ongoing to improve it: 331expect some bugs and a substantial single-threaded performance hit. 332Free-threaded builds of CPython support optionally running with the GIL 333enabled at runtime using the environment variable :envvar:`PYTHON_GIL` or 334the command-line option :option:`-X gil=1`. 335 336To check if the current interpreter supports free-threading, :option:`python -VV <-V>` 337and :attr:`sys.version` contain "experimental free-threading build". 338The new :func:`!sys._is_gil_enabled` function can be used to check whether 339the GIL is actually disabled in the running process. 340 341C-API extension modules need to be built specifically for the free-threaded 342build. Extensions that support running with the :term:`GIL` disabled should 343use the :c:data:`Py_mod_gil` slot. Extensions using single-phase init should 344use :c:func:`PyUnstable_Module_SetGIL` to indicate whether they support 345running with the GIL disabled. Importing C extensions that don't use these 346mechanisms will cause the GIL to be enabled, unless the GIL was explicitly 347disabled with the :envvar:`PYTHON_GIL` environment variable or the 348:option:`-X gil=0` option. 349pip 24.1 or newer is required to install packages with C extensions in the 350free-threaded build. 351 352This work was made possible thanks to many individuals and 353organizations, including the large community of contributors to Python 354and third-party projects to test and enable free-threading support. 355Notable contributors include: 356Sam Gross, Ken Jin, Donghee Na, Itamar Oren, Matt Page, Brett Simmers, 357Dino Viehland, Carl Meyer, Nathan Goldbaum, Ralf Gommers, 358Lysandros Nikolaou, and many others. 359Many of these contributors are employed by Meta, which has 360provided significant engineering resources to support this project. 361 362.. seealso:: 363 364 :pep:`703` "Making the Global Interpreter Lock Optional in CPython" 365 contains rationale and information surrounding this work. 366 367 `Porting Extension Modules to Support Free-Threading 368 <https://py-free-threading.github.io/porting/>`_: A community-maintained 369 porting guide for extension authors. 370 371 372.. _whatsnew313-jit-compiler: 373 374An experimental just-in-time (JIT) compiler 375------------------------------------------- 376 377When CPython is configured and built using 378the :option:`!--enable-experimental-jit` option, 379a just-in-time (JIT) compiler is added which may speed up some Python programs. 380On Windows, use ``PCbuild/build.bat --experimental-jit`` to enable the JIT 381or ``--experimental-jit-interpreter`` to enable the Tier 2 interpreter. 382Build requirements and further supporting information `are contained at`__ 383:file:`Tools/jit/README.md`. 384 385__ https://github.com/python/cpython/blob/main/Tools/jit/README.md 386 387The :option:`!--enable-experimental-jit` option takes these (optional) values, 388defaulting to ``yes`` if :option:`!--enable-experimental-jit` is present 389without the optional value. 390 391* ``no``: Disable the entire Tier 2 and JIT pipeline. 392* ``yes``: Enable the JIT. 393 To disable the JIT at runtime, pass the environment variable ``PYTHON_JIT=0``. 394* ``yes-off``: Build the JIT but disable it by default. 395 To enable the JIT at runtime, pass the environment variable ``PYTHON_JIT=1``. 396* ``interpreter``: Enable the Tier 2 interpreter but disable the JIT. 397 The interpreter can be disabled by running with ``PYTHON_JIT=0``. 398 399The internal architecture is roughly as follows: 400 401* We start with specialized *Tier 1 bytecode*. 402 See :ref:`What's new in 3.11 <whatsnew311-pep659>` for details. 403* When the Tier 1 bytecode gets hot enough, it gets translated 404 to a new purely internal intermediate representation (IR), 405 called the *Tier 2 IR*, and sometimes referred to as micro-ops ("uops"). 406* The Tier 2 IR uses the same stack-based virtual machine as Tier 1, 407 but the instruction format is better suited to translation to machine code. 408* We have several optimization passes for Tier 2 IR, which are applied 409 before it is interpreted or translated to machine code. 410* There is a Tier 2 interpreter, but it is mostly intended for debugging 411 the earlier stages of the optimization pipeline. 412 The Tier 2 interpreter can be enabled by configuring Python 413 with ``--enable-experimental-jit=interpreter``. 414* When the JIT is enabled, the optimized 415 Tier 2 IR is translated to machine code, which is then executed. 416* The machine code translation process uses a technique called 417 *copy-and-patch*. It has no runtime dependencies, but there is a new 418 build-time dependency on LLVM. 419 420.. seealso:: :pep:`744` 421 422(JIT by Brandt Bucher, inspired by a paper by Haoran Xu and Fredrik Kjolstad. 423Tier 2 IR by Mark Shannon and Guido van Rossum. 424Tier 2 optimizer by Ken Jin.) 425 426 427.. _whatsnew313-locals-semantics: 428 429Defined mutation semantics for :py:func:`locals` 430------------------------------------------------ 431 432Historically, the expected result of mutating the return value of 433:func:`locals` has been left to individual Python implementations to define. 434Starting from Python 3.13, :pep:`667` standardises 435the historical behavior of CPython for most code execution scopes, 436but changes :term:`optimized scopes <optimized scope>` 437(functions, generators, coroutines, comprehensions, and generator expressions) 438to explicitly return independent snapshots of the currently assigned local 439variables, including locally referenced nonlocal variables captured in closures. 440 441This change to the semantics of :func:`locals` in optimized scopes also 442affects the default behavior of code execution functions that implicitly 443target :func:`!locals` if no explicit namespace is provided 444(such as :func:`exec` and :func:`eval`). 445In previous versions, whether or not changes could be accessed by calling 446:func:`!locals` after calling the code execution function was 447implementation-dependent. In CPython specifically, such code would typically 448appear to work as desired, but could sometimes fail in optimized scopes based 449on other code (including debuggers and code execution tracing tools) 450potentially resetting the shared snapshot in that scope. 451Now, the code will always run against an independent snapshot of 452the local variables in optimized scopes, and hence the changes will never 453be visible in subsequent calls to :func:`!locals`. 454To access the changes made in these cases, an explicit namespace reference 455must now be passed to the relevant function. 456Alternatively, it may make sense to update affected code to use a higher level 457code execution API that returns the resulting code execution namespace 458(e.g. :func:`runpy.run_path` when executing Python files from disk). 459 460To ensure debuggers and similar tools can reliably update local variables in 461scopes affected by this change, :attr:`FrameType.f_locals <frame.f_locals>` now 462returns a write-through proxy to the frame's local and locally referenced 463nonlocal variables in these scopes, rather than returning an inconsistently 464updated shared ``dict`` instance with undefined runtime semantics. 465 466See :pep:`667` for more details, including related C API changes 467and deprecations. Porting notes are also provided below for the affected 468:ref:`Python APIs <pep667-porting-notes-py>` and :ref:`C APIs 469<pep667-porting-notes-c>`. 470 471(PEP and implementation contributed by Mark Shannon and Tian Gao in 472:gh:`74929`. Documentation updates provided by Guido van Rossum and 473Alyssa Coghlan.) 474 475 476.. _whatsnew313-platform-support: 477 478Support for mobile platforms 479---------------------------- 480 481:pep:`730`: iOS is now a :pep:`11` supported platform, with the 482``arm64-apple-ios`` and ``arm64-apple-ios-simulator`` targets at tier 3 483(iPhone and iPad devices released after 2013 and the Xcode iOS simulator 484running on Apple silicon hardware, respectively). 485``x86_64-apple-ios-simulator`` 486(the Xcode iOS simulator running on older ``x86_64`` hardware) 487is not a tier 3 supported platform, but will have best-effort support. 488(PEP written and implementation contributed by Russell Keith-Magee in 489:gh:`114099`.) 490 491:pep:`738`: Android is now a :pep:`11` supported platform, with the 492``aarch64-linux-android`` and ``x86_64-linux-android`` targets at tier 3. 493The 32-bit targets ``arm-linux-androideabi`` and ``i686-linux-android`` 494are not tier 3 supported platforms, but will have best-effort support. 495(PEP written and implementation contributed by Malcolm Smith in 496:gh:`116622`.) 497 498.. seealso:: :pep:`730`, :pep:`738` 499 500 501Other Language Changes 502====================== 503 504* The compiler now strips common leading whitespace 505 from every line in a docstring. 506 This reduces the size of the :term:`bytecode cache <bytecode>` 507 (such as ``.pyc`` files), with reductions in file size of around 5%, 508 for example in :mod:`!sqlalchemy.orm.session` from SQLAlchemy 2.0. 509 This change affects tools that use docstrings, such as :mod:`doctest`. 510 511 .. doctest:: 512 513 >>> def spam(): 514 ... """ 515 ... This is a docstring with 516 ... leading whitespace. 517 ... 518 ... It even has multiple paragraphs! 519 ... """ 520 ... 521 >>> spam.__doc__ 522 '\nThis is a docstring with\n leading whitespace.\n\nIt even has multiple paragraphs!\n' 523 524 (Contributed by Inada Naoki in :gh:`81283`.) 525 526* :ref:`Annotation scopes <annotation-scopes>` within class scopes 527 can now contain lambdas and comprehensions. 528 Comprehensions that are located within class scopes 529 are not inlined into their parent scope. 530 531 .. code-block:: python 532 533 class C[T]: 534 type Alias = lambda: T 535 536 (Contributed by Jelle Zijlstra in :gh:`109118` and :gh:`118160`.) 537 538* :ref:`Future statements <future>` are no longer triggered by 539 relative imports of the :mod:`__future__` module, 540 meaning that statements of the form ``from .__future__ import ...`` 541 are now simply standard relative imports, with no special features activated. 542 (Contributed by Jeremiah Gabriel Pascual in :gh:`118216`.) 543 544* :keyword:`global` declarations are now permitted in :keyword:`except` blocks 545 when that global is used in the :keyword:`else` block. 546 Previously this raised an erroneous :exc:`SyntaxError`. 547 (Contributed by Irit Katriel in :gh:`111123`.) 548 549* Add :envvar:`PYTHON_FROZEN_MODULES`, a new environment variable that 550 determines whether frozen modules are ignored by the import machinery, 551 equivalent to the :option:`-X frozen_modules <-X>` command-line option. 552 (Contributed by Yilei Yang in :gh:`111374`.) 553 554* Add :ref:`support for the perf profiler <perf_profiling>` working 555 without `frame pointers <https://en.wikipedia.org/wiki/Call_stack>`_ through 556 the new environment variable :envvar:`PYTHON_PERF_JIT_SUPPORT` 557 and command-line option :option:`-X perf_jit <-X>`. 558 (Contributed by Pablo Galindo in :gh:`118518`.) 559 560* The location of a :file:`.python_history` file can be changed via the 561 new :envvar:`PYTHON_HISTORY` environment variable. 562 (Contributed by Levi Sabah, Zackery Spytz and Hugo van Kemenade 563 in :gh:`73965`.) 564 565* Classes have a new :attr:`~type.__static_attributes__` attribute. 566 This is populated by the compiler with a tuple of the class's attribute names 567 which are assigned through ``self.<name>`` from any function in its body. 568 (Contributed by Irit Katriel in :gh:`115775`.) 569 570* The compiler now creates a :attr:`!__firstlineno__` attribute on classes 571 with the line number of the first line of the class definition. 572 (Contributed by Serhiy Storchaka in :gh:`118465`.) 573 574* The :func:`exec` and :func:`eval` builtins now accept 575 the *globals* and *locals* arguments as keywords. 576 (Contributed by Raphael Gaschignard in :gh:`105879`) 577 578* The :func:`compile` builtin now accepts a new flag, 579 ``ast.PyCF_OPTIMIZED_AST``, which is similar to ``ast.PyCF_ONLY_AST`` 580 except that the returned AST is optimized according to 581 the value of the *optimize* argument. 582 (Contributed by Irit Katriel in :gh:`108113`). 583 584* Add a :attr:`~property.__name__` attribute on :class:`property` objects. 585 (Contributed by Eugene Toder in :gh:`101860`.) 586 587* Add :exc:`PythonFinalizationError`, a new exception derived from 588 :exc:`RuntimeError` and used to signal when operations are blocked 589 during :term:`finalization <interpreter shutdown>`. 590 The following callables now raise :exc:`!PythonFinalizationError`, 591 instead of :exc:`RuntimeError`: 592 593 * :func:`_thread.start_new_thread` 594 * :func:`os.fork` 595 * :func:`os.forkpty` 596 * :class:`subprocess.Popen` 597 598 (Contributed by Victor Stinner in :gh:`114570`.) 599 600* Allow the *count* argument of :meth:`str.replace` to be a keyword. 601 (Contributed by Hugo van Kemenade in :gh:`106487`.) 602 603* Many functions now emit a warning if a boolean value is passed as 604 a file descriptor argument. 605 This can help catch some errors earlier. 606 (Contributed by Serhiy Storchaka in :gh:`82626`.) 607 608* Added :attr:`!name` and :attr:`!mode` attributes 609 for compressed and archived file-like objects in 610 the :mod:`bz2`, :mod:`lzma`, :mod:`tarfile`, and :mod:`zipfile` modules. 611 (Contributed by Serhiy Storchaka in :gh:`115961`.) 612 613 614New Modules 615=========== 616 617* :mod:`dbm.sqlite3`: An SQLite backend for :mod:`dbm`. 618 (Contributed by Raymond Hettinger and Erlend E. Aasland in :gh:`100414`.) 619 620 621Improved Modules 622================ 623 624 625argparse 626-------- 627 628* Add the *deprecated* parameter to the 629 :meth:`~argparse.ArgumentParser.add_argument` 630 and :meth:`!add_parser` methods, to enable deprecating 631 command-line options, positional arguments, and subcommands. 632 (Contributed by Serhiy Storchaka in :gh:`83648`.) 633 634 635array 636----- 637 638* Add the ``'w'`` type code (``Py_UCS4``) for Unicode characters. 639 It should be used instead of the deprecated ``'u'`` type code. 640 (Contributed by Inada Naoki in :gh:`80480`.) 641 642* Register :class:`array.array` as a :class:`~collections.abc.MutableSequence` 643 by implementing the :meth:`~array.array.clear` method. 644 (Contributed by Mike Zimin in :gh:`114894`.) 645 646 647ast 648--- 649 650* The constructors of node types in the :mod:`ast` module are now 651 stricter in the arguments they accept, 652 with more intuitive behavior when arguments are omitted. 653 654 If an optional field on an AST node is not included as an argument when 655 constructing an instance, the field will now be set to ``None``. Similarly, 656 if a list field is omitted, that field will now be set to an empty list, 657 and if an :class:`!expr_context` field is omitted, it defaults to 658 :class:`Load() <ast.Load>`. 659 (Previously, in all cases, the attribute would be missing on the newly 660 constructed AST node instance.) 661 662 In all other cases, where a required argument is omitted, 663 the node constructor will emit a :exc:`DeprecationWarning`. 664 This will raise an exception in Python 3.15. 665 Similarly, passing a keyword argument to the constructor 666 that does not map to a field on the AST node is now deprecated, 667 and will raise an exception in Python 3.15. 668 669 These changes do not apply to user-defined subclasses of :class:`ast.AST` 670 unless the class opts in to the new behavior 671 by defining the :attr:`.AST._field_types` mapping. 672 673 (Contributed by Jelle Zijlstra in :gh:`105858`, :gh:`117486`, and :gh:`118851`.) 674 675* :func:`ast.parse` now accepts an optional argument *optimize* 676 which is passed on to :func:`compile`. 677 This makes it possible to obtain an optimized AST. 678 (Contributed by Irit Katriel in :gh:`108113`.) 679 680 681asyncio 682------- 683 684* :func:`asyncio.as_completed` now returns an object that is both an 685 :term:`asynchronous iterator` and a plain :term:`iterator` 686 of :term:`awaitables <awaitable>`. 687 The awaitables yielded by asynchronous iteration include original task 688 or future objects that were passed in, 689 making it easier to associate results with the tasks being completed. 690 (Contributed by Justin Arthur in :gh:`77714`.) 691 692* :meth:`asyncio.loop.create_unix_server` will now automatically remove 693 the Unix socket when the server is closed. 694 (Contributed by Pierre Ossman in :gh:`111246`.) 695 696* :meth:`.DatagramTransport.sendto` will now send zero-length 697 datagrams if called with an empty bytes object. 698 The transport flow control also now accounts for the datagram header 699 when calculating the buffer size. 700 (Contributed by Jamie Phan in :gh:`115199`.) 701 702* Add :meth:`Queue.shutdown <asyncio.Queue.shutdown>` 703 and :exc:`~asyncio.QueueShutDown` to manage queue termination. 704 (Contributed by Laurie Opperman and Yves Duprat in :gh:`104228`.) 705 706* Add the :meth:`.Server.close_clients` and :meth:`.Server.abort_clients` 707 methods, which more forcefully close an asyncio server. 708 (Contributed by Pierre Ossman in :gh:`113538`.) 709 710* Accept a tuple of separators in :meth:`.StreamReader.readuntil`, 711 stopping when any one of them is encountered. 712 (Contributed by Bruce Merry in :gh:`81322`.) 713 714* Improve the behavior of :class:`~asyncio.TaskGroup` when 715 an external cancellation collides with an internal cancellation. 716 For example, when two task groups are nested 717 and both experience an exception in a child task simultaneously, 718 it was possible that the outer task group would hang, 719 because its internal cancellation was swallowed by the inner task group. 720 721 In the case where a task group is cancelled externally 722 and also must raise an :exc:`ExceptionGroup`, 723 it will now call the parent task's :meth:`~asyncio.Task.cancel` method. 724 This ensures that a :exc:`~asyncio.CancelledError` will be raised 725 at the next :keyword:`await`, so the cancellation is not lost. 726 727 An added benefit of these changes is that task groups now preserve 728 the cancellation count (:meth:`~asyncio.Task.cancelling`). 729 730 In order to handle some corner cases, :meth:`~asyncio.Task.uncancel` may now 731 reset the undocumented ``_must_cancel`` flag 732 when the cancellation count reaches zero. 733 734 (Inspired by an issue reported by Arthur Tacca in :gh:`116720`.) 735 736* When :meth:`.TaskGroup.create_task` is called on an inactive 737 :class:`~asyncio.TaskGroup`, the given coroutine will be closed (which 738 prevents a :exc:`RuntimeWarning` about the given coroutine being 739 never awaited). 740 (Contributed by Arthur Tacca and Jason Zhang in :gh:`115957`.) 741 742 743base64 744------ 745 746* Add :func:`~base64.z85encode` and :func:`~base64.z85decode` functions 747 for encoding :class:`bytes` as `Z85 data`_ 748 and decoding Z85-encoded data to :class:`!bytes`. 749 (Contributed by Matan Perelman in :gh:`75299`.) 750 751 .. _Z85 data: https://rfc.zeromq.org/spec/32/ 752 753 754compileall 755---------- 756 757* The default number of worker threads and processes is now selected using 758 :func:`os.process_cpu_count` instead of :func:`os.cpu_count`. 759 (Contributed by Victor Stinner in :gh:`109649`.) 760 761 762concurrent.futures 763------------------ 764 765* The default number of worker threads and processes is now selected using 766 :func:`os.process_cpu_count` instead of :func:`os.cpu_count`. 767 (Contributed by Victor Stinner in :gh:`109649`.) 768 769 770configparser 771------------ 772 773* :class:`~configparser.ConfigParser` now has support for unnamed sections, 774 which allows for top-level key-value pairs. 775 This can be enabled with the new *allow_unnamed_section* parameter. 776 (Contributed by Pedro Sousa Lacerda in :gh:`66449`.) 777 778 779copy 780---- 781 782* The new :func:`~copy.replace` function and the :meth:`replace protocol 783 <object.__replace__>` make creating modified copies of objects much simpler. 784 This is especially useful when working with immutable objects. 785 The following types support the :func:`~copy.replace` function 786 and implement the replace protocol: 787 788 * :func:`collections.namedtuple` 789 * :class:`dataclasses.dataclass` 790 * :class:`datetime.datetime`, :class:`datetime.date`, :class:`datetime.time` 791 * :class:`inspect.Signature`, :class:`inspect.Parameter` 792 * :class:`types.SimpleNamespace` 793 * :ref:`code objects <code-objects>` 794 795 Any user-defined class can also support :func:`copy.replace` by defining 796 the :meth:`~object.__replace__` method. 797 (Contributed by Serhiy Storchaka in :gh:`108751`.) 798 799 800ctypes 801------ 802 803* As a consequence of necessary internal refactoring, initialization of 804 internal metaclasses now happens in ``__init__`` rather 805 than in ``__new__``. This affects projects that subclass these internal 806 metaclasses to provide custom initialization. 807 Generally: 808 809 - Custom logic that was done in ``__new__`` after calling ``super().__new__`` 810 should be moved to ``__init__``. 811 - To create a class, call the metaclass, not only the metaclass's 812 ``__new__`` method. 813 814 See :gh:`124520` for discussion and links to changes in some affected 815 projects. 816 817* :class:`ctypes.Structure` objects have a new :attr:`~ctypes.Structure._align_` 818 attribute which allows the alignment of the structure being packed to/from 819 memory to be specified explicitly. 820 (Contributed by Matt Sanderson in :gh:`112433`) 821 822dbm 823--- 824 825* Add :mod:`dbm.sqlite3`, a new module which implements an SQLite backend, 826 and make it the default :mod:`!dbm` backend. 827 (Contributed by Raymond Hettinger and Erlend E. Aasland in :gh:`100414`.) 828 829* Allow removing all items from the database through 830 the new :meth:`.gdbm.clear` and :meth:`.ndbm.clear` methods. 831 (Contributed by Donghee Na in :gh:`107122`.) 832 833 834dis 835--- 836 837* Change the output of :mod:`dis` module functions to show logical 838 labels for jump targets and exception handlers, rather than offsets. 839 The offsets can be added with the new 840 :option:`-O <dis --show-offsets>` command-line option 841 or the *show_offsets* argument. 842 (Contributed by Irit Katriel in :gh:`112137`.) 843 844* :meth:`~dis.get_instructions` no longer represents cache entries 845 as separate instructions. 846 Instead, it returns them as part of the :class:`~dis.Instruction`, 847 in the new *cache_info* field. 848 The *show_caches* argument to :meth:`~dis.get_instructions` is deprecated 849 and no longer has any effect. 850 (Contributed by Irit Katriel in :gh:`112962`.) 851 852 853.. _whatsnew313-doctest: 854 855doctest 856------- 857 858* :mod:`doctest` output is now colored by default. 859 This can be controlled via the new :envvar:`PYTHON_COLORS` environment 860 variable as well as the canonical |NO_COLOR|_ 861 and |FORCE_COLOR|_ environment variables. 862 See also :ref:`using-on-controlling-color`. 863 (Contributed by Hugo van Kemenade in :gh:`117225`.) 864 865* The :meth:`.DocTestRunner.run` method now counts the number of skipped tests. 866 Add the :attr:`.DocTestRunner.skips` and :attr:`.TestResults.skipped` attributes. 867 (Contributed by Victor Stinner in :gh:`108794`.) 868 869 870email 871----- 872 873* Headers with embedded newlines are now quoted on output. 874 The :mod:`~email.generator` will now refuse to serialize (write) headers 875 that are improperly folded or delimited, such that they would be parsed as 876 multiple headers or joined with adjacent data. 877 If you need to turn this safety feature off, 878 set :attr:`~email.policy.Policy.verify_generated_headers`. 879 (Contributed by Bas Bloemsaat and Petr Viktorin in :gh:`121650`.) 880 881* :func:`~email.utils.getaddresses` and :func:`~email.utils.parseaddr` now 882 return ``('', '')`` pairs in more situations where invalid email addresses 883 are encountered instead of potentially inaccurate values. 884 The two functions have a new optional *strict* parameter (default ``True``). 885 To get the old behavior (accepting malformed input), use ``strict=False``. 886 ``getattr(email.utils, 'supports_strict_parsing', False)`` can be used 887 to check if the *strict* parameter is available. 888 (Contributed by Thomas Dwyer and Victor Stinner for :gh:`102988` to improve 889 the :cve:`2023-27043` fix.) 890 891 892fractions 893--------- 894 895* :class:`~fractions.Fraction` objects now support the standard 896 :ref:`format specification mini-language <formatspec>` rules 897 for fill, alignment, sign handling, minimum width, and grouping. 898 (Contributed by Mark Dickinson in :gh:`111320`.) 899 900 901glob 902---- 903 904* Add :func:`~glob.translate`, a function to convert a path specification 905 with shell-style wildcards to a regular expression. 906 (Contributed by Barney Gale in :gh:`72904`.) 907 908 909importlib 910--------- 911 912* The following functions in :mod:`importlib.resources` now allow accessing 913 a directory (or tree) of resources, using multiple positional arguments 914 (the *encoding* and *errors* arguments in the text-reading functions 915 are now keyword-only): 916 917 * :func:`~importlib.resources.is_resource` 918 * :func:`~importlib.resources.open_binary` 919 * :func:`~importlib.resources.open_text` 920 * :func:`~importlib.resources.path` 921 * :func:`~importlib.resources.read_binary` 922 * :func:`~importlib.resources.read_text` 923 924 These functions are no longer deprecated and are not scheduled for removal. 925 (Contributed by Petr Viktorin in :gh:`116608`.) 926 927* :func:`~importlib.resources.contents` remains deprecated in favor of 928 the fully-featured :class:`~importlib.resources.abc.Traversable` API. 929 However, there is now no plan to remove it. 930 (Contributed by Petr Viktorin in :gh:`116608`.) 931 932 933io 934-- 935 936* The :class:`~io.IOBase` finalizer now logs any errors raised by 937 the :meth:`~io.IOBase.close` method with :data:`sys.unraisablehook`. 938 Previously, errors were ignored silently by default, 939 and only logged in :ref:`Python Development Mode <devmode>` 940 or when using a :ref:`Python debug build <debug-build>`. 941 (Contributed by Victor Stinner in :gh:`62948`.) 942 943 944ipaddress 945--------- 946 947* Add the :attr:`.IPv4Address.ipv6_mapped` property, 948 which returns the IPv4-mapped IPv6 address. 949 (Contributed by Charles Machalow in :gh:`109466`.) 950 951* Fix ``is_global`` and ``is_private`` behavior in 952 :class:`~ipaddress.IPv4Address`, :class:`~ipaddress.IPv6Address`, 953 :class:`~ipaddress.IPv4Network`, and :class:`~ipaddress.IPv6Network`. 954 (Contributed by Jakub Stasiak in :gh:`113171`.) 955 956 957itertools 958--------- 959 960* :func:`~itertools.batched` has a new *strict* parameter, 961 which raises a :exc:`ValueError` if the final batch is shorter 962 than the specified batch size. 963 (Contributed by Raymond Hettinger in :gh:`113202`.) 964 965 966marshal 967------- 968 969* Add the *allow_code* parameter in module functions. 970 Passing ``allow_code=False`` prevents serialization and de-serialization 971 of code objects which are incompatible between Python versions. 972 (Contributed by Serhiy Storchaka in :gh:`113626`.) 973 974 975math 976---- 977 978* The new function :func:`~math.fma` performs fused multiply-add operations. 979 This computes ``x * y + z`` with only a single round, 980 and so avoids any intermediate loss of precision. 981 It wraps the ``fma()`` function provided by C99, 982 and follows the specification of the IEEE 754 "fusedMultiplyAdd" operation 983 for special cases. 984 (Contributed by Mark Dickinson and Victor Stinner in :gh:`73468`.) 985 986 987mimetypes 988--------- 989 990* Add the :func:`~mimetypes.guess_file_type` function to guess a MIME type 991 from a filesystem path. 992 Using paths with :func:`~mimetypes.guess_type` is now :term:`soft deprecated`. 993 (Contributed by Serhiy Storchaka in :gh:`66543`.) 994 995 996mmap 997---- 998 999* :class:`~mmap.mmap` is now protected from crashing on Windows when the 1000 mapped memory is inaccessible due to file system errors or access violations. 1001 (Contributed by Jannis Weigend in :gh:`118209`.) 1002 1003* :class:`~mmap.mmap` has a new :meth:`~mmap.mmap.seekable` method 1004 that can be used when a seekable file-like object is required. 1005 The :meth:`~mmap.mmap.seek` method now returns the new absolute position. 1006 (Contributed by Donghee Na and Sylvie Liberman in :gh:`111835`.) 1007 1008* The new UNIX-only *trackfd* parameter for :class:`~mmap.mmap` controls 1009 file descriptor duplication; 1010 if false, the file descriptor specified by *fileno* will not be duplicated. 1011 (Contributed by Zackery Spytz and Petr Viktorin in :gh:`78502`.) 1012 1013 1014multiprocessing 1015--------------- 1016 1017* The default number of worker threads and processes is now selected using 1018 :func:`os.process_cpu_count` instead of :func:`os.cpu_count`. 1019 (Contributed by Victor Stinner in :gh:`109649`.) 1020 1021 1022os 1023-- 1024 1025* Add :func:`~os.process_cpu_count` function to get the number 1026 of logical CPU cores usable by the calling thread of the current process. 1027 (Contributed by Victor Stinner in :gh:`109649`.) 1028 1029* :func:`~os.cpu_count` and :func:`~os.process_cpu_count` can be overridden 1030 through the new environment variable :envvar:`PYTHON_CPU_COUNT` 1031 or the new command-line option :option:`-X cpu_count <-X>`. 1032 This option is useful for users who need to limit CPU resources 1033 of a container system without having to modify application code 1034 or the container itself. 1035 (Contributed by Donghee Na in :gh:`109595`.) 1036 1037* Add a :ref:`low level interface <os-timerfd>` to Linux's 1038 :manpage:`timer file descriptors <timerfd_create(2)>` 1039 via :func:`~os.timerfd_create`, 1040 :func:`~os.timerfd_settime`, :func:`~os.timerfd_settime_ns`, 1041 :func:`~os.timerfd_gettime`, :func:`~os.timerfd_gettime_ns`, 1042 :const:`~os.TFD_NONBLOCK`, :const:`~os.TFD_CLOEXEC`, 1043 :const:`~os.TFD_TIMER_ABSTIME`, and :const:`~os.TFD_TIMER_CANCEL_ON_SET` 1044 (Contributed by Masaru Tsuchiyama in :gh:`108277`.) 1045 1046* :func:`~os.lchmod` and the *follow_symlinks* argument of :func:`~os.chmod` 1047 are both now available on Windows. 1048 Note that the default value of *follow_symlinks* 1049 in :func:`!lchmod` is ``False`` on Windows. 1050 (Contributed by Serhiy Storchaka in :gh:`59616`.) 1051 1052* :func:`~os.fchmod` and support for file descriptors in :func:`~os.chmod` 1053 are both now available on Windows. 1054 (Contributed by Serhiy Storchaka in :gh:`113191`.) 1055 1056* On Windows, :func:`~os.mkdir` and :func:`~os.makedirs` now support passing 1057 a *mode* value of ``0o700`` to apply access control to the new directory. 1058 This implicitly affects :func:`tempfile.mkdtemp` 1059 and is a mitigation for :cve:`2024-4030`. 1060 Other values for *mode* continue to be ignored. 1061 (Contributed by Steve Dower in :gh:`118486`.) 1062 1063* :func:`~os.posix_spawn` now accepts ``None`` for the *env* argument, 1064 which makes the newly spawned process use the current process environment. 1065 (Contributed by Jakub Kulik in :gh:`113119`.) 1066 1067* :func:`~os.posix_spawn` can now use the :attr:`~os.POSIX_SPAWN_CLOSEFROM` 1068 attribute in the *file_actions* parameter on platforms that support 1069 :c:func:`!posix_spawn_file_actions_addclosefrom_np`. 1070 (Contributed by Jakub Kulik in :gh:`113117`.) 1071 1072 1073os.path 1074------- 1075 1076* Add :func:`~os.path.isreserved` to check if a path is reserved 1077 on the current system. 1078 This function is only available on Windows. 1079 (Contributed by Barney Gale in :gh:`88569`.) 1080 1081* On Windows, :func:`~os.path.isabs` no longer considers paths 1082 starting with exactly one slash (``\`` or ``/``) to be absolute. 1083 (Contributed by Barney Gale and Jon Foster in :gh:`44626`.) 1084 1085* :func:`~os.path.realpath` now resolves MS-DOS style file names 1086 even if the file is not accessible. 1087 (Contributed by Moonsik Park in :gh:`82367`.) 1088 1089 1090pathlib 1091------- 1092 1093* Add :exc:`~pathlib.UnsupportedOperation`, which is raised instead of 1094 :exc:`NotImplementedError` when a path operation isn't supported. 1095 (Contributed by Barney Gale in :gh:`89812`.) 1096 1097* Add a new constructor for creating :class:`~pathlib.Path` objects 1098 from 'file' URIs (``file:///``), :meth:`.Path.from_uri`. 1099 (Contributed by Barney Gale in :gh:`107465`.) 1100 1101* Add :meth:`.PurePath.full_match` for matching paths with 1102 shell-style wildcards, including the recursive wildcard "``**``". 1103 (Contributed by Barney Gale in :gh:`73435`.) 1104 1105* Add the :attr:`.PurePath.parser` class attribute to store the 1106 implementation of :mod:`os.path` used 1107 for low-level path parsing and joining. 1108 This will be either :mod:`!posixpath` or :mod:`!ntpath`. 1109 1110* Add *recurse_symlinks* keyword-only argument to 1111 :meth:`.Path.glob` and :meth:`~pathlib.Path.rglob`. 1112 (Contributed by Barney Gale in :gh:`77609`.) 1113 1114* :meth:`.Path.glob` and :meth:`~pathlib.Path.rglob` 1115 now return files and directories when given a pattern that ends with "``**``". 1116 Previously, only directories were returned. 1117 (Contributed by Barney Gale in :gh:`70303`.) 1118 1119* Add the *follow_symlinks* keyword-only argument to 1120 :meth:`Path.is_file <pathlib.Path.is_file>`, 1121 :meth:`Path.is_dir <pathlib.Path.is_dir>`, 1122 :meth:`.Path.owner`, and :meth:`.Path.group`. 1123 (Contributed by Barney Gale in :gh:`105793` and Kamil Turek in :gh:`107962`.) 1124 1125 1126pdb 1127--- 1128 1129* :func:`breakpoint` and :func:`~pdb.set_trace` now enter the debugger immediately 1130 rather than on the next line of code to be executed. This change prevents the 1131 debugger from breaking outside of the context when :func:`!breakpoint` is positioned 1132 at the end of the context. 1133 (Contributed by Tian Gao in :gh:`118579`.) 1134 1135* ``sys.path[0]`` is no longer replaced by the directory of the script 1136 being debugged when :attr:`sys.flags.safe_path` is set. 1137 (Contributed by Tian Gao and Christian Walther in :gh:`111762`.) 1138 1139* :mod:`zipapp` is now supported as a debugging target. 1140 (Contributed by Tian Gao in :gh:`118501`.) 1141 1142* Add ability to move between chained exceptions during 1143 post-mortem debugging in :func:`~pdb.pm` using 1144 the new :pdbcmd:`exceptions [exc_number] <exceptions>` command for Pdb. 1145 (Contributed by Matthias Bussonnier in :gh:`106676`.) 1146 1147* Expressions and statements whose prefix is a pdb command are now correctly 1148 identified and executed. 1149 (Contributed by Tian Gao in :gh:`108464`.) 1150 1151 1152queue 1153----- 1154 1155* Add :meth:`Queue.shutdown <queue.Queue.shutdown>` and :exc:`~queue.ShutDown` 1156 to manage queue termination. 1157 (Contributed by Laurie Opperman and Yves Duprat in :gh:`104750`.) 1158 1159 1160random 1161------ 1162 1163* Add a :ref:`command-line interface <random-cli>`. 1164 (Contributed by Hugo van Kemenade in :gh:`118131`.) 1165 1166 1167re 1168-- 1169 1170* Rename :exc:`!re.error` to :exc:`~re.PatternError` for improved clarity. 1171 :exc:`!re.error` is kept for backward compatibility. 1172 1173 1174shutil 1175------ 1176 1177* Support the *dir_fd* and *follow_symlinks* keyword arguments 1178 in :func:`~shutil.chown`. 1179 (Contributed by Berker Peksag and Tahia K in :gh:`62308`) 1180 1181 1182site 1183---- 1184 1185* :file:`.pth` files are now decoded using UTF-8 first, 1186 and then with the :term:`locale encoding` if UTF-8 decoding fails. 1187 (Contributed by Inada Naoki in :gh:`117802`.) 1188 1189 1190sqlite3 1191------- 1192 1193* A :exc:`ResourceWarning` is now emitted if a :class:`~sqlite3.Connection` 1194 object is not :meth:`closed <sqlite3.Connection.close>` explicitly. 1195 (Contributed by Erlend E. Aasland in :gh:`105539`.) 1196 1197* Add the *filter* keyword-only parameter to :meth:`.Connection.iterdump` 1198 for filtering database objects to dump. 1199 (Contributed by Mariusz Felisiak in :gh:`91602`.) 1200 1201 1202ssl 1203--- 1204 1205* The :func:`~ssl.create_default_context` API now includes 1206 :data:`~ssl.VERIFY_X509_PARTIAL_CHAIN` and :data:`~ssl.VERIFY_X509_STRICT` 1207 in its default flags. 1208 1209 .. note:: 1210 1211 :data:`~ssl.VERIFY_X509_STRICT` may reject pre-:rfc:`5280` 1212 or malformed certificates that the underlying OpenSSL implementation 1213 might otherwise accept. 1214 Whilst disabling this is not recommended, you can do so using: 1215 1216 .. code-block:: python 1217 1218 import ssl 1219 1220 ctx = ssl.create_default_context() 1221 ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT 1222 1223 (Contributed by William Woodruff in :gh:`112389`.) 1224 1225 1226statistics 1227---------- 1228 1229* Add :func:`~statistics.kde` for kernel density estimation. 1230 This makes it possible to estimate a continuous probability density function 1231 from a fixed number of discrete samples. 1232 (Contributed by Raymond Hettinger in :gh:`115863`.) 1233 1234* Add :func:`~statistics.kde_random` for sampling from an 1235 estimated probability density function created by :func:`~statistics.kde`. 1236 (Contributed by Raymond Hettinger in :gh:`115863`.) 1237 1238 1239.. _whatsnew313-subprocess: 1240 1241subprocess 1242---------- 1243 1244* The :mod:`subprocess` module now uses the :func:`~os.posix_spawn` function in 1245 more situations. 1246 1247 Notably, when *close_fds* is ``True`` (the default), 1248 :func:`~os.posix_spawn` will be used when the C library provides 1249 :c:func:`!posix_spawn_file_actions_addclosefrom_np`, 1250 which includes recent versions of Linux, FreeBSD, and Solaris. 1251 On Linux, this should perform similarly to the existing 1252 Linux :c:func:`!vfork` based code. 1253 1254 A private control knob :attr:`!subprocess._USE_POSIX_SPAWN` can 1255 be set to ``False`` if you need to force :mod:`subprocess` 1256 to never use :func:`~os.posix_spawn`. 1257 Please report your reason and platform details in 1258 the :ref:`issue tracker <using-the-tracker>` if you set this 1259 so that we can improve our API selection logic for everyone. 1260 (Contributed by Jakub Kulik in :gh:`113117`.) 1261 1262 1263sys 1264--- 1265 1266* Add the :func:`~sys._is_interned` function to test if a string was interned. 1267 This function is not guaranteed to exist in all implementations of Python. 1268 (Contributed by Serhiy Storchaka in :gh:`78573`.) 1269 1270 1271tempfile 1272-------- 1273 1274* On Windows, the default mode ``0o700`` used by :func:`tempfile.mkdtemp` now 1275 limits access to the new directory due to changes to :func:`os.mkdir`. 1276 This is a mitigation for :cve:`2024-4030`. 1277 (Contributed by Steve Dower in :gh:`118486`.) 1278 1279 1280time 1281---- 1282 1283* On Windows, :func:`~time.monotonic` now uses the 1284 ``QueryPerformanceCounter()`` clock for a resolution of 1 microsecond, 1285 instead of the ``GetTickCount64()`` clock which has 1286 a resolution of 15.6 milliseconds. 1287 (Contributed by Victor Stinner in :gh:`88494`.) 1288 1289* On Windows, :func:`~time.time` now uses the 1290 ``GetSystemTimePreciseAsFileTime()`` clock for a resolution of 1 microsecond, 1291 instead of the ``GetSystemTimeAsFileTime()`` clock which has 1292 a resolution of 15.6 milliseconds. 1293 (Contributed by Victor Stinner in :gh:`63207`.) 1294 1295 1296tkinter 1297------- 1298 1299* Add :mod:`tkinter` widget methods: 1300 :meth:`!tk_busy_hold`, :meth:`!tk_busy_configure`, 1301 :meth:`!tk_busy_cget`, :meth:`!tk_busy_forget`, 1302 :meth:`!tk_busy_current`, and :meth:`!tk_busy_status`. 1303 (Contributed by Miguel, klappnase and Serhiy Storchaka in :gh:`72684`.) 1304 1305* The :mod:`tkinter` widget method :meth:`!wm_attributes` now accepts 1306 the attribute name without the minus prefix to get window attributes, 1307 for example ``w.wm_attributes('alpha')`` 1308 and allows specifying attributes and values to set as keyword arguments, 1309 for example ``w.wm_attributes(alpha=0.5)``. 1310 (Contributed by Serhiy Storchaka in :gh:`43457`.) 1311 1312* :meth:`!wm_attributes` can now return attributes as a :class:`dict`, 1313 by using the new optional keyword-only parameter *return_python_dict*. 1314 (Contributed by Serhiy Storchaka in :gh:`43457`.) 1315 1316* :meth:`!Text.count` can now return a simple :class:`int` 1317 when the new optional keyword-only parameter *return_ints* is used. 1318 Otherwise, the single count is returned as a 1-tuple or ``None``. 1319 (Contributed by Serhiy Storchaka in :gh:`97928`.) 1320 1321* Support the "vsapi" element type in 1322 the :meth:`~tkinter.ttk.Style.element_create` method of 1323 :class:`tkinter.ttk.Style`. 1324 (Contributed by Serhiy Storchaka in :gh:`68166`.) 1325 1326* Add the :meth:`!after_info` method for Tkinter widgets. 1327 (Contributed by Cheryl Sabella in :gh:`77020`.) 1328 1329* Add a new :meth:`!copy_replace` method to :class:`!PhotoImage` 1330 to copy a region from one image to another, 1331 possibly with pixel zooming, subsampling, or both. 1332 (Contributed by Serhiy Storchaka in :gh:`118225`.) 1333 1334* Add *from_coords* parameter to the :class:`!PhotoImage` methods 1335 :meth:`!copy`, :meth:`!zoom` and :meth:`!subsample`. 1336 Add *zoom* and *subsample* parameters to the :class:`!PhotoImage` method 1337 :meth:`!copy`. 1338 (Contributed by Serhiy Storchaka in :gh:`118225`.) 1339 1340* Add the :class:`!PhotoImage` methods 1341 :meth:`!read` to read an image from a file 1342 and :meth:`!data` to get the image data. 1343 Add *background* and *grayscale* parameters to the :meth:`!write` method. 1344 (Contributed by Serhiy Storchaka in :gh:`118271`.) 1345 1346 1347traceback 1348--------- 1349 1350* Add the :attr:`~traceback.TracebackException.exc_type_str` attribute 1351 to :class:`~traceback.TracebackException`, 1352 which holds a string display of the *exc_type*. 1353 Deprecate the :attr:`~traceback.TracebackException.exc_type` attribute, 1354 which holds the type object itself. 1355 Add parameter *save_exc_type* (default ``True``) 1356 to indicate whether ``exc_type`` should be saved. 1357 (Contributed by Irit Katriel in :gh:`112332`.) 1358 1359* Add a new *show_group* keyword-only parameter to 1360 :meth:`.TracebackException.format_exception_only` to (recursively) format 1361 the nested exceptions of a :exc:`BaseExceptionGroup` instance. 1362 (Contributed by Irit Katriel in :gh:`105292`.) 1363 1364 1365types 1366----- 1367 1368* :class:`~types.SimpleNamespace` can now take a single positional argument 1369 to initialise the namespace's arguments. 1370 This argument must either be a mapping or an iterable of key-value pairs. 1371 (Contributed by Serhiy Storchaka in :gh:`108191`.) 1372 1373 1374typing 1375------ 1376 1377* :pep:`705`: Add :data:`~typing.ReadOnly`, a special typing construct 1378 to mark a :class:`~typing.TypedDict` item as read-only for type checkers. 1379 1380* :pep:`742`: Add :data:`~typing.TypeIs`, a typing construct 1381 that can be used to instruct a type checker how to narrow a type. 1382 1383* Add :data:`~typing.NoDefault`, a sentinel object used to represent 1384 the defaults of some parameters in the :mod:`typing` module. 1385 (Contributed by Jelle Zijlstra in :gh:`116126`.) 1386 1387* Add :func:`~typing.get_protocol_members` to return the set of members 1388 defining a :class:`typing.Protocol`. 1389 (Contributed by Jelle Zijlstra in :gh:`104873`.) 1390 1391* Add :func:`~typing.is_protocol` to check whether a class 1392 is a :class:`~typing.Protocol`. 1393 (Contributed by Jelle Zijlstra in :gh:`104873`.) 1394 1395* :data:`~typing.ClassVar` can now be nested in :data:`~typing.Final`, 1396 and vice versa. 1397 (Contributed by Mehdi Drissi in :gh:`89547`.) 1398 1399 1400unicodedata 1401----------- 1402 1403* Update the Unicode database to `version 15.1.0`__. 1404 (Contributed by James Gerity in :gh:`109559`.) 1405 1406 __ https://www.unicode.org/versions/Unicode15.1.0/ 1407 1408 1409venv 1410---- 1411 1412* Add support for creating source control management (SCM) ignore files 1413 in a virtual environment's directory. 1414 By default, Git is supported. 1415 This is implemented as opt-in via the API, 1416 which can be extended to support other SCMs 1417 (:class:`~venv.EnvBuilder` and :func:`~venv.create`), 1418 and opt-out via the CLI, using :option:`!--without-scm-ignore-files`. 1419 (Contributed by Brett Cannon in :gh:`108125`.) 1420 1421 1422warnings 1423-------- 1424 1425* :pep:`702`: The new :func:`warnings.deprecated` decorator provides a way to 1426 communicate deprecations to a :term:`static type checker` 1427 and to warn on usage of deprecated classes and functions. 1428 A :exc:`DeprecationWarning` may also be emitted when 1429 a decorated function or class is used at runtime. 1430 (Contributed by Jelle Zijlstra in :gh:`104003`.) 1431 1432 1433xml 1434--- 1435 1436* Allow controlling Expat >=2.6.0 reparse deferral (:cve:`2023-52425`) 1437 by adding five new methods: 1438 1439 * :meth:`xml.etree.ElementTree.XMLParser.flush` 1440 * :meth:`xml.etree.ElementTree.XMLPullParser.flush` 1441 * :meth:`xml.parsers.expat.xmlparser.GetReparseDeferralEnabled` 1442 * :meth:`xml.parsers.expat.xmlparser.SetReparseDeferralEnabled` 1443 * :meth:`!xml.sax.expatreader.ExpatParser.flush` 1444 1445 (Contributed by Sebastian Pipping in :gh:`115623`.) 1446 1447* Add the :meth:`!close` method for the iterator returned by 1448 :func:`~xml.etree.ElementTree.iterparse` for explicit cleanup. 1449 (Contributed by Serhiy Storchaka in :gh:`69893`.) 1450 1451 1452zipimport 1453--------- 1454 1455* Add support for ZIP64_ format files. 1456 Everybody loves huge data, right? 1457 (Contributed by Tim Hatch in :gh:`94146`.) 1458 1459 .. _ZIP64: https://en.wikipedia.org/wiki/Zip_(file_format)#ZIP64 1460 1461 1462Optimizations 1463============= 1464 1465* Several standard library modules have had 1466 their import times significantly improved. 1467 For example, the import time of the :mod:`typing` module 1468 has been reduced by around a third by removing dependencies 1469 on :mod:`re` and :mod:`contextlib`. 1470 Other modules to enjoy import-time speedups include 1471 :mod:`email.utils`, :mod:`enum`, :mod:`functools`, 1472 :mod:`importlib.metadata`, and :mod:`threading`. 1473 (Contributed by Alex Waygood, Shantanu Jain, Adam Turner, Daniel Hollas, 1474 and others in :gh:`109653`.) 1475 1476* :func:`textwrap.indent` is now around 30% faster than before for large input. 1477 (Contributed by Inada Naoki in :gh:`107369`.) 1478 1479* The :mod:`subprocess` module now uses the :func:`~os.posix_spawn` function in 1480 more situations, including when *close_fds* is ``True`` (the default) 1481 on many modern platforms. 1482 This should provide a notable performance increase 1483 when launching processes on FreeBSD and Solaris. 1484 See the :ref:`subprocess <whatsnew313-subprocess>` section above for details. 1485 (Contributed by Jakub Kulik in :gh:`113117`.) 1486 1487 1488Removed Modules And APIs 1489======================== 1490 1491 1492.. _whatsnew313-pep594: 1493 1494PEP 594: Remove "dead batteries" from the standard library 1495---------------------------------------------------------- 1496 1497:pep:`594` proposed removing 19 modules from the standard library, 1498colloquially referred to as 'dead batteries' due to their 1499historic, obsolete, or insecure status. 1500All of the following modules were deprecated in Python 3.11, 1501and are now removed: 1502 1503* :mod:`!aifc` 1504* :mod:`!audioop` 1505* :mod:`!chunk` 1506* :mod:`!cgi` and :mod:`!cgitb` 1507 1508 * :class:`!cgi.FieldStorage` can typically be replaced with 1509 :func:`urllib.parse.parse_qsl` for ``GET`` and ``HEAD`` requests, 1510 and the :mod:`email.message` module or the :pypi:`multipart` library 1511 for ``POST`` and ``PUT`` requests. 1512 1513 * :func:`!cgi.parse` can be replaced by calling 1514 :func:`urllib.parse.parse_qs` directly on the desired query string, 1515 unless the input is ``multipart/form-data``, 1516 which should be replaced as described below for :func:`!cgi.parse_multipart`. 1517 1518 * :func:`!cgi.parse_header` can be replaced with the functionality 1519 in the :mod:`email` package, which implements the same MIME RFCs. 1520 For example, with :class:`email.message.EmailMessage`: 1521 1522 .. code-block:: python 1523 1524 from email.message import EmailMessage 1525 1526 msg = EmailMessage() 1527 msg['content-type'] = 'application/json; charset="utf8"' 1528 main, params = msg.get_content_type(), msg['content-type'].params 1529 1530 * :func:`!cgi.parse_multipart` can be replaced with the functionality 1531 in the :mod:`email` package, which implements the same MIME RFCs, 1532 or with the :pypi:`multipart` library. 1533 For example, the :class:`email.message.EmailMessage` 1534 and :class:`email.message.Message` classes. 1535 1536* :mod:`!crypt` and the private :mod:`!_crypt` extension. 1537 The :mod:`hashlib` module may be an appropriate replacement 1538 when simply hashing a value is required. 1539 Otherwise, various third-party libraries on PyPI are available: 1540 1541 * :pypi:`bcrypt`: 1542 Modern password hashing for your software and your servers. 1543 * :pypi:`passlib`: 1544 Comprehensive password hashing framework supporting over 30 schemes. 1545 * :pypi:`argon2-cffi`: 1546 The secure Argon2 password hashing algorithm. 1547 * :pypi:`legacycrypt`: 1548 :mod:`ctypes` wrapper to the POSIX crypt library call 1549 and associated functionality. 1550 * :pypi:`crypt_r`: 1551 Fork of the :mod:`!crypt` module, 1552 wrapper to the :manpage:`crypt_r(3)` library call 1553 and associated functionality. 1554 1555* :mod:`!imghdr`: 1556 The :pypi:`filetype`, :pypi:`puremagic`, or :pypi:`python-magic` libraries 1557 should be used as replacements. 1558 For example, the :func:`!puremagic.what` function can be used 1559 to replace the :func:`!imghdr.what` function for all file formats 1560 that were supported by :mod:`!imghdr`. 1561* :mod:`!mailcap`: 1562 Use the :mod:`mimetypes` module instead. 1563* :mod:`!msilib` 1564* :mod:`!nis` 1565* :mod:`!nntplib`: 1566 Use the :pypi:`pynntp` library from PyPI instead. 1567* :mod:`!ossaudiodev`: 1568 For audio playback, use the :pypi:`pygame` library from PyPI instead. 1569* :mod:`!pipes`: 1570 Use the :mod:`subprocess` module instead. 1571 Use :func:`shlex.quote` to replace the undocumented ``pipes.quote`` 1572 function. 1573* :mod:`!sndhdr`: 1574 The :pypi:`filetype`, :pypi:`puremagic`, or :pypi:`python-magic` libraries 1575 should be used as replacements. 1576* :mod:`!spwd`: 1577 Use the :pypi:`python-pam` library from PyPI instead. 1578* :mod:`!sunau` 1579* :mod:`!telnetlib`, 1580 Use the :pypi:`telnetlib3` or :pypi:`Exscript` libraries from PyPI instead. 1581* :mod:`!uu`: 1582 Use the :mod:`base64` module instead, as a modern alternative. 1583* :mod:`!xdrlib` 1584 1585(Contributed by Victor Stinner and Zachary Ware in :gh:`104773` and :gh:`104780`.) 1586 1587 15882to3 1589---- 1590 1591* Remove the :program:`2to3` program and the :mod:`!lib2to3` module, 1592 previously deprecated in Python 3.11. 1593 (Contributed by Victor Stinner in :gh:`104780`.) 1594 1595 1596builtins 1597-------- 1598 1599* Remove support for chained :class:`classmethod` descriptors 1600 (introduced in :gh:`63272`). 1601 These can no longer be used to wrap other descriptors, 1602 such as :class:`property`. 1603 The core design of this feature was flawed and led to several problems. 1604 To "pass-through" a :class:`classmethod`, consider using 1605 the :attr:`!__wrapped__` attribute that was added in Python 3.10. 1606 (Contributed by Raymond Hettinger in :gh:`89519`.) 1607 1608* Raise a :exc:`RuntimeError` when calling :meth:`frame.clear` 1609 on a suspended frame (as has always been the case for an executing frame). 1610 (Contributed by Irit Katriel in :gh:`79932`.) 1611 1612 1613configparser 1614------------ 1615 1616* Remove the undocumented :class:`!LegacyInterpolation` class, 1617 deprecated in the docstring since Python 3.2, 1618 and at runtime since Python 3.11. 1619 (Contributed by Hugo van Kemenade in :gh:`104886`.) 1620 1621 1622importlib.metadata 1623------------------ 1624 1625* Remove deprecated subscript (:meth:`~object.__getitem__`) access for 1626 :ref:`EntryPoint <entry-points>` objects. 1627 (Contributed by Jason R. Coombs in :gh:`113175`.) 1628 1629 1630locale 1631------ 1632 1633* Remove the :func:`!locale.resetlocale` function, deprecated in Python 3.11. 1634 Use ``locale.setlocale(locale.LC_ALL, "")`` instead. 1635 (Contributed by Victor Stinner in :gh:`104783`.) 1636 1637 1638opcode 1639------ 1640 1641* Move :attr:`!opcode.ENABLE_SPECIALIZATION` to :attr:`!_opcode.ENABLE_SPECIALIZATION`. 1642 This field was added in 3.12, it was never documented, 1643 and is not intended for external use. 1644 (Contributed by Irit Katriel in :gh:`105481`.) 1645 1646* Remove :func:`!opcode.is_pseudo`, :attr:`!opcode.MIN_PSEUDO_OPCODE`, 1647 and :attr:`!opcode.MAX_PSEUDO_OPCODE`, which were added in Python 3.12, 1648 but were neither documented nor exposed through :mod:`dis`, 1649 and were not intended to be used externally. 1650 (Contributed by Irit Katriel in :gh:`105481`.) 1651 1652 1653pathlib 1654------- 1655 1656* Remove the ability to use :class:`~pathlib.Path` objects as context managers. 1657 This functionality was deprecated and has had no effect since Python 3.9. 1658 (Contributed by Barney Gale in :gh:`83863`.) 1659 1660 1661re 1662-- 1663 1664* Remove the undocumented, deprecated, and broken 1665 :func:`!re.template` function and :attr:`!re.TEMPLATE` / :attr:`!re.T` flag. 1666 (Contributed by Serhiy Storchaka and Nikita Sobolev in :gh:`105687`.) 1667 1668 1669tkinter.tix 1670----------- 1671 1672* Remove the :mod:`!tkinter.tix` module, deprecated in Python 3.6. 1673 The third-party Tix library which the module wrapped is unmaintained. 1674 (Contributed by Zachary Ware in :gh:`75552`.) 1675 1676 1677turtle 1678------ 1679 1680* Remove the :meth:`!RawTurtle.settiltangle` method, 1681 deprecated in the documentation since Python 3.1 1682 and at runtime since Python 3.11. 1683 (Contributed by Hugo van Kemenade in :gh:`104876`.) 1684 1685 1686typing 1687------ 1688 1689* Remove the :mod:`!typing.io` and :mod:`!typing.re` namespaces, 1690 deprecated since Python 3.8. 1691 The items in those namespaces can be imported directly 1692 from the :mod:`typing` module. 1693 (Contributed by Sebastian Rittau in :gh:`92871`.) 1694 1695* Remove the keyword-argument method of creating 1696 :class:`~typing.TypedDict` types, deprecated in Python 3.11. 1697 (Contributed by Tomas Roun in :gh:`104786`.) 1698 1699 1700unittest 1701-------- 1702 1703* Remove the following :mod:`unittest` functions, deprecated in Python 3.11: 1704 1705 * :func:`!unittest.findTestCases` 1706 * :func:`!unittest.makeSuite` 1707 * :func:`!unittest.getTestCaseNames` 1708 1709 Use :class:`~unittest.TestLoader` methods instead: 1710 1711 * :meth:`~unittest.TestLoader.loadTestsFromModule` 1712 * :meth:`~unittest.TestLoader.loadTestsFromTestCase` 1713 * :meth:`~unittest.TestLoader.getTestCaseNames` 1714 1715 (Contributed by Hugo van Kemenade in :gh:`104835`.) 1716 1717* Remove the untested and undocumented :meth:`!TestProgram.usageExit` 1718 method, deprecated in Python 3.11. 1719 (Contributed by Hugo van Kemenade in :gh:`104992`.) 1720 1721 1722urllib 1723------ 1724 1725* Remove the *cafile*, *capath*, and *cadefault* parameters of the 1726 :func:`urllib.request.urlopen` function, deprecated in Python 3.6. 1727 Use the *context* parameter instead with an :class:`~ssl.SSLContext` instance. 1728 The :meth:`ssl.SSLContext.load_cert_chain` function 1729 can be used to load specific certificates, 1730 or let :func:`ssl.create_default_context` select 1731 the operating system's trusted certificate authority (CA) certificates. 1732 (Contributed by Victor Stinner in :gh:`105382`.) 1733 1734 1735webbrowser 1736---------- 1737 1738* Remove the untested and undocumented :class:`!MacOSX` class, 1739 deprecated in Python 3.11. 1740 Use the :class:`!MacOSXOSAScript` class (introduced in Python 3.2) instead. 1741 (Contributed by Hugo van Kemenade in :gh:`104804`.) 1742 1743* Remove the deprecated :attr:`!MacOSXOSAScript._name` attribute. 1744 Use the :attr:`MacOSXOSAScript.name <webbrowser.controller.name>` 1745 attribute instead. 1746 (Contributed by Nikita Sobolev in :gh:`105546`.) 1747 1748 1749New Deprecations 1750================ 1751 1752* :ref:`User-defined functions <user-defined-funcs>`: 1753 1754 * Deprecate assignment to a function's :attr:`~function.__code__` attribute, 1755 where the new code object's type does not match the function's type. 1756 The different types are: 1757 plain function, generator, async generator, and coroutine. 1758 (Contributed by Irit Katriel in :gh:`81137`.) 1759 1760* :mod:`array`: 1761 1762 * Deprecate the ``'u'`` format code (:c:type:`wchar_t`) at runtime. 1763 This format code has been deprecated in documentation since Python 3.3, 1764 and will be removed in Python 3.16. 1765 Use the ``'w'`` format code (:c:type:`Py_UCS4`) 1766 for Unicode characters instead. 1767 (Contributed by Hugo van Kemenade in :gh:`80480`.) 1768 1769* :mod:`ctypes`: 1770 1771 * Deprecate the undocumented :func:`!SetPointerType` function, 1772 to be removed in Python 3.15. 1773 (Contributed by Victor Stinner in :gh:`105733`.) 1774 1775 * :term:`Soft-deprecate <soft deprecated>` the :func:`~ctypes.ARRAY` 1776 function in favour of ``type * length`` multiplication. 1777 (Contributed by Victor Stinner in :gh:`105733`.) 1778 1779* :mod:`decimal`: 1780 1781 * Deprecate the non-standard and undocumented :class:`~decimal.Decimal` 1782 format specifier ``'N'``, 1783 which is only supported in the :mod:`!decimal` module's C implementation. 1784 (Contributed by Serhiy Storchaka in :gh:`89902`.) 1785 1786* :mod:`dis`: 1787 1788 * Deprecate the :attr:`!HAVE_ARGUMENT` separator. 1789 Check membership in :data:`~dis.hasarg` instead. 1790 (Contributed by Irit Katriel in :gh:`109319`.) 1791 1792* :mod:`getopt` and :mod:`optparse`: 1793 1794 * Both modules are now :term:`soft deprecated`, 1795 with :mod:`argparse` preferred for new projects. 1796 This is a new soft-deprecation for the :mod:`!getopt` module, 1797 whereas the :mod:`!optparse` module was already *de facto* soft deprecated. 1798 (Contributed by Victor Stinner in :gh:`106535`.) 1799 1800* :mod:`gettext`: 1801 1802 * Deprecate non-integer numbers as arguments to functions and methods 1803 that consider plural forms in the :mod:`!gettext` module, 1804 even if no translation was found. 1805 (Contributed by Serhiy Storchaka in :gh:`88434`.) 1806 1807* :mod:`glob`: 1808 1809 * Deprecate the undocumented :func:`!glob0` and :func:`!glob1` functions. 1810 Use :func:`~glob.glob` and pass a :term:`path-like object` specifying 1811 the root directory to the *root_dir* parameter instead. 1812 (Contributed by Barney Gale in :gh:`117337`.) 1813 1814* :mod:`http.server`: 1815 1816 * Deprecate :class:`~http.server.CGIHTTPRequestHandler`, 1817 to be removed in Python 3.15. 1818 Process-based CGI HTTP servers have been out of favor for a very long time. 1819 This code was outdated, unmaintained, and rarely used. 1820 It has a high potential for both security and functionality bugs. 1821 (Contributed by Gregory P. Smith in :gh:`109096`.) 1822 1823 * Deprecate the :option:`!--cgi` flag to 1824 the :program:`python -m http.server` command-line interface, 1825 to be removed in Python 3.15. 1826 (Contributed by Gregory P. Smith in :gh:`109096`.) 1827 1828* :mod:`mimetypes`: 1829 1830 * :term:`Soft-deprecate <soft deprecated>` file path arguments 1831 to :func:`~mimetypes.guess_type`, 1832 use :func:`~mimetypes.guess_file_type` instead. 1833 (Contributed by Serhiy Storchaka in :gh:`66543`.) 1834 1835* :mod:`re`: 1836 1837 * Deprecate passing the optional *maxsplit*, *count*, or *flags* arguments 1838 as positional arguments to the module-level 1839 :func:`~re.split`, :func:`~re.sub`, and :func:`~re.subn` functions. 1840 These parameters will become :ref:`keyword-only <keyword-only_parameter>` 1841 in a future version of Python. 1842 (Contributed by Serhiy Storchaka in :gh:`56166`.) 1843 1844* :mod:`pathlib`: 1845 1846 * Deprecate :meth:`.PurePath.is_reserved`, 1847 to be removed in Python 3.15. 1848 Use :func:`os.path.isreserved` to detect reserved paths on Windows. 1849 (Contributed by Barney Gale in :gh:`88569`.) 1850 1851* :mod:`platform`: 1852 1853 * Deprecate :func:`~platform.java_ver`, 1854 to be removed in Python 3.15. 1855 This function is only useful for Jython support, has a confusing API, 1856 and is largely untested. 1857 (Contributed by Nikita Sobolev in :gh:`116349`.) 1858 1859* :mod:`pydoc`: 1860 1861 * Deprecate the undocumented :func:`!ispackage` function. 1862 (Contributed by Zackery Spytz in :gh:`64020`.) 1863 1864* :mod:`sqlite3`: 1865 1866 * Deprecate passing more than one positional argument to 1867 the :func:`~sqlite3.connect` function 1868 and the :class:`~sqlite3.Connection` constructor. 1869 The remaining parameters will become keyword-only in Python 3.15. 1870 (Contributed by Erlend E. Aasland in :gh:`107948`.) 1871 1872 * Deprecate passing name, number of arguments, and the callable as keyword 1873 arguments for :meth:`.Connection.create_function` 1874 and :meth:`.Connection.create_aggregate` 1875 These parameters will become positional-only in Python 3.15. 1876 (Contributed by Erlend E. Aasland in :gh:`108278`.) 1877 1878 * Deprecate passing the callback callable by keyword for the 1879 :meth:`~sqlite3.Connection.set_authorizer`, 1880 :meth:`~sqlite3.Connection.set_progress_handler`, and 1881 :meth:`~sqlite3.Connection.set_trace_callback` 1882 :class:`~sqlite3.Connection` methods. 1883 The callback callables will become positional-only in Python 3.15. 1884 (Contributed by Erlend E. Aasland in :gh:`108278`.) 1885 1886* :mod:`sys`: 1887 1888 * Deprecate the :func:`~sys._enablelegacywindowsfsencoding` function, 1889 to be removed in Python 3.16. 1890 Use the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment variable instead. 1891 (Contributed by Inada Naoki in :gh:`73427`.) 1892 1893* :mod:`tarfile`: 1894 1895 * Deprecate the undocumented and unused :attr:`!TarFile.tarfile` attribute, 1896 to be removed in Python 3.16. 1897 (Contributed in :gh:`115256`.) 1898 1899* :mod:`traceback`: 1900 1901 * Deprecate the :attr:`.TracebackException.exc_type` attribute. 1902 Use :attr:`.TracebackException.exc_type_str` instead. 1903 (Contributed by Irit Katriel in :gh:`112332`.) 1904 1905* :mod:`typing`: 1906 1907 * Deprecate the undocumented keyword argument syntax for creating 1908 :class:`~typing.NamedTuple` classes 1909 (e.g. ``Point = NamedTuple("Point", x=int, y=int)``), 1910 to be removed in Python 3.15. 1911 Use the class-based syntax or the functional syntax instead. 1912 (Contributed by Alex Waygood in :gh:`105566`.) 1913 1914 * Deprecate omitting the *fields* parameter when creating 1915 a :class:`~typing.NamedTuple` or :class:`typing.TypedDict` class, 1916 and deprecate passing ``None`` to the *fields* parameter of both types. 1917 Python 3.15 will require a valid sequence for the *fields* parameter. 1918 To create a NamedTuple class with zero fields, 1919 use ``class NT(NamedTuple): pass`` or ``NT = NamedTuple("NT", ())``. 1920 To create a TypedDict class with zero fields, 1921 use ``class TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``. 1922 (Contributed by Alex Waygood in :gh:`105566` and :gh:`105570`.) 1923 1924 * Deprecate the :func:`typing.no_type_check_decorator` decorator function, 1925 to be removed in in Python 3.15. 1926 After eight years in the :mod:`typing` module, 1927 it has yet to be supported by any major type checker. 1928 (Contributed by Alex Waygood in :gh:`106309`.) 1929 1930 * Deprecate :data:`typing.AnyStr`. 1931 In Python 3.16, it will be removed from ``typing.__all__``, 1932 and a :exc:`DeprecationWarning` will be emitted at runtime 1933 when it is imported or accessed. 1934 It will be removed entirely in Python 3.18. 1935 Use the new :ref:`type parameter syntax <type-params>` instead. 1936 (Contributed by Michael The in :gh:`107116`.) 1937 1938* :mod:`wave`: 1939 1940 * Deprecate the :meth:`~wave.Wave_read.getmark`, :meth:`!setmark`, 1941 and :meth:`~wave.Wave_read.getmarkers` methods of 1942 the :class:`~wave.Wave_read` and :class:`~wave.Wave_write` classes, 1943 to be removed in Python 3.15. 1944 (Contributed by Victor Stinner in :gh:`105096`.) 1945 1946.. Add deprecations above alphabetically, not here at the end. 1947 1948.. include:: ../deprecations/pending-removal-in-3.14.rst 1949 1950.. include:: ../deprecations/pending-removal-in-3.15.rst 1951 1952.. include:: ../deprecations/pending-removal-in-3.16.rst 1953 1954.. include:: ../deprecations/pending-removal-in-future.rst 1955 1956CPython Bytecode Changes 1957======================== 1958 1959* The oparg of :opcode:`YIELD_VALUE` is now 1960 ``1`` if the yield is part of a yield-from or await, and ``0`` otherwise. 1961 The oparg of :opcode:`RESUME` was changed to add a bit indicating 1962 if the except-depth is 1, which is needed to optimize closing of generators. 1963 (Contributed by Irit Katriel in :gh:`111354`.) 1964 1965 1966C API Changes 1967============= 1968 1969New Features 1970------------ 1971 1972* Add the :ref:`PyMonitoring C API <c-api-monitoring>` 1973 for generating :pep:`669` monitoring events: 1974 1975 * :c:type:`PyMonitoringState` 1976 * :c:func:`PyMonitoring_FirePyStartEvent` 1977 * :c:func:`PyMonitoring_FirePyResumeEvent` 1978 * :c:func:`PyMonitoring_FirePyReturnEvent` 1979 * :c:func:`PyMonitoring_FirePyYieldEvent` 1980 * :c:func:`PyMonitoring_FireCallEvent` 1981 * :c:func:`PyMonitoring_FireLineEvent` 1982 * :c:func:`PyMonitoring_FireJumpEvent` 1983 * :c:func:`PyMonitoring_FireBranchEvent` 1984 * :c:func:`PyMonitoring_FireCReturnEvent` 1985 * :c:func:`PyMonitoring_FirePyThrowEvent` 1986 * :c:func:`PyMonitoring_FireRaiseEvent` 1987 * :c:func:`PyMonitoring_FireCRaiseEvent` 1988 * :c:func:`PyMonitoring_FireReraiseEvent` 1989 * :c:func:`PyMonitoring_FireExceptionHandledEvent` 1990 * :c:func:`PyMonitoring_FirePyUnwindEvent` 1991 * :c:func:`PyMonitoring_FireStopIterationEvent` 1992 * :c:func:`PyMonitoring_EnterScope` 1993 * :c:func:`PyMonitoring_ExitScope` 1994 1995 (Contributed by Irit Katriel in :gh:`111997`). 1996 1997* Add :c:type:`PyMutex`, a lightweight mutex that occupies a single byte, 1998 and the new :c:func:`PyMutex_Lock` and :c:func:`PyMutex_Unlock` functions. 1999 :c:func:`!PyMutex_Lock` will release the :term:`GIL` (if currently held) 2000 if the operation needs to block. 2001 (Contributed by Sam Gross in :gh:`108724`.) 2002 2003* Add the :ref:`PyTime C API <c-api-time>` to provide access to system clocks: 2004 2005 * :c:type:`PyTime_t`. 2006 * :c:var:`PyTime_MIN` and :c:var:`PyTime_MAX`. 2007 * :c:func:`PyTime_AsSecondsDouble`. 2008 * :c:func:`PyTime_Monotonic`. 2009 * :c:func:`PyTime_MonotonicRaw`. 2010 * :c:func:`PyTime_PerfCounter`. 2011 * :c:func:`PyTime_PerfCounterRaw`. 2012 * :c:func:`PyTime_Time`. 2013 * :c:func:`PyTime_TimeRaw`. 2014 2015 (Contributed by Victor Stinner and Petr Viktorin in :gh:`110850`.) 2016 2017* Add the :c:func:`PyDict_ContainsString` function 2018 with the same behavior as :c:func:`PyDict_Contains`, 2019 but *key* is specified as a :c:expr:`const char*` UTF-8 encoded bytes string, 2020 rather than a :c:expr:`PyObject*`. 2021 (Contributed by Victor Stinner in :gh:`108314`.) 2022 2023* Add the :c:func:`PyDict_GetItemRef` and :c:func:`PyDict_GetItemStringRef` 2024 functions, 2025 which behave similarly to :c:func:`PyDict_GetItemWithError`, 2026 but return a :term:`strong reference` instead of a :term:`borrowed reference`. 2027 Moreover, these functions return ``-1`` on error, 2028 removing the need to check :c:func:`!PyErr_Occurred`. 2029 (Contributed by Victor Stinner in :gh:`106004`.) 2030 2031* Add the :c:func:`PyDict_SetDefaultRef` function, 2032 which behaves similarly to :c:func:`PyDict_SetDefault`, 2033 but returns a :term:`strong reference` instead of a :term:`borrowed reference`. 2034 This function returns ``-1`` on error, 2035 ``0`` on insertion, 2036 and ``1`` if the key was already present in the dictionary. 2037 (Contributed by Sam Gross in :gh:`112066`.) 2038 2039* Add the :c:func:`PyDict_Pop` and :c:func:`PyDict_PopString` functions 2040 to remove a key from a dictionary and optionally return the removed value. 2041 This is similar to :meth:`dict.pop`, 2042 though there is no default value, 2043 and :exc:`KeyError` is not raised for missing keys. 2044 (Contributed by Stefan Behnel and Victor Stinner in :gh:`111262`.) 2045 2046* Add the :c:func:`PyMapping_GetOptionalItem` 2047 and :c:func:`PyMapping_GetOptionalItemString` functions 2048 as alternatives to :c:func:`PyObject_GetItem` 2049 and :c:func:`PyMapping_GetItemString` respectively. 2050 The new functions do not raise :exc:`KeyError` 2051 if the requested key is missing from the mapping. 2052 These variants are more convenient and faster 2053 if a missing key should not be treated as a failure. 2054 (Contributed by Serhiy Storchaka in :gh:`106307`.) 2055 2056* Add the :c:func:`PyObject_GetOptionalAttr` 2057 and :c:func:`PyObject_GetOptionalAttrString` functions 2058 as alternatives to :c:func:`PyObject_GetAttr` 2059 and :c:func:`PyObject_GetAttrString` respectively. 2060 The new functions do not raise :exc:`AttributeError` 2061 if the requested attribute is not found on the object. 2062 These variants are more convenient and faster 2063 if the missing attribute should not be treated as a failure. 2064 (Contributed by Serhiy Storchaka in :gh:`106521`.) 2065 2066* Add the :c:func:`PyErr_FormatUnraisable` function 2067 as an extension to :c:func:`PyErr_WriteUnraisable` 2068 that allows customizing the warning message. 2069 (Contributed by Serhiy Storchaka in :gh:`108082`.) 2070 2071* Add new functions that return a :term:`strong reference` instead of 2072 a :term:`borrowed reference` for frame locals, globals, and builtins, 2073 as part of :ref:`PEP 667 <whatsnew313-locals-semantics>`: 2074 2075 * :c:func:`PyEval_GetFrameBuiltins` replaces :c:func:`PyEval_GetBuiltins` 2076 * :c:func:`PyEval_GetFrameGlobals` replaces :c:func:`PyEval_GetGlobals` 2077 * :c:func:`PyEval_GetFrameLocals` replaces :c:func:`PyEval_GetLocals` 2078 2079 (Contributed by Mark Shannon and Tian Gao in :gh:`74929`.) 2080 2081* Add the :c:func:`Py_GetConstant` and :c:func:`Py_GetConstantBorrowed` 2082 functions to get :term:`strong <strong reference>` 2083 or :term:`borrowed <borrowed reference>` references to constants. 2084 For example, ``Py_GetConstant(Py_CONSTANT_ZERO)`` returns a strong reference 2085 to the constant zero. 2086 (Contributed by Victor Stinner in :gh:`115754`.) 2087 2088* Add the :c:func:`PyImport_AddModuleRef` function 2089 as a replacement for :c:func:`PyImport_AddModule` 2090 that returns a :term:`strong reference` instead of a :term:`borrowed reference`. 2091 (Contributed by Victor Stinner in :gh:`105922`.) 2092 2093* Add the :c:func:`Py_IsFinalizing` function to check 2094 whether the main Python interpreter is 2095 :term:`shutting down <interpreter shutdown>`. 2096 (Contributed by Victor Stinner in :gh:`108014`.) 2097 2098* Add the :c:func:`PyList_GetItemRef` function 2099 as a replacement for :c:func:`PyList_GetItem` 2100 that returns a :term:`strong reference` instead of a :term:`borrowed reference`. 2101 (Contributed by Sam Gross in :gh:`114329`.) 2102 2103* Add the :c:func:`PyList_Extend` and :c:func:`PyList_Clear` functions, 2104 mirroring the Python :meth:`!list.extend` and :meth:`!list.clear` methods. 2105 (Contributed by Victor Stinner in :gh:`111138`.) 2106 2107* Add the :c:func:`PyLong_AsInt` function. 2108 It behaves similarly to :c:func:`PyLong_AsLong`, 2109 but stores the result in a C :c:expr:`int` instead of a C :c:expr:`long`. 2110 (Contributed by Victor Stinner in :gh:`108014`.) 2111 2112* Add the :c:func:`PyLong_AsNativeBytes`, :c:func:`PyLong_FromNativeBytes`, 2113 and :c:func:`PyLong_FromUnsignedNativeBytes` functions 2114 to simplify converting between native integer types 2115 and Python :class:`int` objects. 2116 (Contributed by Steve Dower in :gh:`111140`.) 2117 2118* Add :c:func:`PyModule_Add` function, which is similar to 2119 :c:func:`PyModule_AddObjectRef` and :c:func:`PyModule_AddObject`, 2120 but always steals a reference to the value. 2121 (Contributed by Serhiy Storchaka in :gh:`86493`.) 2122 2123* Add the :c:func:`PyObject_GenericHash` function 2124 that implements the default hashing function of a Python object. 2125 (Contributed by Serhiy Storchaka in :gh:`113024`.) 2126 2127* Add the :c:func:`Py_HashPointer` function to hash a raw pointer. 2128 (Contributed by Victor Stinner in :gh:`111545`.) 2129 2130* Add the :c:func:`PyObject_VisitManagedDict` and 2131 :c:func:`PyObject_ClearManagedDict` functions. 2132 which must be called by the traverse and clear functions of a type using 2133 the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag. 2134 The `pythoncapi-compat project`_ can be used to 2135 use these functions with Python 3.11 and 3.12. 2136 (Contributed by Victor Stinner in :gh:`107073`.) 2137 2138* Add the :c:func:`PyRefTracer_SetTracer` 2139 and :c:func:`PyRefTracer_GetTracer` functions, 2140 which enable tracking object creation and destruction 2141 in the same way that the :mod:`tracemalloc` module does. 2142 (Contributed by Pablo Galindo in :gh:`93502`.) 2143 2144* Add the :c:func:`PySys_AuditTuple` function 2145 as an alternative to :c:func:`PySys_Audit` 2146 that takes event arguments as a Python :class:`tuple` object. 2147 (Contributed by Victor Stinner in :gh:`85283`.) 2148 2149* Add the :c:func:`PyThreadState_GetUnchecked()` function 2150 as an alternative to :c:func:`PyThreadState_Get()` 2151 that doesn't kill the process with a fatal error if it is ``NULL``. 2152 The caller is responsible for checking if the result is ``NULL``. 2153 (Contributed by Victor Stinner in :gh:`108867`.) 2154 2155* Add the :c:func:`PyType_GetFullyQualifiedName` function 2156 to get the type's fully qualified name. 2157 The module name is prepended if :attr:`type.__module__` is 2158 a string and is not equal to either ``'builtins'`` or ``'__main__'``. 2159 (Contributed by Victor Stinner in :gh:`111696`.) 2160 2161* Add the :c:func:`PyType_GetModuleName` function 2162 to get the type's module name. This is equivalent to getting the 2163 :attr:`type.__module__` attribute. 2164 (Contributed by Eric Snow and Victor Stinner in :gh:`111696`.) 2165 2166* Add the :c:func:`PyUnicode_EqualToUTF8AndSize` 2167 and :c:func:`PyUnicode_EqualToUTF8` functions 2168 to compare a Unicode object with a :c:expr:`const char*` UTF-8 encoded string 2169 and ``1`` if they are equal or ``0`` otherwise. 2170 These functions do not raise exceptions. 2171 (Contributed by Serhiy Storchaka in :gh:`110289`.) 2172 2173* Add the :c:func:`PyWeakref_GetRef` function 2174 as an alternative to :c:func:`PyWeakref_GetObject` 2175 that returns a :term:`strong reference` 2176 or ``NULL`` if the referent is no longer live. 2177 (Contributed by Victor Stinner in :gh:`105927`.) 2178 2179* Add fixed variants of functions which silently ignore errors: 2180 2181 * :c:func:`PyObject_HasAttrWithError` replaces :c:func:`PyObject_HasAttr`. 2182 * :c:func:`PyObject_HasAttrStringWithError` 2183 replaces :c:func:`PyObject_HasAttrString`. 2184 * :c:func:`PyMapping_HasKeyWithError` replaces :c:func:`PyMapping_HasKey`. 2185 * :c:func:`PyMapping_HasKeyStringWithError` 2186 replaces :c:func:`PyMapping_HasKeyString`. 2187 2188 The new functions return ``-1`` for errors 2189 and the standard ``1`` for true and ``0`` for false. 2190 2191 (Contributed by Serhiy Storchaka in :gh:`108511`.) 2192 2193 2194Changed C APIs 2195-------------- 2196 2197* The *keywords* parameter of :c:func:`PyArg_ParseTupleAndKeywords` 2198 and :c:func:`PyArg_VaParseTupleAndKeywords` 2199 now has type :c:expr:`char * const *` in C 2200 and :c:expr:`const char * const *` in C++, 2201 instead of :c:expr:`char **`. 2202 In C++, this makes these functions compatible with arguments 2203 of type :c:expr:`const char * const *`, :c:expr:`const char **`, 2204 or :c:expr:`char * const *` without an explicit type cast. 2205 In C, the functions only support arguments of type :c:expr:`char * const *`. 2206 This can be overridden with the :c:macro:`PY_CXX_CONST` macro. 2207 (Contributed by Serhiy Storchaka in :gh:`65210`.) 2208 2209* :c:func:`PyArg_ParseTupleAndKeywords` now supports 2210 non-ASCII keyword parameter names. 2211 (Contributed by Serhiy Storchaka in :gh:`110815`.) 2212 2213* The :c:func:`!PyCode_GetFirstFree` function is now unstable API 2214 and is now named :c:func:`PyUnstable_Code_GetFirstFree`. 2215 (Contributed by Bogdan Romanyuk in :gh:`115781`.) 2216 2217* The :c:func:`PyDict_GetItem`, :c:func:`PyDict_GetItemString`, 2218 :c:func:`PyMapping_HasKey`, :c:func:`PyMapping_HasKeyString`, 2219 :c:func:`PyObject_HasAttr`, :c:func:`PyObject_HasAttrString`, 2220 and :c:func:`PySys_GetObject` functions, 2221 each of which clears all errors which occurred when calling them 2222 now reports these errors using :func:`sys.unraisablehook`. 2223 You may replace them with other functions as recommended in the documentation. 2224 (Contributed by Serhiy Storchaka in :gh:`106672`.) 2225 2226* Add support for the ``%T``, ``%#T``, ``%N`` and ``%#N`` formats 2227 to :c:func:`PyUnicode_FromFormat`: 2228 2229 * ``%T``: Get the fully qualified name of an object type 2230 * ``%#T``: As above, but use a colon as the separator 2231 * ``%N``: Get the fully qualified name of a type 2232 * ``%#N``: As above, but use a colon as the separator 2233 2234 See :pep:`737` for more information. 2235 (Contributed by Victor Stinner in :gh:`111696`.) 2236 2237* You no longer have to define the ``PY_SSIZE_T_CLEAN`` macro before 2238 including :file:`Python.h` when using ``#`` formats in 2239 :ref:`format codes <arg-parsing-string-and-buffers>`. 2240 APIs accepting the format codes always use ``Py_ssize_t`` for ``#`` formats. 2241 (Contributed by Inada Naoki in :gh:`104922`.) 2242 2243* If Python is built in :ref:`debug mode <debug-build>` 2244 or :option:`with assertions <--with-assertions>`, 2245 :c:func:`PyTuple_SET_ITEM` and :c:func:`PyList_SET_ITEM` 2246 now check the index argument with an assertion. 2247 (Contributed by Victor Stinner in :gh:`106168`.) 2248 2249 2250Limited C API Changes 2251--------------------- 2252 2253* The following functions are now included in the Limited C API: 2254 2255 * :c:func:`PyMem_RawMalloc` 2256 * :c:func:`PyMem_RawCalloc` 2257 * :c:func:`PyMem_RawRealloc` 2258 * :c:func:`PyMem_RawFree` 2259 * :c:func:`PySys_Audit` 2260 * :c:func:`PySys_AuditTuple` 2261 * :c:func:`PyType_GetModuleByDef` 2262 2263 (Contributed by Victor Stinner in :gh:`85283`, :gh:`85283`, and :gh:`116936`.) 2264 2265* Python built with :option:`--with-trace-refs` (tracing references) 2266 now supports the :ref:`Limited API <limited-c-api>`. 2267 (Contributed by Victor Stinner in :gh:`108634`.) 2268 2269 2270Removed C APIs 2271-------------- 2272 2273* Remove several functions, macros, variables, etc 2274 with names prefixed by ``_Py`` or ``_PY`` (which are considered private). 2275 If your project is affected by one of these removals 2276 and you believe that the removed API should remain available, 2277 please :ref:`open a new issue <using-the-tracker>` to request a public C API 2278 and add ``cc: @vstinner`` to the issue to notify Victor Stinner. 2279 (Contributed by Victor Stinner in :gh:`106320`.) 2280 2281* Remove old buffer protocols deprecated in Python 3.0. 2282 Use :ref:`bufferobjects` instead. 2283 2284 * :c:func:`!PyObject_CheckReadBuffer`: 2285 Use :c:func:`PyObject_CheckBuffer` to test 2286 whether the object supports the buffer protocol. 2287 Note that :c:func:`PyObject_CheckBuffer` doesn't guarantee 2288 that :c:func:`PyObject_GetBuffer` will succeed. 2289 To test if the object is actually readable, 2290 see the next example of :c:func:`PyObject_GetBuffer`. 2291 2292 * :c:func:`!PyObject_AsCharBuffer`, :c:func:`!PyObject_AsReadBuffer`: 2293 Use :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead: 2294 2295 .. code-block:: c 2296 2297 Py_buffer view; 2298 if (PyObject_GetBuffer(obj, &view, PyBUF_SIMPLE) < 0) { 2299 return NULL; 2300 } 2301 // Use `view.buf` and `view.len` to read from the buffer. 2302 // You may need to cast buf as `(const char*)view.buf`. 2303 PyBuffer_Release(&view); 2304 2305 * :c:func:`!PyObject_AsWriteBuffer`: 2306 Use :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead: 2307 2308 .. code-block:: c 2309 2310 Py_buffer view; 2311 if (PyObject_GetBuffer(obj, &view, PyBUF_WRITABLE) < 0) { 2312 return NULL; 2313 } 2314 // Use `view.buf` and `view.len` to write to the buffer. 2315 PyBuffer_Release(&view); 2316 2317 (Contributed by Inada Naoki in :gh:`85275`.) 2318 2319* Remove various functions deprecated in Python 3.9: 2320 2321 * :c:func:`!PyEval_CallObject`, :c:func:`!PyEval_CallObjectWithKeywords`: 2322 Use :c:func:`PyObject_CallNoArgs` or :c:func:`PyObject_Call` instead. 2323 2324 .. warning:: 2325 2326 In :c:func:`PyObject_Call`, positional arguments must be a :class:`tuple` 2327 and must not be ``NULL``, 2328 and keyword arguments must be a :class:`dict` or ``NULL``, 2329 whereas the removed functions checked argument types 2330 and accepted ``NULL`` positional and keyword arguments. 2331 To replace ``PyEval_CallObjectWithKeywords(func, NULL, kwargs)`` with 2332 :c:func:`PyObject_Call`, 2333 pass an empty tuple as positional arguments using 2334 :c:func:`PyTuple_New(0) <PyTuple_New>`. 2335 2336 * :c:func:`!PyEval_CallFunction`: 2337 Use :c:func:`PyObject_CallFunction` instead. 2338 * :c:func:`!PyEval_CallMethod`: 2339 Use :c:func:`PyObject_CallMethod` instead. 2340 * :c:func:`!PyCFunction_Call`: 2341 Use :c:func:`PyObject_Call` instead. 2342 2343 (Contributed by Victor Stinner in :gh:`105107`.) 2344 2345* Remove the following old functions to configure the Python initialization, 2346 deprecated in Python 3.11: 2347 2348 * :c:func:`!PySys_AddWarnOptionUnicode`: 2349 Use :c:member:`PyConfig.warnoptions` instead. 2350 * :c:func:`!PySys_AddWarnOption`: 2351 Use :c:member:`PyConfig.warnoptions` instead. 2352 * :c:func:`!PySys_AddXOption`: 2353 Use :c:member:`PyConfig.xoptions` instead. 2354 * :c:func:`!PySys_HasWarnOptions`: 2355 Use :c:member:`PyConfig.xoptions` instead. 2356 * :c:func:`!PySys_SetPath`: 2357 Set :c:member:`PyConfig.module_search_paths` instead. 2358 * :c:func:`!Py_SetPath`: 2359 Set :c:member:`PyConfig.module_search_paths` instead. 2360 * :c:func:`!Py_SetStandardStreamEncoding`: 2361 Set :c:member:`PyConfig.stdio_encoding` instead, 2362 and set also maybe :c:member:`PyConfig.legacy_windows_stdio` (on Windows). 2363 * :c:func:`!_Py_SetProgramFullPath`: 2364 Set :c:member:`PyConfig.executable` instead. 2365 2366 Use the new :c:type:`PyConfig` API of the :ref:`Python Initialization 2367 Configuration <init-config>` instead (:pep:`587`), added to Python 3.8. 2368 (Contributed by Victor Stinner in :gh:`105145`.) 2369 2370* Remove :c:func:`!PyEval_AcquireLock` and :c:func:`!PyEval_ReleaseLock` functions, 2371 deprecated in Python 3.2. 2372 They didn't update the current thread state. 2373 They can be replaced with: 2374 2375 * :c:func:`PyEval_SaveThread` and :c:func:`PyEval_RestoreThread`; 2376 * low-level :c:func:`PyEval_AcquireThread` and :c:func:`PyEval_RestoreThread`; 2377 * or :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`. 2378 2379 (Contributed by Victor Stinner in :gh:`105182`.) 2380 2381* Remove the :c:func:`!PyEval_ThreadsInitialized` function, 2382 deprecated in Python 3.9. 2383 Since Python 3.7, :c:func:`!Py_Initialize` always creates the GIL: 2384 calling :c:func:`!PyEval_InitThreads` does nothing and 2385 :c:func:`!PyEval_ThreadsInitialized` always returns non-zero. 2386 (Contributed by Victor Stinner in :gh:`105182`.) 2387 2388* Remove the :c:func:`!_PyInterpreterState_Get` alias to 2389 :c:func:`PyInterpreterState_Get()` 2390 which was kept for backward compatibility with Python 3.8. 2391 The `pythoncapi-compat project`_ can be used to get 2392 :c:func:`PyInterpreterState_Get()` on Python 3.8 and older. 2393 (Contributed by Victor Stinner in :gh:`106320`.) 2394 2395* Remove the private :c:func:`!_PyObject_FastCall` function: 2396 use :c:func:`!PyObject_Vectorcall` which is available since Python 3.8 2397 (:pep:`590`). 2398 (Contributed by Victor Stinner in :gh:`106023`.) 2399 2400* Remove the ``cpython/pytime.h`` header file, 2401 which only contained private functions. 2402 (Contributed by Victor Stinner in :gh:`106316`.) 2403 2404* Remove the undocumented ``PY_TIMEOUT_MAX`` constant from the limited C API. 2405 (Contributed by Victor Stinner in :gh:`110014`.) 2406 2407* Remove the old trashcan macros ``Py_TRASHCAN_SAFE_BEGIN`` 2408 and ``Py_TRASHCAN_SAFE_END``. 2409 Replace both with the new macros ``Py_TRASHCAN_BEGIN`` 2410 and ``Py_TRASHCAN_END``. 2411 (Contributed by Irit Katriel in :gh:`105111`.) 2412 2413Deprecated C APIs 2414----------------- 2415 2416* Deprecate old Python initialization functions: 2417 2418 * :c:func:`PySys_ResetWarnOptions`: 2419 Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead. 2420 * :c:func:`Py_GetExecPrefix`: 2421 Get :data:`sys.exec_prefix` instead. 2422 * :c:func:`Py_GetPath`: 2423 Get :data:`sys.path` instead. 2424 * :c:func:`Py_GetPrefix`: 2425 Get :data:`sys.prefix` instead. 2426 * :c:func:`Py_GetProgramFullPath`: 2427 Get :data:`sys.executable` instead. 2428 * :c:func:`Py_GetProgramName`: 2429 Get :data:`sys.executable` instead. 2430 * :c:func:`Py_GetPythonHome`: 2431 Get :c:member:`PyConfig.home` 2432 or the :envvar:`PYTHONHOME` environment variable instead. 2433 2434 (Contributed by Victor Stinner in :gh:`105145`.) 2435 2436* :term:`Soft deprecate <soft deprecated>` the 2437 :c:func:`PyEval_GetBuiltins`, :c:func:`PyEval_GetGlobals`, 2438 and :c:func:`PyEval_GetLocals` functions, 2439 which return a :term:`borrowed reference`. 2440 (Soft deprecated as part of :pep:`667`.) 2441 2442* Deprecate the :c:func:`PyImport_ImportModuleNoBlock` function, 2443 which is just an alias to :c:func:`PyImport_ImportModule` since Python 3.3. 2444 (Contributed by Victor Stinner in :gh:`105396`.) 2445 2446* :term:`Soft deprecate <soft deprecated>` the 2447 :c:func:`PyModule_AddObject` function. 2448 It should be replaced with :c:func:`PyModule_Add` 2449 or :c:func:`PyModule_AddObjectRef`. 2450 (Contributed by Serhiy Storchaka in :gh:`86493`.) 2451 2452* Deprecate the old ``Py_UNICODE`` and ``PY_UNICODE_TYPE`` types 2453 and the :c:macro:`!Py_UNICODE_WIDE` define. 2454 Use the :c:type:`wchar_t` type directly instead. 2455 Since Python 3.3, ``Py_UNICODE`` and ``PY_UNICODE_TYPE`` 2456 are just aliases to :c:type:`!wchar_t`. 2457 (Contributed by Victor Stinner in :gh:`105156`.) 2458 2459* Deprecate the :c:func:`PyWeakref_GetObject` and 2460 :c:func:`PyWeakref_GET_OBJECT` functions, 2461 which return a :term:`borrowed reference`. 2462 Replace them with the new :c:func:`PyWeakref_GetRef` function, 2463 which returns a :term:`strong reference`. 2464 The `pythoncapi-compat project`_ can be used to get 2465 :c:func:`PyWeakref_GetRef` on Python 3.12 and older. 2466 (Contributed by Victor Stinner in :gh:`105927`.) 2467 2468.. Add deprecations above alphabetically, not here at the end. 2469 2470.. include:: ../deprecations/c-api-pending-removal-in-3.14.rst 2471 2472.. include:: ../deprecations/c-api-pending-removal-in-3.15.rst 2473 2474.. include:: ../deprecations/c-api-pending-removal-in-future.rst 2475 2476.. _pythoncapi-compat project: https://github.com/python/pythoncapi-compat/ 2477 2478Build Changes 2479============= 2480 2481* ``arm64-apple-ios`` and ``arm64-apple-ios-simulator`` are both 2482 now :pep:`11` tier 3 platforms. 2483 (:ref:`PEP 730 <whatsnew313-platform-support>` written 2484 and implementation contributed by Russell Keith-Magee in :gh:`114099`.) 2485 2486* ``aarch64-linux-android`` and ``x86_64-linux-android`` are both 2487 now :pep:`11` tier 3 platforms. 2488 (:ref:`PEP 738 <whatsnew313-platform-support>` written 2489 and implementation contributed by Malcolm Smith in :gh:`116622`.) 2490 2491* ``wasm32-wasi`` is now a :pep:`11` tier 2 platform. 2492 (Contributed by Brett Cannon in :gh:`115192`.) 2493 2494* ``wasm32-emscripten`` is no longer a :pep:`11` supported platform. 2495 (Contributed by Brett Cannon in :gh:`115192`.) 2496 2497* Building CPython now requires a compiler with support for the C11 atomic 2498 library, GCC built-in atomic functions, or MSVC interlocked intrinsics. 2499 2500* Autoconf 2.71 and aclocal 1.16.5 are now required to regenerate 2501 the :file:`configure` script. 2502 (Contributed by Christian Heimes in :gh:`89886` and by Victor Stinner in :gh:`112090`.) 2503 2504* SQLite 3.15.2 or newer is required to build 2505 the :mod:`sqlite3` extension module. 2506 (Contributed by Erlend Aasland in :gh:`105875`.) 2507 2508* CPython now bundles the `mimalloc library`_ by default. 2509 It is licensed under the MIT license; 2510 see :ref:`mimalloc license <mimalloc-license>`. 2511 The bundled mimalloc has custom changes, see :gh:`113141` for details. 2512 (Contributed by Dino Viehland in :gh:`109914`.) 2513 2514 .. _mimalloc library: https://github.com/microsoft/mimalloc/ 2515 2516* The :file:`configure` option :option:`--with-system-libmpdec` 2517 now defaults to ``yes``. 2518 The bundled copy of ``libmpdecimal`` will be removed in Python 3.15. 2519 2520* Python built with :file:`configure` :option:`--with-trace-refs` 2521 (tracing references) is now ABI compatible with the Python release build 2522 and :ref:`debug build <debug-build>`. 2523 (Contributed by Victor Stinner in :gh:`108634`.) 2524 2525* On POSIX systems, the pkg-config (``.pc``) filenames now include the ABI 2526 flags. For example, the free-threaded build generates ``python-3.13t.pc`` 2527 and the debug build generates ``python-3.13d.pc``. 2528 2529* The ``errno``, ``fcntl``, ``grp``, ``md5``, ``pwd``, ``resource``, 2530 ``termios``, ``winsound``, 2531 ``_ctypes_test``, ``_multiprocessing.posixshmem``, ``_scproxy``, ``_stat``, 2532 ``_statistics``, ``_testconsole``, ``_testimportmultiple`` and ``_uuid`` 2533 C extensions are now built with the :ref:`limited C API <limited-c-api>`. 2534 (Contributed by Victor Stinner in :gh:`85283`.) 2535 2536 2537Porting to Python 3.13 2538====================== 2539 2540This section lists previously described changes and other bugfixes 2541that may require changes to your code. 2542 2543Changes in the Python API 2544------------------------- 2545 2546.. _pep667-porting-notes-py: 2547 2548* :ref:`PEP 667 <whatsnew313-locals-semantics>` introduces several changes 2549 to the semantics of :func:`locals` and :attr:`f_locals <frame.f_locals>`: 2550 2551 * Calling :func:`locals` in an :term:`optimized scope` now produces an 2552 independent snapshot on each call, and hence no longer implicitly updates 2553 previously returned references. Obtaining the legacy CPython behavior now 2554 requires explicit calls to update the initially returned dictionary with the 2555 results of subsequent calls to :func:`!locals`. Code execution functions that 2556 implicitly target :func:`!locals` (such as ``exec`` and ``eval``) must be 2557 passed an explicit namespace to access their results in an optimized scope. 2558 (Changed as part of :pep:`667`.) 2559 2560 * Calling :func:`locals` from a comprehension at module or class scope 2561 (including via ``exec`` or ``eval``) once more behaves as if the comprehension 2562 were running as an independent nested function (i.e. the local variables from 2563 the containing scope are not included). In Python 3.12, this had changed 2564 to include the local variables from the containing scope when implementing 2565 :pep:`709`. (Changed as part of :pep:`667`.) 2566 2567 * Accessing :attr:`FrameType.f_locals <frame.f_locals>` in an 2568 :term:`optimized scope` now returns a write-through proxy rather than a 2569 snapshot that gets updated at ill-specified times. If a snapshot is desired, 2570 it must be created explicitly with ``dict`` or the proxy's ``.copy()`` method. 2571 (Changed as part of :pep:`667`.) 2572 2573* :class:`functools.partial` now emits a :exc:`FutureWarning` 2574 when used as a method. 2575 The behavior will change in future Python versions. 2576 Wrap it in :func:`staticmethod` if you want to preserve the old behavior. 2577 (Contributed by Serhiy Storchaka in :gh:`121027`.) 2578 2579* An :exc:`OSError` is now raised by :func:`getpass.getuser` 2580 for any failure to retrieve a username, 2581 instead of :exc:`ImportError` on non-Unix platforms 2582 or :exc:`KeyError` on Unix platforms where the password database is empty. 2583 2584* The value of the :attr:`!mode` attribute of :class:`gzip.GzipFile` 2585 is now a string (``'rb'`` or ``'wb'``) instead of an integer (``1`` or ``2``). 2586 The value of the :attr:`!mode` attribute of the readable file-like object 2587 returned by :meth:`zipfile.ZipFile.open` is now ``'rb'`` instead of ``'r'``. 2588 (Contributed by Serhiy Storchaka in :gh:`115961`.) 2589 2590* :class:`mailbox.Maildir` now ignores files with a leading dot (``.``). 2591 (Contributed by Zackery Spytz in :gh:`65559`.) 2592 2593* :meth:`pathlib.Path.glob` and :meth:`~pathlib.Path.rglob` now return both 2594 files and directories if a pattern that ends with "``**``" is given, 2595 rather than directories only. 2596 Add a trailing slash to keep the previous behavior and only match directories. 2597 2598* The :mod:`threading` module now expects the :mod:`!_thread` module 2599 to have an :func:`!_is_main_interpreter` function. 2600 This function takes no arguments and returns ``True`` 2601 if the current interpreter is the main interpreter. 2602 2603 Any library or application that provides a custom :mod:`!_thread` module 2604 must provide :func:`!_is_main_interpreter`, 2605 just like the module's other "private" attributes. 2606 (:gh:`112826`.) 2607 2608 2609Changes in the C API 2610-------------------- 2611 2612* ``Python.h`` no longer includes the ``<ieeefp.h>`` standard header. It was 2613 included for the :c:func:`!finite` function which is now provided by the 2614 ``<math.h>`` header. It should now be included explicitly if needed. Remove 2615 also the ``HAVE_IEEEFP_H`` macro. 2616 (Contributed by Victor Stinner in :gh:`108765`.) 2617 2618* ``Python.h`` no longer includes these standard header files: ``<time.h>``, 2619 ``<sys/select.h>`` and ``<sys/time.h>``. If needed, they should now be 2620 included explicitly. For example, ``<time.h>`` provides the :c:func:`!clock` and 2621 :c:func:`!gmtime` functions, ``<sys/select.h>`` provides the :c:func:`!select` 2622 function, and ``<sys/time.h>`` provides the :c:func:`!futimes`, :c:func:`!gettimeofday` 2623 and :c:func:`!setitimer` functions. 2624 (Contributed by Victor Stinner in :gh:`108765`.) 2625 2626* On Windows, ``Python.h`` no longer includes the ``<stddef.h>`` standard 2627 header file. If needed, it should now be included explicitly. For example, it 2628 provides :c:func:`!offsetof` function, and ``size_t`` and ``ptrdiff_t`` types. 2629 Including ``<stddef.h>`` explicitly was already needed by all other 2630 platforms, the ``HAVE_STDDEF_H`` macro is only defined on Windows. 2631 (Contributed by Victor Stinner in :gh:`108765`.) 2632 2633* If the :c:macro:`Py_LIMITED_API` macro is defined, :c:macro:`!Py_BUILD_CORE`, 2634 :c:macro:`!Py_BUILD_CORE_BUILTIN` and :c:macro:`!Py_BUILD_CORE_MODULE` macros 2635 are now undefined by ``<Python.h>``. 2636 (Contributed by Victor Stinner in :gh:`85283`.) 2637 2638* The old trashcan macros ``Py_TRASHCAN_SAFE_BEGIN`` and ``Py_TRASHCAN_SAFE_END`` 2639 were removed. They should be replaced by the new macros ``Py_TRASHCAN_BEGIN`` 2640 and ``Py_TRASHCAN_END``. 2641 2642 A ``tp_dealloc`` function that has the old macros, such as:: 2643 2644 static void 2645 mytype_dealloc(mytype *p) 2646 { 2647 PyObject_GC_UnTrack(p); 2648 Py_TRASHCAN_SAFE_BEGIN(p); 2649 ... 2650 Py_TRASHCAN_SAFE_END 2651 } 2652 2653 should migrate to the new macros as follows:: 2654 2655 static void 2656 mytype_dealloc(mytype *p) 2657 { 2658 PyObject_GC_UnTrack(p); 2659 Py_TRASHCAN_BEGIN(p, mytype_dealloc) 2660 ... 2661 Py_TRASHCAN_END 2662 } 2663 2664 Note that ``Py_TRASHCAN_BEGIN`` has a second argument which 2665 should be the deallocation function it is in. The new macros were 2666 added in Python 3.8 and the old macros were deprecated in Python 3.11. 2667 (Contributed by Irit Katriel in :gh:`105111`.) 2668 2669.. _pep667-porting-notes-c: 2670 2671* :ref:`PEP 667 <whatsnew313-locals-semantics>` introduces several changes 2672 to frame-related functions: 2673 2674 * The effects of mutating the dictionary returned from 2675 :c:func:`PyEval_GetLocals` in an :term:`optimized scope` have changed. 2676 New dict entries added this way will now *only* be visible to 2677 subsequent :c:func:`PyEval_GetLocals` calls in that frame, 2678 as :c:func:`PyFrame_GetLocals`, :func:`locals`, 2679 and :attr:`FrameType.f_locals <frame.f_locals>` no longer access 2680 the same underlying cached dictionary. 2681 Changes made to entries for actual variable names and names added via 2682 the write-through proxy interfaces will be overwritten on subsequent calls 2683 to :c:func:`PyEval_GetLocals` in that frame. 2684 The recommended code update depends on how the function was being used, 2685 so refer to the deprecation notice on the function for details. 2686 2687 * Calling :c:func:`PyFrame_GetLocals` in an :term:`optimized scope` 2688 now returns a write-through proxy rather than a snapshot 2689 that gets updated at ill-specified times. 2690 If a snapshot is desired, it must be created explicitly 2691 (e.g. with :c:func:`PyDict_Copy`), 2692 or by calling the new :c:func:`PyEval_GetFrameLocals` API. 2693 2694 * :c:func:`!PyFrame_FastToLocals` and :c:func:`!PyFrame_FastToLocalsWithError` 2695 no longer have any effect. 2696 Calling these functions has been redundant since Python 3.11, 2697 when :c:func:`PyFrame_GetLocals` was first introduced. 2698 2699 * :c:func:`!PyFrame_LocalsToFast` no longer has any effect. 2700 Calling this function is redundant now that :c:func:`PyFrame_GetLocals` 2701 returns a write-through proxy for :term:`optimized scopes <optimized scope>`. 2702 2703Regression Test Changes 2704======================= 2705 2706* Python built with :file:`configure` :option:`--with-pydebug` now 2707 supports a :option:`-X presite=package.module <-X>` command-line 2708 option. If used, it specifies a module that should be imported early 2709 in the lifecycle of the interpreter, before ``site.py`` is executed. 2710 (Contributed by Łukasz Langa in :gh:`110769`.) 2711 2712 2713Notable changes in 3.13.1 2714========================= 2715 2716sys 2717--- 2718 2719* The previously undocumented special function :func:`sys.getobjects`, 2720 which only exists in specialized builds of Python, may now return objects 2721 from other interpreters than the one it's called in. 2722