# What’s new in Python 3.16

Editor:

  TBD

This article explains the new features in Python 3.16, compared to 3.15.

For full details, see the changelog.

Observera

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

## Summary — release highlights

## New features

## Other language changes

- Frame objects now support `weak references`. This allows associating extra data with active frames, for example in debuggers, without keeping the frames (and everything they reference) alive indefinitely. (Contributed by Łukasz Langa in gh-102960.)

## New modules

- None yet.

## Improved modules

### codecs

- On platforms that provide the C library’s iconv(3) function, every encoding known to `iconv` for which Python has no built-in codec is now available (for example `cp1133`). Prefixing an encoding name with `iconv:` forces the `iconv`-based codec even when a built-in codec of the same name exists. (Contributed by Serhiy Storchaka in gh-152997.)

### curses

- The `curses` character-cell window methods now accept a full character cell — a spacing character optionally followed by combining characters — in addition to a single integer or byte character. This affects `addch()`, `bkgd()`, `bkgdset()`, `border()`, `box()`, `echochar()`, `hline()`, `insch()` and `vline()`. Also add the wide-character read methods `get_wstr()` and `in_wstr()`, the counterparts of `getstr()` and `instr()` that return a `str` rather than `bytes`, and the module functions `curses.erasewchar()`, `curses.killwchar()` and `curses.wunctrl()`, the wide-character counterparts of `curses.erasechar()`, `curses.killchar()` and `curses.unctrl()`. On a narrow (non-ncursesw) build the character cell holds a single character without combining marks, representable as one byte in the window’s encoding, and `in_wstr()` returns its decoded text. (Contributed by Serhiy Storchaka in gh-151757.)

- Add the `curses.complexchar` type, representing a styled character cell (its text, attributes and color pair), and the window methods `in_wch()` and `getbkgrnd()` that return one — the counterparts of `inch()` and `getbkgd()`. The character-cell methods, such as `addch()` and `border()`, now also accept a `complexchar`. These work whether or not Python was built against a wide-character-aware curses library; on a narrow build a cell holds a single character representable as one byte in the window’s encoding (so only 8-bit locales are supported). (Contributed by Serhiy Storchaka in gh-152233.)

- Add the `curses.complexstr` type, an immutable run of styled cells (the string counterpart of `complexchar`), and the window method `in_wchstr()` that returns one. The string-cell methods `addstr()`, `addnstr()`, `insstr()` and `insnstr()` now also accept a `complexstr`. Like `complexchar`, it works whether or not Python was built against a wide-character-aware curses library. (Contributed by Serhiy Storchaka in gh-152233.)

- The wide-character `curses` functions and methods `get_wch()`, `get_wstr()`, `curses.unget_wch()`, `curses.erasewchar()`, `curses.killwchar()` and `curses.wunctrl()` now also work when Python is not built against a wide-character-aware curses library, on an 8-bit locale, where each character is a single byte in the relevant encoding. `curses.ungetch()` now also accepts a one-character string, like `curses.unget_wch()`; on a wide-character build it can be any character (previously a multibyte character raised `OverflowError`). (Contributed by Serhiy Storchaka in gh-152470.)

- Add support for multiple terminals to the `curses` module: the new functions `curses.newterm()`, `curses.set_term()` and `curses.new_prescr()`, the corresponding screen object, and the `window.use()` method. (Contributed by Serhiy Storchaka in gh-90092.)

- Add the `curses` window methods `attr_get()`, `attr_set()`, `attr_on()`, `attr_off()` and `color_set()`, which pass the color pair as a separate argument instead of packing it into the attribute value, and the corresponding `WA_*` attribute constants. (Contributed by Serhiy Storchaka in gh-152219.)

- Add the `curses.term_attrs()` function, which returns the supported video attributes as WA_* values, the counterpart of `curses.termattrs()`. (Contributed by Serhiy Storchaka in gh-152332.)

- Add the `curses` functions `curses.alloc_pair()`, `curses.find_pair()`, `curses.free_pair()` and `curses.reset_color_pairs()` for dynamic color-pair management, available when built against a wide-character ncurses with extended-color support. (Contributed by Serhiy Storchaka in gh-151774.)

- Add the `curses` functions `scr_dump()`, `scr_restore()`, `scr_init()` and `scr_set()`, which dump the whole screen to a file and restore it. (Contributed by Serhiy Storchaka in gh-152260.)

- Add the `curses` window method `dupwin()`, which returns a new window that is an independent duplicate of an existing one. (Contributed by Serhiy Storchaka in gh-152258.)

- Add the soft-label-key functions to the `curses` module, which manage a row of labels along the bottom line of the screen: `slk_init()`, `slk_set()`, `slk_label()`, `slk_refresh()`, `slk_noutrefresh()`, `slk_clear()`, `slk_restore()`, `slk_touch()`, the attribute functions `slk_attron()`, `slk_attroff()`, `slk_attrset()`, `slk_attr()`, `slk_attr_on()`, `slk_attr_off()`, `slk_attr_set()`, and `slk_color()`. (Contributed by Serhiy Storchaka in gh-152263.)

- Add the `curses` key-management functions `define_key()`, `key_defined()` and `keyok()`, available when built against an ncurses with `NCURSES_EXT_FUNCS`. (Contributed by Serhiy Storchaka in gh-152334.)

- Add the `curses.has_mouse()` function and the `curses.window.mouse_trafo()` method, completing the `curses` mouse interface. (Contributed by Serhiy Storchaka in gh-152325.)

- Add `curses` functions and window methods that report state which could previously only be set, such as `curses.window.is_keypad()`, `curses.window.getparent()` and `curses.is_cbreak()`, available when built against an ncurses with `NCURSES_EXT_FUNCS`. (Contributed by Serhiy Storchaka in gh-151776.)

- Add `curses.nofilter()`, which undoes the effect of `curses.filter()`. (Contributed by Serhiy Storchaka in gh-151744.)

- `curses.textpad.Textbox` now supports entering and reading back the full Unicode range, including combining characters, when curses is built with wide-character support. (Contributed by Serhiy Storchaka in gh-133031.)

### ctypes

- Add `ctypes.util.struct()` for generating `Structure` types from an annotation-based syntax, similar to how the `dataclasses` module is used. (Contributed by Peter Bierma in gh-104533.)

- Add `ctypes.util.wrap_dll_function()` for generating function pointers through a function signature. (Contributed by Peter Bierma in gh-153903.)

### encodings

- Add the `utf-7-imap` codec, implementing the modified UTF-7 encoding used for international IMAP4 mailbox names (RFC 3501). (Contributed by Serhiy Storchaka in gh-66788.)

### gzip

- `gzip.open()` now accepts an optional argument `mtime` which is passed on to the constructor of the `GzipFile` class. (Contributed by Marin Misur in gh-91372.)

### io

- Add `io.BytesIO.peek()` method to read without advancing position. (Contributed by Marcel Martin in gh-90533.)

### imaplib

- Add the `id()` method, a wrapper for the `ID` command (RFC 2971). (Contributed by Serhiy Storchaka in gh-98092.)

- Add the `move()` method, a wrapper for the `MOVE` command (RFC 6851). (Contributed by Serhiy Storchaka in gh-77508.)

- Add the `login_plain()` method, which authenticates using the `PLAIN` SASL mechanism (RFC 4616) and supports non-ASCII user names and passwords. (Contributed by Przemysław Buczkowski and Serhiy Storchaka in gh-89869.)

- Non-ASCII mailbox names are now automatically encoded as modified UTF-7 (RFC 3501, section 5.1.3) in the default mode, so international mailbox names can be passed as ordinary `str` without enabling `UTF8=ACCEPT` (under which they are sent as UTF-8). (Contributed by Serhiy Storchaka in gh-49555.)

- The `copy()`, `move()`, `fetch()`, `store()`, `search()`, `sort()`, `thread()` and `expunge()` methods now accept a keyword-only uid argument that selects the corresponding `UID` command, as a more convenient alternative to `uid()`. (Contributed by Serhiy Storchaka in gh-153502.)

- `search()`, `sort()` and `thread()` (and the corresponding `uid` commands) now encode `str` search criteria to the declared charset, so international search text can be passed as an ordinary `str`. When charset is `None` (as it must be under `UTF8=ACCEPT`), the criteria are sent using the connection encoding instead. (Contributed by Serhiy Storchaka in gh-153494.)

- Command methods now accept structured arguments, so the module takes care of quoting instead of the caller. A message_set and lists of flags or other atoms can be passed as sequences instead of preformatted strings, and the `search()`, `fetch()`, `sort()`, `thread()` and `uid()` methods accept a params keyword argument that substitutes and quotes `?` placeholders, in the manner of `sqlite3` parameter substitution. (Contributed by Serhiy Storchaka in gh-153521.)

### ipaddress

Add `next_network()` and `next_network()` methods to find the next nearest network with a specific prefix size.

### logging

- `TimedRotatingFileHandler` now uses the creation time instead of the last modification time of an existing log file as the basis for the first rotation after handler creation, if supported by the OS and file system. This allows it to be used in short-running programs that start and end before the rotation interval expires. (Contributed by Iván Márton and Serhiy Storchaka in gh-84649.)

### lzma

- Add support of new BCJ filters ARM64 and RISC-V via `lzma.FILTER_ARM64` and `lzma.FILTER_RISCV`. Note that the new filters will work only if the runtime library supports them. ARM64 filter requires `lzma` 5.4.0 or newer while RISC-V requires 5.6.0 or newer. (Contributed by Chien Wong in gh-115988.)

### math

- Added trigonometric functions that work in units of half turns, rather than radians. The new functions `math.acospi()`, `math.asinpi()`, `math.atanpi()`, and `math.atan2pi()` return half-turn angles. The new functions `math.cospi()`, `math.sinpi()`, and `math.tanpi()` take half-turn angle arguments. These functions are recommended by IEEE 754-2019 and standardized in C23. (Contributed by Jeff Epler in gh-150534.)

### os

- Add `os.pidfd_getfd()` for duplicating a file descriptor from another process via a pidfd. Available on Linux 5.6+. (Contributed by Maurycy Pawłowski-Wieroński in gh-149464.)

### pydoc

- Modernize the HTML output of `pydoc`. The pages generated by the `pydoc` HTTP server now use semantic HTML5 markup and a new style sheet based on the python-docs-theme used by docs.python.org, with dark mode support. Class members inherited from other classes are collapsed by default. (Contributed by Serhiy Storchaka in gh-153906.)

### re

- `re` now supports set operations and nested sets in character classes, as described in Unicode Technical Standard #18: set difference (`[A--B]`), intersection (`[A&&B]`) and union (`[A||B]`), where an operand may be a nested set written in square brackets. For example, `[a-z--[aeiou]]` matches an ASCII lowercase consonant. (Contributed by Serhiy Storchaka in gh-152100.)

- Regular expressions now support Unicode property escapes `\p{...}` and `\P{...}`, which match a character by a Unicode property – for example `\p{Lu}` (an uppercase letter), `\p{Cased}` or `\p{ASCII}`. See the regular expression syntax for the supported properties. (Contributed by Serhiy Storchaka in gh-95555.)

### shlex

- Add keyword-only parameter force to `shlex.quote()` to force quoting a string, even if it is already safe for a shell without being quoted. (Contributed by Jay Berry in gh-148846.)

### symtable

- `symtable.symtable()` now accepts an AST object, like the builtin `compile()`. (Contributed by Serhiy Storchaka in gh-153844.)

### tkinter

- Added many `tkinter.ttk.Treeview` methods wrapping the enhanced `ttk::treeview` widget commands from Tk 9.1, such as `sort()`, `search()`, `expand()`, `collapse()`, `hide()`, `unhide()`, and methods for cell focus, selection and tagging. The `expand()` and `collapse()` methods (without recursion) also work on Tk older than 9.1. (Contributed by Serhiy Storchaka in gh-151910.)

- Added new `tkinter.Text` methods `edit_canundo()` and `edit_canredo()` which return whether an undo or redo is possible. (Contributed by Serhiy Storchaka in gh-151674.)

- Added new `tkinter.Text` methods `sync()` and `pendingsync()` which control and report the synchronization of the displayed view with the underlying text. (Contributed by Serhiy Storchaka in gh-151675.)

- Added the `ttk.Style.theme_styles` method which returns the list of styles defined in a theme. (Contributed by Serhiy Storchaka in gh-151920.)

- Added new `tkinter.Canvas` methods `rchars()` which replaces the text or coordinates of canvas items, and `rotate()` which rotates the coordinates of canvas items. (Contributed by Serhiy Storchaka in gh-151876.)

- Added a `validate()` method to the `tkinter.Entry` and `tkinter.Spinbox` widgets, which forces an evaluation of the validation command. (Contributed by Serhiy Storchaka in gh-151878.)

- Added the `tkinter.Menu.postcascade()` method, and the `tk_scaling()` and `tk_inactive()` methods which respectively query or set the display scaling factor and report the user idle time. (Contributed by Serhiy Storchaka in gh-151881.)

- Added the `tk_print()` method to `tkinter.Canvas` and `tkinter.Text` which prints the contents of the widget using the native print dialog. It requires Tk 8.7/9.0 or newer. (Contributed by Serhiy Storchaka in gh-153256.)

- Added new window-management methods `winfo_isdark()` (dark mode detection), `wm_iconbadge()` (application icon badge) and `wm_stackorder()` (toplevel stacking order). (Contributed by Serhiy Storchaka in gh-151874.)

- Added the `tk_appname()`, `tk_useinputmethods()` and `tk_caret()` methods, exposing the application send name, the X Input Methods state and the input method caret location. (Contributed by Serhiy Storchaka in gh-151886.)

- Added support for more options in `tkinter.PhotoImage` methods: the format parameter of `put()`, the metadata parameter of `put()`, `read()`, `write()` and `data()`, and the withalpha parameter of `get()`. (Contributed by Serhiy Storchaka in gh-151890.)

- Added the `redither()` method which recalculates the dithered image when its data was supplied in pieces. (Contributed by Serhiy Storchaka in gh-151888.)

- `tkinter.OptionMenu` now accepts arbitrary `tkinter.Menubutton` options as keyword arguments, which can also override its default appearance. (Contributed by Serhiy Storchaka in gh-101284.)

- The `tkinter.simpledialog` dialogs were modernized to match the look and feel of the native Tk dialogs. `tkinter.simpledialog.SimpleDialog` and the `askinteger()`, `askfloat()` and `askstring()` dialogs are now built from the themed `tkinter.ttk` widgets instead of the classic `tkinter` widgets; the `tkinter.simpledialog.Dialog` base class still defaults to the classic widgets for compatibility. Both `Dialog` and `SimpleDialog` gained a use_ttk parameter that selects between the classic Tk widgets and the themed ttk widgets. `SimpleDialog` also gained bitmap and detail parameters, draws the standard icons with themed images in the ttk version, and accepts mappings of button options as buttons entries. (Contributed by Serhiy Storchaka in gh-59396.)

- The `tkinter.filedialog.FileDialog` dialog and its `tkinter.filedialog.LoadFileDialog` and `tkinter.filedialog.SaveFileDialog` subclasses are now built from the themed `tkinter.ttk` widgets by default instead of the classic `tkinter` widgets, and gained a use_ttk parameter to select between them. (Contributed by Serhiy Storchaka in gh-59396.)

- Added the `tkinter.systray` module which provides the `SysTrayIcon` class as an interface to the system tray icon and the `notify()` function which sends a desktop notification. They require Tk 8.7/9.0 or newer. (Contributed by Serhiy Storchaka in gh-153259.)

- `tkinter.scrolledtext.ScrolledText` gained a use_ttk parameter to use the themed `tkinter.ttk` frame and scroll bar instead of the classic `tkinter` widgets. (Contributed by Serhiy Storchaka in gh-59396.)

- `tkinter.font.Font` can now wrap a font description without creating a new named font, by passing it as font with `exists=True` and no name. This avoids a loss of precision in `actual()`, `measure()` and `metrics()`. (Contributed by Serhiy Storchaka in gh-143990.)

- Added the `tkinter.fontchooser` module which provides the `FontChooser` class as an interface to the native font selection dialog. (Contributed by Serhiy Storchaka in gh-72880.)

- Values of several Tcl object types returned by `tkinter` are now converted to the corresponding Python type instead of being wrapped in a `_tkinter.Tcl_Obj`: `index`, `window`, `nsName` and `parsedVarName` objects to `str`, and `pixel` screen distances with no unit suffix to `int` or `float`. (Contributed by Serhiy Storchaka in gh-153513.)

### xml

- Add support for multiple multi-byte encodings in the `XML parser`: ”cp932”, ”cp949”, ”cp950”, ”Big5”, ”EUC-JP”, ”GB2312”, ”GBK”, ”johab”, and ”Shift_JIS”. Add partial support (only BMP characters) for multi-byte encodings ”Big5-HKSCS”, ”EUC_JIS-2004”, ”EUC_JISX0213”, ”Shift_JIS-2004”, ”Shift_JISX0213”, ”utf-8-sig” and non-standard aliases like ”UTF8” (without hyphen). The parser now raises `ValueError` for known unsupported multi-byte encodings such as ”ISO-2022-JP” or ”raw-unicode-escape” instead of failing later, when encountering non-ASCII data. (Contributed by Serhiy Storchaka in gh-62259.)

### zipfile

- Add `ZipFile.remove()` to remove a member from an archive’s central directory, and `ZipFile.repack()` to reclaim the space used by the local file entries of removed members. (Contributed by Danny Lin in gh-51067.)

## Optimizations

### re

- Character class escapes (`\d`, `\D`, `\s`, `\S`, `\w` and `\W`) outside a character set, and character sets containing a single such escape (such as `[\d]` or `[^\s]`), are now compiled to a single `CATEGORY` opcode instead of being wrapped in an `IN` block. This speeds up matching of patterns such as `\d+` and reduces the size of the compiled byte code. (Contributed by Serhiy Storchaka in gh-152033 and Pieter Eendebak in gh-152056.)

### module_name

- TODO

## Removed

### annotationlib

- The `annotationlib.ForwardRef._evaluate()` method which has been deprecated since Python 3.14. Use `annotationlib.ForwardRef.evaluate()` or `typing.evaluate_forward_ref()` instead.

### array

- The `'u'` format code (`wchar_t`) which has been deprecated in documentation since Python 3.3 and at runtime since Python 3.13. Use `'w'` format code instead (`Py_UCS4`, always 4 bytes).

### asyncio

- The `asyncio.iscoroutinefunction()` which has been deprecated since Python 3.14. Use `inspect.iscoroutinefunction()` instead.

- The event loop policy system, including the `asyncio.AbstractEventLoopPolicy`, `asyncio.DefaultEventLoopPolicy`, `asyncio.WindowsSelectorEventLoopPolicy` and `asyncio.WindowsProactorEventLoopPolicy` classes and the `asyncio.get_event_loop_policy()` and `asyncio.set_event_loop_policy()` functions, which have been deprecated since Python 3.14. Use `asyncio.run()` or `asyncio.Runner` with a custom loop_factory instead.

### functools

- Calling the Python implementation of `functools.reduce()` with function or sequence as keyword arguments has been deprecated since Python 3.14.

### logging

- Support for custom logging handlers with the strm argument is deprecated and scheduled for removal in Python 3.16. Define handlers with the stream argument instead.

### mimetypes

- Valid extensions start with a ’.’ or are empty for `mimetypes.MimeTypes.add_type()`. Undotted extensions now raise a `ValueError`.

### shutil

- The `ExecError` exception which has been deprecated since Python 3.14. It has not been used by any function in `shutil` since Python 3.4. (Contributed by Stan Ulbrych in gh-149567.)

### symtable

- The `symtable.Class.get_methods()` method which has been deprecated since Python 3.14.

### sys

- The `_enablelegacywindowsfsencoding()` function which has been deprecated since Python 3.13. Use the `PYTHONLEGACYWINDOWSFSENCODING` environment variable instead. (Contributed by Stan Ulbrych in gh-149595.)

### sysconfig

- The `sysconfig.expand_makefile_vars()` function which has been deprecated since Python 3.14. Use the `vars` argument of `sysconfig.get_paths()` instead. (Contributed by Stan Ulbrych in gh-149499.)

### tarfile

- The undocumented and unused `tarfile.TarFile.tarfile` attribute has been deprecated since Python 3.13.

## Deprecated

### New deprecations

- `abc`

  - Soft-deprecated since Python 3.3 `abc.abstractclassmethod`, `abc.abstractstaticmethod`, and `abc.abstractproperty` now raise a `DeprecationWarning`. These classes will be removed in Python 3.21, instead use `abc.abstractmethod()` with `classmethod()`, `staticmethod()`, and `property` respectively.

- `ast`:

  - Classes `slice`, `Index`, `ExtSlice`, `Suite`, `Param`, `AugLoad` and `AugStore`, deprecated since Python 3.9, are no longer imported by `from ast import *` and issue a deprecation warning on use. The classes are slated for removal in Python 3.21. These types are not generated by the parser or accepted by the code generator.

  - The `dims` property of `ast.Tuple` objects, deprecated since Python 3.9, now issues a deprecation warning on use. This property is slated for removal in 3.21. Use `ast.Tuple.elts` instead.

- `struct`:

  - Soft-deprecated since Python 3.15, using `'F'` and `'D'` type codes are now deprecated. These codes will be removed in Python 3.21. Use instead two-letter forms `'Zf'` and `'Zd'`. (Contributed by Sergey B Kirpichev in gh-121249.)

- `tempfile`

  - The private `tempfile._TemporaryFileWrapper` name is deprecated and is slated for removal in Python 3.21. Use the new public `tempfile.TemporaryFileWrapper` instead, which is the return type of `tempfile.NamedTemporaryFile()`.

- `tkinter`:

  - `tkinter.filedialog.askopenfiles()` is deprecated and slated for removal in Python 3.19. Opening several files at once is error-prone, and the returned list cannot be used in a `with` statement. Iterate over the names returned by `askopenfilenames()` and open them one by one instead. (Contributed by Serhiy Storchaka in gh-152638.)

### Pending removal in Python 3.17

- `datetime`:

  - `strptime()` calls using a format string containing `%e` (day of month) without a year. This has been deprecated since Python 3.15. (Contributed by Stan Ulbrych in gh-70647.)

- `collections.abc`:

  - `collections.abc.ByteString` is scheduled for removal in Python 3.17.

    Use `isinstance(obj, collections.abc.Buffer)` to test if `obj` implements the buffer protocol at runtime. For use in type annotations, either use `Buffer` or a union that explicitly specifies the types your code supports (e.g., `bytes | bytearray | memoryview`).

    `ByteString` was originally intended to be an abstract class that would serve as a supertype of both `bytes` and `bytearray`. However, since the ABC never had any methods, knowing that an object was an instance of `ByteString` never actually told you anything useful about the object. Other common buffer types such as `memoryview` were also never understood as subtypes of `ByteString` (either at runtime or by static type checkers).

    See PEP 688 for more details. (Contributed by Shantanu Jain in gh-91896.)

- `encodings`:

  - Passing non-ascii encoding names to `encodings.normalize_encoding()` is deprecated and scheduled for removal in Python 3.17. (Contributed by Stan Ulbrych in gh-136702.)

- `webbrowser`:

  - `webbrowser.MacOSXOSAScript` is deprecated in favour of `webbrowser.MacOS`. (gh-137586)

- `typing`:

  - Before Python 3.14, old-style unions were implemented using the private class `typing._UnionGenericAlias`. This class is no longer needed for the implementation, but it has been retained for backward compatibility, with removal scheduled for Python 3.17. Users should use documented introspection helpers like `typing.get_origin()` and `typing.get_args()` instead of relying on private implementation details.

  - `typing.ByteString`, deprecated since Python 3.9, is scheduled for removal in Python 3.17.

    Use `isinstance(obj, collections.abc.Buffer)` to test if `obj` implements the buffer protocol at runtime. For use in type annotations, either use `Buffer` or a union that explicitly specifies the types your code supports (e.g., `bytes | bytearray | memoryview`).

    `ByteString` was originally intended to be an abstract class that would serve as a supertype of both `bytes` and `bytearray`. However, since the ABC never had any methods, knowing that an object was an instance of `ByteString` never actually told you anything useful about the object. Other common buffer types such as `memoryview` were also never understood as subtypes of `ByteString` (either at runtime or by static type checkers).

    See PEP 688 for more details. (Contributed by Shantanu Jain in gh-91896.)

- `tkinter`:

  - The `tkinter.Variable` methods `trace_variable()`, `trace()` (an alias of `trace_variable()`), `trace_vdelete()` and `trace_vinfo()`, deprecated since Python 3.14, are scheduled for removal in Python 3.17. Use `trace_add()`, `trace_remove()` and `trace_info()` instead. (Contributed by Serhiy Storchaka in gh-120220.)

### Pending removal in Python 3.18

- No longer accept a boolean value when a file descriptor is expected. (Contributed by Serhiy Storchaka in gh-82626.)

- `decimal`:

  - The non-standard and undocumented `Decimal` format specifier `'N'`, which is only supported in the `decimal` module’s C implementation, has been deprecated since Python 3.13. (Contributed by Serhiy Storchaka in gh-89902.)

- Deprecations defined by PEP 829:

  - `import` lines in `name.pth` files are silently ignored.

  (Contributed by Barry Warsaw in gh-148641.)

### Pending removal in Python 3.19

- `ctypes`:

  - Implicitly switching to the MSVC-compatible struct layout by setting `_pack_` but not `_layout_` on non-Windows platforms.

- `hashlib`:

  - In hash function constructors such as `new()` or the direct hash-named constructors such as `md5()` and `sha256()`, their optional initial data parameter could also be passed a keyword argument named `data=` or `string=` in various `hashlib` implementations.

    Support for the `string` keyword argument name is now deprecated and slated for removal in Python 3.19.

    Before Python 3.13, the `string` keyword parameter was not correctly supported depending on the backend implementation of hash functions. Prefer passing the initial data as a positional argument for maximum backwards compatibility.

- `http.cookies`:

  - `http.cookies.Morsel.js_output()` is deprecated and will be removed in Python 3.19.

  - `http.cookies.BaseCookie.js_output()` is deprecated and will be removed in Python 3.19.

- `imaplib`:

  - Altering `IMAP4.file` is now deprecated and slated for removal in Python 3.19. This property is now unused and changing its value does not automatically close the current file.

    Before Python 3.14, this property was used to implement the corresponding `read()` and `readline()` methods for `IMAP4` but this is no longer the case since then.

- `tkinter`:

  - `tkinter.filedialog.askopenfiles()` has been deprecated since Python 3.16. Iterate over the names returned by `askopenfilenames()` and open them one by one instead. (Contributed by Serhiy Storchaka in gh-152638.)

### Pending removal in Python 3.20

- Calling the `__new__()` method of `struct.Struct` without the format argument is deprecated and will be removed in Python 3.20. Calling `__init__()` method on initialized `Struct` objects is deprecated and will be removed in Python 3.20.

  (Contributed by Sergey B Kirpichev and Serhiy Storchaka in gh-143715.)

- The `__version__`, `version` and `VERSION` attributes have been deprecated in these standard library modules and will be removed in Python 3.20. Use `sys.version_info` instead.

  - `argparse`

  - `csv`

  - `ctypes`

  - `ctypes.macholib`

  - `decimal` (use `decimal.SPEC_VERSION` instead)

  - `http.server`

  - `imaplib`

  - `ipaddress`

  - `json`

  - `logging` (`__date__` also deprecated)

  - `optparse`

  - `pickle`

  - `platform`

  - `re`

  - `socketserver`

  - `tabnanny`

  - `tarfile`

  - `tkinter.font`

  - `tkinter.ttk`

  - `wsgiref.simple_server`

  - `xml.etree.ElementTree`

  - `xml.sax.expatreader`

  - `xml.sax.handler`

  - `zlib`

  (Contributed by Hugo van Kemenade and Stan Ulbrych in gh-76007.)

- Deprecations defined by PEP 829:

  - Warnings are produced for `import` lines found in `name.pth` files.

  - `name.pth` files are no longer decoded in the locale encoding by default. They MUST be encoded in `utf-8-sig`.

  (Contributed by Barry Warsaw in gh-148641.)

- `ast`:

  - Creating instances of abstract AST nodes (such as `ast.AST` or `ast.expr`) is deprecated and will raise an error in Python 3.20.

### Pending removal in Python 3.21

- `abc`

  > - Soft-deprecated since Python 3.3 `abc.abstractclassmethod`, `abc.abstractstaticmethod`, and `abc.abstractproperty` now raise a `DeprecationWarning`. These classes will be removed in Python 3.21, instead use `abc.abstractmethod()` with `classmethod()`, `staticmethod()`, and `property` respectively.

- `ast`:

  - Classes `slice`, `Index`, `ExtSlice`, `Suite`, `Param`, `AugLoad` and `AugStore`, will be removed in Python 3.21. These types are not generated by the parser or accepted by the code generator.

  - The `dims` property of `ast.Tuple` will be removed in Python 3.21. Use the `ast.Tuple.elts` property instead.

- `struct`:

  - Soft-deprecated since Python 3.15, using `'F'` and `'D'` type codes are now deprecated. These codes will be removed in Python 3.21. Use instead two-letter forms `'Zf'` and `'Zd'`.

- `tempfile`:

  - `tempfile._TemporaryFileWrapper` will be removed in Python 3.21. Use the public `tempfile.TemporaryFileWrapper` instead.

### Pending removal in future versions

The following APIs will be removed in the future, although there is currently no date scheduled for their removal.

- `argparse`:

  - Nesting argument groups and nesting mutually exclusive groups are deprecated.

  - Passing the undocumented keyword argument prefix_chars to `add_argument_group()` is now deprecated.

  - The `argparse.FileType` type converter is deprecated.

- `builtins`:

  - Generators: `throw(type, exc, tb)` and `athrow(type, exc, tb)` signature is deprecated: use `throw(exc)` and `athrow(exc)` instead, the single argument signature.

  - Currently Python accepts numeric literals immediately followed by keywords, for example `0in x`, `1or x`, `0if 1else 2`. It allows confusing and ambiguous expressions like `[0x1for x in y]` (which can be interpreted as `[0x1 for x in y]` or `[0x1f or x in y]`). A syntax warning is raised if the numeric literal is immediately followed by one of keywords `and`, `else`, `for`, `if`, `in`, `is` and `or`. In a future release it will be changed to a syntax error. (gh-87999)

  - Support for `__index__()` and `__int__()` method returning non-int type: these methods will be required to return an instance of a strict subclass of `int`.

  - Support for `__float__()` method returning a strict subclass of `float`: these methods will be required to return an instance of `float`.

  - Support for `__complex__()` method returning a strict subclass of `complex`: these methods will be required to return an instance of `complex`.

  - Passing a complex number as the real or imag argument in the `complex()` constructor is now deprecated; it should only be passed as a single positional argument. (Contributed by Serhiy Storchaka in gh-109218.)

- `calendar`: `calendar.January` and `calendar.February` constants are deprecated and replaced by `calendar.JANUARY` and `calendar.FEBRUARY`. (Contributed by Prince Roshan in gh-103636.)

- `codecs`: use `open()` instead of `codecs.open()`. (gh-133038)

- `codeobject.co_lnotab`: use the `codeobject.co_lines()` method instead.

- `datetime`:

  - `utcnow()`: use `datetime.datetime.now(tz=datetime.UTC)`.

  - `utcfromtimestamp()`: use `datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)`.

- `gettext`: Plural value must be an integer.

- `importlib`:

  - `cache_from_source()` debug_override parameter is deprecated: use the optimization parameter instead.

- `importlib.metadata`:

  - `EntryPoints` tuple interface.

  - Implicit `None` on return values.

- `logging`: the `warn()` method has been deprecated since Python 3.3, use `warning()` instead.

- `mailbox`: Use of StringIO input and text mode is deprecated, use BytesIO and binary mode instead.

- `os`: Calling `os.register_at_fork()` in a multi-threaded process.

- `os.path`: `os.path.commonprefix()` is deprecated, use `os.path.commonpath()` for path prefixes. The `os.path.commonprefix()` function is being deprecated due to having a misleading name and module. The function is not safe to use for path prefixes despite being included in a module about path manipulation, meaning it is easy to accidentally introduce path traversal vulnerabilities into Python programs by using this function.

- `pydoc.ErrorDuringImport`: A tuple value for exc_info parameter is deprecated, use an exception instance.

- `re`: More strict rules are now applied for numerical group references and group names in regular expressions. Only sequence of ASCII digits is now accepted as a numerical reference. The group name in bytes patterns and replacement strings can now only contain ASCII letters and digits and underscore. (Contributed by Serhiy Storchaka in gh-91760.)

- `shutil`: `rmtree()`’s onerror parameter is deprecated in Python 3.12; use the onexc parameter instead.

- `ssl` options and protocols:

  - `ssl.SSLContext` without protocol argument is deprecated.

  - `ssl.SSLContext`: `set_npn_protocols()` and `selected_npn_protocol()` are deprecated: use ALPN instead.

  - `ssl.OP_NO_SSL*` options

  - `ssl.OP_NO_TLS*` options

  - `ssl.PROTOCOL_SSLv3`

  - `ssl.PROTOCOL_TLS`

  - `ssl.PROTOCOL_TLSv1`

  - `ssl.PROTOCOL_TLSv1_1`

  - `ssl.PROTOCOL_TLSv1_2`

  - `ssl.TLSVersion.SSLv3`

  - `ssl.TLSVersion.TLSv1`

  - `ssl.TLSVersion.TLSv1_1`

- `threading` methods:

  - `threading.Condition.notifyAll()`: use `notify_all()`.

  - `threading.Event.isSet()`: use `is_set()`.

  - `threading.Thread.isDaemon()`, `threading.Thread.setDaemon()`: use `threading.Thread.daemon` attribute.

  - `threading.Thread.getName()`, `threading.Thread.setName()`: use `threading.Thread.name` attribute.

  - `threading.currentThread()`: use `threading.current_thread()`.

  - `threading.activeCount()`: use `threading.active_count()`.

- `typing.Text` (gh-92332).

- The internal class `typing._UnionGenericAlias` is no longer used to implement `typing.Union`. To preserve compatibility with users using this private class, a compatibility shim will be provided until at least Python 3.17. (Contributed by Jelle Zijlstra in gh-105499.)

- `unittest.IsolatedAsyncioTestCase`: it is deprecated to return a value that is not `None` from a test case.

- `urllib.parse` deprecated functions: `urlparse()` instead

  - `splitattr()`

  - `splithost()`

  - `splitnport()`

  - `splitpasswd()`

  - `splitport()`

  - `splitquery()`

  - `splittag()`

  - `splittype()`

  - `splituser()`

  - `splitvalue()`

  - `to_bytes()`

- `wsgiref`: `SimpleHandler.stdout.write()` should not do partial writes.

- `xml.etree.ElementTree`: Testing the truth value of an `Element` is deprecated. In a future release it will always return `True`. Prefer explicit `len(elem)` or `elem is not None` tests instead.

- `sys._clear_type_cache()` is deprecated: use `sys._clear_internal_caches()` instead.

## Porting to Python 3.16

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

- In `tkinter`, the name parameter of the `wait_variable()`, `setvar()` and `getvar()` methods and the value parameter of `setvar()` are now required. Calling these methods without them, which formerly defaulted to `'PY_VAR'` and `'1'`, now raises `TypeError`. (Contributed by Serhiy Storchaka in gh-152587.)

## Build changes

- Remove the bundled copy of the libmpdec decimal library from the CPython source tree to simplify maintenance and updates. The `decimal` module will now unconditionally use the system’s libmpdec decimal library. Also remove the now unused `--with-system-libmpdec` configure flag. This change has no impact on binary releases of Python, which have been built against a separate copy of libmpdec for the past several releases.

  (Contributed by Sergey B Kirpichev in gh-115119.)

- Add a `--with-build-details-suffix` configure flag to allow Linux distributions that co-install multiple versions of Python in the same tree to avoid `build-details.json` clashes.

  (Contributed by Stefano Rivera in gh-131372.)

- Add the `--with-curses` configure option to select the curses backend for the `curses` and `curses.panel` modules. In addition to `ncursesw` and `ncurses`, it can now build against the system’s native `curses` library (for example on NetBSD or Solaris), with wide-character support when the library provides it. `--without-curses` excludes the modules from the build.

  (Contributed by Serhiy Storchaka in gh-136687.)

## C API changes

### New features

- TODO

### Porting to Python 3.16

- TODO

### Deprecated C APIs

- `PyGen_New()`, `PyGen_NewWithQualName()`, `PyCoro_New()`, and `PyAsyncGen_New()` are deprecated. They are scheduled for removal in 3.18.

#### Pending removal in Python 3.18

- The following private functions are deprecated and planned for removal in Python 3.18:

  - `_PyBytes_Join()`: use `PyBytes_Join()`.

  - `_PyDict_GetItemStringWithError()`: use `PyDict_GetItemStringRef()`.

  - `_PyDict_Pop()`: use `PyDict_Pop()`.

  - `_PyLong_Sign()`: use `PyLong_GetSign()`.

  - `_PyLong_FromDigits()` and `_PyLong_New()`: use `PyLongWriter_Create()`.

  - `_PyThreadState_UncheckedGet()`: use `PyThreadState_GetUnchecked()`.

  - `_PyUnicode_AsString()`: use `PyUnicode_AsUTF8()`.

  - `_PyUnicodeWriter_Init()`: replace `_PyUnicodeWriter_Init(&writer)` with `writer = PyUnicodeWriter_Create(0)`.

  - `_PyUnicodeWriter_Finish()`: replace `_PyUnicodeWriter_Finish(&writer)` with `PyUnicodeWriter_Finish(writer)`.

  - `_PyUnicodeWriter_Dealloc()`: replace `_PyUnicodeWriter_Dealloc(&writer)` with `PyUnicodeWriter_Discard(writer)`.

  - `_PyUnicodeWriter_WriteChar()`: replace `_PyUnicodeWriter_WriteChar(&writer, ch)` with `PyUnicodeWriter_WriteChar(writer, ch)`.

  - `_PyUnicodeWriter_WriteStr()`: replace `_PyUnicodeWriter_WriteStr(&writer, str)` with `PyUnicodeWriter_WriteStr(writer, str)`.

  - `_PyUnicodeWriter_WriteSubstring()`: replace `_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)` with `PyUnicodeWriter_WriteSubstring(writer, str, start, end)`.

  - `_PyUnicodeWriter_WriteASCIIString()`: replace `_PyUnicodeWriter_WriteASCIIString(&writer, str)` with `PyUnicodeWriter_WriteASCII(writer, str)`.

  - `_PyUnicodeWriter_WriteLatin1String()`: replace `_PyUnicodeWriter_WriteLatin1String(&writer, str)` with `PyUnicodeWriter_WriteUTF8(writer, str)`.

  - `_PyUnicodeWriter_Prepare()`: (no replacement).

  - `_PyUnicodeWriter_PrepareKind()`: (no replacement).

  - `_Py_HashPointer()`: use `Py_HashPointer()`.

  - `_Py_fopen_obj()`: use `Py_fopen()`.

  - `PyGen_New()`: (no replacement).

  - `PyGen_NewWithQualName()`: (no replacement).

  - `PyCoro_New()`: (no replacement).

  - `PyAsyncGen_New()`: (no replacement).

  The pythoncapi-compat project can be used to get these new public functions on Python 3.13 and older. (Contributed by Victor Stinner in gh-128863.)

#### Pending removal in Python 3.19

- PEP 456 embedders support for the string hashing scheme definition.

#### Pending removal in Python 3.20

- `_PyObject_CallMethodId()`, `_PyObject_GetAttrId()` and `_PyUnicode_FromId()` are deprecated since 3.15 and will be removed in 3.20. Instead, use `PyUnicode_InternFromString()` and cache the result in the module state, then call `PyObject_CallMethod()` or `PyObject_GetAttr()`. (Contributed by Victor Stinner in gh-141049.)

- The `cval` field in `PyComplexObject` (gh-128813). Use `PyComplex_AsCComplex()` and `PyComplex_FromCComplex()` to convert a Python complex number to/from the C `Py_complex` representation.

- Macros `Py_MATH_PIl` and `Py_MATH_El`.

#### Pending removal in future versions

The following APIs are deprecated and will be removed, although there is currently no date scheduled for their removal.

- `Py_TPFLAGS_HAVE_FINALIZE`: Unneeded since Python 3.8.

- `PyErr_Fetch()`: Use `PyErr_GetRaisedException()` instead.

- `PyErr_NormalizeException()`: Use `PyErr_GetRaisedException()` instead.

- `PyErr_Restore()`: Use `PyErr_SetRaisedException()` instead.

- `PyModule_GetFilename()`: Use `PyModule_GetFilenameObject()` instead.

- `PyOS_AfterFork()`: Use `PyOS_AfterFork_Child()` instead.

- `PySlice_GetIndicesEx()`: Use `PySlice_Unpack()` and `PySlice_AdjustIndices()` instead.

- `PyUnicode_READY()`: Unneeded since Python 3.12

- `PyErr_Display()`: Use `PyErr_DisplayException()` instead.

- `_PyErr_ChainExceptions()`: Use `_PyErr_ChainExceptions1()` instead.

- `PyBytesObject.ob_shash` member: call `PyObject_Hash()` instead.

- Thread Local Storage (TLS) API:

  - `PyThread_create_key()`: Use `PyThread_tss_alloc()` instead.

  - `PyThread_delete_key()`: Use `PyThread_tss_free()` instead.

  - `PyThread_set_key_value()`: Use `PyThread_tss_set()` instead.

  - `PyThread_get_key_value()`: Use `PyThread_tss_get()` instead.

  - `PyThread_delete_key_value()`: Use `PyThread_tss_delete()` instead.

  - `PyThread_ReInitTLS()`: Unneeded since Python 3.7.

### Removed C APIs