# Deprecations

## Pending Removal in Python 3.13

Modules (see PEP 594):

- `aifc`

- `audioop`

- `cgi`

- `cgitb`

- `chunk`

- `crypt`

- `imghdr`

- `mailcap`

- `msilib`

- `nis`

- `nntplib`

- `ossaudiodev`

- `pipes`

- `sndhdr`

- `spwd`

- `sunau`

- `telnetlib`

- `uu`

- `xdrlib`

Other modules:

- `lib2to3`, and the 2to3 program (gh-84540)

APIs:

- `configparser.LegacyInterpolation` (gh-90765)

- `locale.resetlocale()` (gh-90817)

- `turtle.RawTurtle.settiltangle()` (gh-50096)

- `unittest.findTestCases()` (gh-50096)

- `unittest.getTestCaseNames()` (gh-50096)

- `unittest.makeSuite()` (gh-50096)

- `unittest.TestProgram.usageExit()` (gh-67048)

- `webbrowser.MacOSX` (gh-86421)

- `classmethod` descriptor chaining (gh-89519)

- `importlib.resources` deprecated methods:

  - `contents()`

  - `is_resource()`

  - `open_binary()`

  - `open_text()`

  - `path()`

  - `read_binary()`

  - `read_text()`

  Use `importlib.resources.files()` instead. Refer to importlib-resources: Migrating from Legacy (gh-106531)

## Pending Removal in Python 3.14

- `argparse`: The type, choices, and metavar parameters of `argparse.BooleanOptionalAction` are deprecated and will be removed in 3.14. (Contributed by Nikita Sobolev in gh-92248.)

- `ast`: The following features have been deprecated in documentation since Python 3.8, now cause a `DeprecationWarning` to be emitted at runtime when they are accessed or used, and will be removed in Python 3.14:

  - `ast.Num`

  - `ast.Str`

  - `ast.Bytes`

  - `ast.NameConstant`

  - `ast.Ellipsis`

  Use `ast.Constant` instead. (Contributed by Serhiy Storchaka in gh-90953.)

- `asyncio`:

  - The child watcher classes `MultiLoopChildWatcher`, `FastChildWatcher`, `AbstractChildWatcher` and `SafeChildWatcher` are deprecated and will be removed in Python 3.14. (Contributed by Kumar Aditya in gh-94597.)

  - `asyncio.set_child_watcher()`, `asyncio.get_child_watcher()`, `asyncio.AbstractEventLoopPolicy.set_child_watcher()` and `asyncio.AbstractEventLoopPolicy.get_child_watcher()` are deprecated and will be removed in Python 3.14. (Contributed by Kumar Aditya in gh-94597.)

  - The `get_event_loop()` method of the default event loop policy now emits a `DeprecationWarning` if there is no current event loop set and it decides to create one. (Contributed by Serhiy Storchaka and Guido van Rossum in gh-100160.)

- `collections.abc`: Deprecated `ByteString`. Prefer `Sequence` or `Buffer`. For use in typing, prefer a union, like `bytes | bytearray`, or `collections.abc.Buffer`. (Contributed by Shantanu Jain in gh-91896.)

- `email`: Deprecated the isdst parameter in `email.utils.localtime()`. (Contributed by Alan Williams in gh-72346.)

- `importlib`: `__package__` and `__cached__` will cease to be set or taken into consideration by the import system (gh-97879).

- `importlib.abc` deprecated classes:

  - `importlib.abc.ResourceReader`

  - `importlib.abc.Traversable`

  - `importlib.abc.TraversableResources`

  Use `importlib.resources.abc` classes instead:

  - `importlib.resources.abc.Traversable`

  - `importlib.resources.abc.TraversableResources`

  (Contributed by Jason R. Coombs and Hugo van Kemenade in gh-93963.)

- `itertools` had undocumented, inefficient, historically buggy, and inconsistent support for copy, deepcopy, and pickle operations. This will be removed in 3.14 for a significant reduction in code volume and maintenance burden. (Contributed by Raymond Hettinger in gh-101588.)

- `multiprocessing`: The default start method will change to a safer one on Linux, BSDs, and other non-macOS POSIX platforms where `'fork'` is currently the default (gh-84559). Adding a runtime warning about this was deemed too disruptive as the majority of code is not expected to care. Use the `get_context()` or `set_start_method()` APIs to explicitly specify when your code requires `'fork'`. See Contexts and start methods.

- `pathlib`: `is_relative_to()` and `relative_to()`: passing additional arguments is deprecated.

- `pkgutil`: `find_loader()` and `get_loader()` now raise `DeprecationWarning`; use `importlib.util.find_spec()` instead. (Contributed by Nikita Sobolev in gh-97850.)

- `pty`:

  - `master_open()`: use `pty.openpty()`.

  - `slave_open()`: use `pty.openpty()`.

- `sqlite3`:

  - `version` and `version_info`.

  - `execute()` and `executemany()` if named placeholders are used and parameters is a sequence instead of a `dict`.

- `typing`: `ByteString`, deprecated since Python 3.9, now causes a `DeprecationWarning` to be emitted when it is used.

- `urllib`: `urllib.parse.Quoter` is deprecated: it was not intended to be a public API. (Contributed by Gregory P. Smith in gh-88168.)

## Pending Removal in Python 3.15

- `http.server.CGIHTTPRequestHandler` will be removed along with its related `--cgi` flag to `python -m http.server`. It was obsolete and rarely used. No direct replacement exists. Anything is better than CGI to interface a web server with a request handler.

- `importlib`:

  - `load_module()` method: use `exec_module()` instead.

- `locale`: `locale.getdefaultlocale()` was deprecated in Python 3.11 and originally planned for removal in Python 3.13 (gh-90817), but removal has been postponed to Python 3.15. Use `locale.setlocale()`, `locale.getencoding()` and `locale.getlocale()` instead. (Contributed by Hugo van Kemenade in gh-111187.)

- `pathlib`: `pathlib.PurePath.is_reserved()` is deprecated and scheduled for removal in Python 3.15. From Python 3.13 onwards, use `os.path.isreserved` to detect reserved paths on Windows.

- `platform`: `java_ver()` is deprecated and will be removed in 3.15. It was largely untested, had a confusing API, and was only useful for Jython support. (Contributed by Nikita Sobolev in gh-116349.)

- `sysconfig`:

  - The check_home argument of `sysconfig.is_python_build()` has been deprecated since Python 3.12.

- `threading`: Passing any arguments to `threading.RLock()` is now deprecated. C version allows any numbers of args and kwargs, but they are just ignored. Python version does not allow any arguments. All arguments will be removed from `threading.RLock()` in Python 3.15. (Contributed by Nikita Sobolev in gh-102029.)

- `typing.NamedTuple`:

  - The undocumented keyword argument syntax for creating `NamedTuple` classes (`NT = NamedTuple("NT", x=int)`) is deprecated, and will be disallowed in 3.15. Use the class-based syntax or the functional syntax instead.

- `types`:

  - `types.CodeType`: Accessing `co_lnotab` was deprecated in PEP 626 since 3.10 and was planned to be removed in 3.12, but it only got a proper `DeprecationWarning` in 3.12. May be removed in 3.15. (Contributed by Nikita Sobolev in gh-101866.)

- `typing`:

  - When using the functional syntax to create a `NamedTuple` class, failing to pass a value to the fields parameter (`NT = NamedTuple("NT")`) is deprecated. Passing `None` to the fields parameter (`NT = NamedTuple("NT", None)`) is also deprecated. Both will be disallowed in Python 3.15. To create a `NamedTuple` class with 0 fields, use `class NT(NamedTuple): pass` or `NT = NamedTuple("NT", [])`.

- `typing.TypedDict`: When using the functional syntax to create a `TypedDict` class, failing to pass a value to the fields parameter (`TD = TypedDict("TD")`) is deprecated. Passing `None` to the fields parameter (`TD = TypedDict("TD", None)`) is also deprecated. Both will be disallowed in Python 3.15. To create a `TypedDict` class with 0 fields, use `class TD(TypedDict): pass` or `TD = TypedDict("TD", {})`.

- `wave`: Deprecate the `getmark()`, `setmark()` and `getmarkers()` methods of the `wave.Wave_read` and `wave.Wave_write` classes. They will be removed in Python 3.15. (Contributed by Victor Stinner in gh-105096.)

## Pending Removal in Python 3.16

- The import system:

  - Setting `__loader__` on a module while failing to set `__spec__.loader` is deprecated. In Python 3.16, `__loader__` will cease to be set or taken into consideration by the import system or the standard library.

- `array`: `array.array` `'u'` type (`wchar_t`): use the `'w'` type instead (`Py_UCS4`).

- `builtins`: `~bool`, bitwise inversion on bool.

- `symtable`: Deprecate `symtable.Class.get_methods()` due to the lack of interest. (Contributed by Bénédikt Tran in gh-119698.)

## 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.

- `array`'s `'u'` format code (gh-57281)

- `builtins`:

  - `bool(NotImplemented)`.

  - 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`.

  - Delegation of `int()` to `__trunc__()` method.

  - 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.)

- `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.

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

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

- `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.)

- `sre_compile`, `sre_constants` and `sre_parse` modules.

- `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).

- `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()`

- `urllib.request`: `URLopener` and `FancyURLopener` style of invoking requests is deprecated. Use newer `urlopen()` functions and methods.

- `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.

- `zipimport.zipimporter.load_module()` is deprecated: use `exec_module()` instead.

## C API Deprecations

### Pending Removal in Python 3.14

- The `ma_version_tag` field in `PyDictObject` for extension modules (PEP 699; gh-101193).

- Creating `immutable types` with mutable bases (gh-95388).

- Functions to configure Python's initialization, deprecated in Python 3.11:

  - `PySys_SetArgvEx()`: Set `PyConfig.argv` instead.

  - `PySys_SetArgv()`: Set `PyConfig.argv` instead.

  - `Py_SetProgramName()`: Set `PyConfig.program_name` instead.

  - `Py_SetPythonHome()`: Set `PyConfig.home` instead.

  The `Py_InitializeFromConfig()` API should be used with `PyConfig` instead.

- Global configuration variables:

  - `Py_DebugFlag`: Use `PyConfig.parser_debug` instead.

  - `Py_VerboseFlag`: Use `PyConfig.verbose` instead.

  - `Py_QuietFlag`: Use `PyConfig.quiet` instead.

  - `Py_InteractiveFlag`: Use `PyConfig.interactive` instead.

  - `Py_InspectFlag`: Use `PyConfig.inspect` instead.

  - `Py_OptimizeFlag`: Use `PyConfig.optimization_level` instead.

  - `Py_NoSiteFlag`: Use `PyConfig.site_import` instead.

  - `Py_BytesWarningFlag`: Use `PyConfig.bytes_warning` instead.

  - `Py_FrozenFlag`: Use `PyConfig.pathconfig_warnings` instead.

  - `Py_IgnoreEnvironmentFlag`: Use `PyConfig.use_environment` instead.

  - `Py_DontWriteBytecodeFlag`: Use `PyConfig.write_bytecode` instead.

  - `Py_NoUserSiteDirectory`: Use `PyConfig.user_site_directory` instead.

  - `Py_UnbufferedStdioFlag`: Use `PyConfig.buffered_stdio` instead.

  - `Py_HashRandomizationFlag`: Use `PyConfig.use_hash_seed` and `PyConfig.hash_seed` instead.

  - `Py_IsolatedFlag`: Use `PyConfig.isolated` instead.

  - `Py_LegacyWindowsFSEncodingFlag`: Use `PyPreConfig.legacy_windows_fs_encoding` instead.

  - `Py_LegacyWindowsStdioFlag`: Use `PyConfig.legacy_windows_stdio` instead.

  - `Py_FileSystemDefaultEncoding`: Use `PyConfig.filesystem_encoding` instead.

  - `Py_HasFileSystemDefaultEncoding`: Use `PyConfig.filesystem_encoding` instead.

  - `Py_FileSystemDefaultEncodeErrors`: Use `PyConfig.filesystem_errors` instead.

  - `Py_UTF8Mode`: Use `PyPreConfig.utf8_mode` instead. (see `Py_PreInitialize()`)

  The `Py_InitializeFromConfig()` API should be used with `PyConfig` instead.

### Pending Removal in Python 3.15

- The bundled copy of `libmpdecimal`.

- The `PyImport_ImportModuleNoBlock()`: Use `PyImport_ImportModule()` instead.

- `PyWeakref_GetObject()` and `PyWeakref_GET_OBJECT()`: Use `PyWeakref_GetRef()` instead.

- `Py_UNICODE` type and the `Py_UNICODE_WIDE` macro: Use `wchar_t` instead.

- Python initialization functions:

  - `PySys_ResetWarnOptions()`: Clear `sys.warnoptions` and `warnings.filters` instead.

  - `Py_GetExecPrefix()`: Get `sys.exec_prefix` instead.

  - `Py_GetPath()`: Get `sys.path` instead.

  - `Py_GetPrefix()`: Get `sys.prefix` instead.

  - `Py_GetProgramFullPath()`: Get `sys.executable` instead.

  - `Py_GetProgramName()`: Get `sys.executable` instead.

  - `Py_GetPythonHome()`: Get `PyConfig.home` or the `PYTHONHOME` environment variable instead.

### 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_AsDecodedObject()`: Use `PyCodec_Decode()` instead.

- `PyUnicode_AsDecodedUnicode()`: Use `PyCodec_Decode()` instead.

- `PyUnicode_AsEncodedObject()`: Use `PyCodec_Encode()` instead.

- `PyUnicode_AsEncodedUnicode()`: Use `PyCodec_Encode()` 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.

- `PyDictObject.ma_version_tag` member.

- 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.