# 弃用

## 计划在 Python 3.13 中移除

模块 (参见 PEP 594):

- `aifc`

- `audioop`

- `cgi`

- `cgitb`

- `chunk`

- `crypt`

- `imghdr`

- `mailcap`

- `msilib`

- `nis`

- `nntplib`

- `ossaudiodev`

- `pipes`

- `sndhdr`

- `spwd`

- `sunau`

- `telnetlib`

- `uu`

- `xdrlib`

其他模块：

- `lib2to3`，以及 2to3 程序 (gh-84540)

API:

- `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` 描述器串联 (gh-89519)

- `importlib.resources` 中已弃用的方法：

  - `contents()`

  - `is_resource()`

  - `open_binary()`

  - `open_text()`

  - `path()`

  - `read_binary()`

  - `read_text()`

  改用 `importlib.resources.files()`。 参见 importlib-resources: Migrating from Legacy (gh-106531)

## 计划在 Python 3.14 中移除

- `argparse`: `argparse.BooleanOptionalAction` 的 type, choices 和 metavar 形参已被弃用并将在 3.14 中移除。 （由 Nikita Sobolev 在 gh-92248 中贡献。）

- `ast`: 以下特性自 Python 3.8 起已在文档中声明弃用，现在当运行时如果它们被访问或使用时将发出 `DeprecationWarning`，并将在 Python 3.14 中移除：

  - `ast.Num`

  - `ast.Str`

  - `ast.Bytes`

  - `ast.NameConstant`

  - `ast.Ellipsis`

  请改用 `ast.Constant`。 （由 Serhiy Storchaka 在 gh-90953 中贡献。）

- `asyncio`:

  - 子监视器类 `MultiLoopChildWatcher`, `FastChildWatcher`, `AbstractChildWatcher` 和 `SafeChildWatcher` 已被弃用并将在 Python 3.14 中移除。 （由 Kumar Aditya 在 gh-94597 中贡献。）

  - `asyncio.set_child_watcher()`、`asyncio.get_child_watcher()`、`asyncio.AbstractEventLoopPolicy.set_child_watcher()` 和 `asyncio.AbstractEventLoopPolicy.get_child_watcher()` 已弃用，并将在 Python 3.14 中移除。（由 Kumar Aditya 在 gh-94597 中贡献。）

  - 现在默认事件循环策略的 `get_event_loop()` 方法在当前事件循环未设置并决定创建一个时将发出 `DeprecationWarning`。 （由 Serhiy Storchaka 和 Guido van Rossum 在 gh-100160 中贡献。）

- `collections.abc`: 已弃用 `ByteString`。 推荐改用 `Sequence` 或 `Buffer`。 用于类型标注时，则推荐并集运算符，如 `bytes | bytearray`，或 `collections.abc.Buffer`。 （由 Shantanu Jain 在 gh-91896 中贡献。）

- `email`: 已弃用 `email.utils.localtime()` 中的 isdst 形参。 （由 Alan Williams 在 gh-72346 中贡献。）

- `importlib`: `__package__` 和 `__cached__` 将不再被设置或是被导入系统纳入考量 (gh-97879)。

- `importlib.abc` 中已弃用的类：

  - `importlib.abc.ResourceReader`

  - `importlib.abc.Traversable`

  - `importlib.abc.TraversableResources`

  使用 `importlib.resources.abc` 类代替:

  - `importlib.resources.abc.Traversable`

  - `importlib.resources.abc.TraversableResources`

  （由 Jason R. Coombs 和 Hugo van Kemenade 在 gh-93963 中贡献。）

- `itertools` 具有对 copy, deepcopy 和 pickle 等操作的未写入文档的、低效的、历史上充满问题的且不稳定的支持。 这将在 3.14 中移除以显著减少代码量和维护负担。 （由 Raymond Hettinger 在 gh-101588 中贡献。）

- `multiprocessing`: 默认的启动方法在目前默认使用 `'fork'` 的 Linux, BSD 和其他非 macOS POSIX 平台上将改为更安全的方法 (gh-84559)。 为此添加运行时警告将带来糟糕的体验因为大部分代码并不会关心这个问题。 当你的代码 需要 `'fork'` 时请使用 `get_context()` 或 `set_start_method()` API 来显式地指明。 参见 上下文和启动方法。

- `pathlib`: `is_relative_to()` 和 `relative_to()`: 传入额外参数的做法已被弃用。

- `pkgutil`: 现在 `find_loader()` 和 `get_loader()` 将引发 `DeprecationWarning`；请改用 `importlib.util.find_spec()`。 （由 Nikita Sobolev 在 gh-97850 中贡献。）

- `pty`:

  - `master_open()`: 使用 `pty.openpty()`。

  - `slave_open()`: 使用 `pty.openpty()`。

- `sqlite3`:

  - `version` 和 `version_info`。

  - 如果使用了 命名占位符 且 parameters 是一个序列而不是 `dict` 则选择 `execute()` 和 `executemany()`。

- `typing`: `ByteString` 自 Python 3.9 起已被弃用，现在当被使用时将会发出 `DeprecationWarning`。

- `urllib`: `urllib.parse.Quoter` 已被弃用：它不应被作为公有 API。 （由 Gregory P. Smith 在 gh-88168 中贡献。）

## Python 3.15 中的待移除功能

- `http.server.CGIHTTPRequestHandler` 将同 `python -m http.server` 中与其相关的 `--cgi` 旗标一起被移除。 它已经过时并且很少被使用。 不存在直接的替代品。 对于建立 Web 服务器与请求处理器的接口的任务来说 任何东西 都比 CGI 要好。

- `importlib`:

  - `load_module()` 方法：改用 `exec_module()`。

- `locale`: `locale.getdefaultlocale()` 在 Python 3.11 中已被弃用并且原计划在 Python 3.13 中移除 (gh-90817)，但移除时间已被推迟至 Python 3.15。 请改用 `locale.setlocale()`, `locale.getencoding()` 和 `locale.getlocale()`。 （由 Hugo van Kemenade 在 gh-111187 中贡献。）

- `pathlib`：`pathlib.PurePath.is_reserved()` 已被弃用，并计划在 Python 3.15 中移除。从 Python 3.13 起，请在 Windows 上使用``os.path.isreserved`` 检测保留路径。

- `platform`: `java_ver()` 已被弃用并将在 3.15 中移除。 它几乎未经测试，具有令人困惑的 API，并且仅适用于 Jython 支持。 （由 Nikita Sobolev 在 gh-116349 中贡献。）

- `sysconfig`:

  - `sysconfig.is_python_build()` 的 check_home 参数自 Python 3.12 起已被弃用。

- `threading`: 向 `threading.RLock()` 传入任意参数的做法现已被弃用。 C 版本允许任意数量的 args 和 kwargs，但它们都会被忽略。 Python 版本不允许任何参数。 在 Python 3.15 中将从 `threading.RLock()` 移除所有参数。 （由 Nikita Sobolev 在 gh-102029 中贡献。）

- `typing.NamedTuple`:

  - 创建 `NamedTuple` 类 (`NT = NamedTuple("NT", x=int)`) 的关键字参数语法从未写入文档且已被弃用，并将在 3.15 中被禁止。 请改用基于类的语法或函数语法。

- `types`:

  - `types.CodeType`: 访问 `co_lnotab` 的做法自 3.10 起已根据 PEP 626 被弃用并曾计划在 3.12 中移除，但在 3.12 中实际仅设置了 `DeprecationWarning`。 可能会在 3.15 中移除。 （由 Nikita Sobolev 在 gh-101866 中贡献。）

- `typing`:

  - 当使用函数式语法创建 `NamedTuple` 类时，不向 fields 形参传值的做法 (`NT = NamedTuple("NT")`) 已被弃用。 将 `None` 传给 fields 形参的做法 (`NT = NamedTuple("NT", None)`) 也已被弃用。 两者都将在 Python 3.15 中被禁止。 要创建拥有 0 个字段的 `NamedTuple` 类，请使用 `class NT(NamedTuple): pass` 或 `NT = NamedTuple("NT", [])`。

- `typing.TypedDict`: 当使用函数语法创建 `TypedDict` 类时，不向 fields 形参传值 (`TD = TypedDict("TD")`) 的行为已被弃用。 将 `None` 传给 fields 形参 (`TD = TypedDict("TD", None)`) 的行为也已被弃用。 两者都将在 Python 3.15 中被禁止。 要创建拥有 0 个字段的 `TypedDict` 类，请使用 `class TD(TypedDict): pass` 或 `TD = TypedDict("TD", {})`。

- `wave`: 已弃用 `wave.Wave_read` 和 `wave.Wave_write` 类的 `getmark()`, `setmark()` 和 `getmarkers()` 方法。 它们将在 Python 3.15 中被移除。 （由 Victor Stinner 在 gh-105096 中贡献。）

## 计划在 Python 3.16 中移除

- 导入系统：

  - 当设置 `__spec__.loader` 失败时在模块上设置 `__loader__` 的做法已被弃用。 在 Python 3.16 中，`__loader__` 将不会再被设置或是被导入系统或标准库纳入考虑。

- `array`: `array.array` `'u'` 类型 (`wchar_t`): 改用 `'w'` 类型 (`Py_UCS4`)。

- `builtins`: `~bool`，对布尔值按位取反。

- `symtable`: `symtable.Class.get_methods()` 因缺少适当的场景已被弃用。 （由 Bénédikt Tran 在 gh-119698 中贡献。）

## 计划在未来版本中移除

以下API将会被移除，尽管具体时间还未确定。

- `argparse`: 嵌套参数分组和嵌套互斥分组的做法已被弃用。

- `array` 的 `'u'` 格式代码 (gh-57281)

- `builtins`:

  - `bool(NotImplemented)`。

  - 生成器: `throw(type, exc, tb)` 和 `athrow(type, exc, tb)` 签名已被弃用：请改用 `throw(exc)` 和 `athrow(exc)`，即单参数签名。

  - 目前 Python 接受数字类字面值后面紧跟关键字的写法，例如 `0in x`, `1or x`, `0if 1else 2`。 它允许像 `[0x1for x in y]` 这样令人困惑且有歧义的表达式 (它可以被解读为 `[0x1 for x in y]` 或者 `[0x1f or x in y]`)。 如果数字类字面值后面紧跟关键字 `and`, `else`, `for`, `if`, `in`, `is` 和 `or` 中的一个将会引发语法警告。 在未来的版本中它将改为语法错误。 (gh-87999)

  - 对 `__index__()` 和 `__int__()` 方法返回非 int 类型的支持：将要求这些方法必须返回 `int` 的子类的实例。

  - 对 `__float__()` 方法返回 `float` 的子类的支持：将要求这些方法必须返回 `float` 的实例。

  - 对 `__complex__()` 方法返回 `complex` 的子类的支持：将要求这些方法必须返回 `complex` 的实例。

  - 将 `int()` 委托给 `__trunc__()` 方法。

  - 传入一个复数作为 `complex()` 构造器中的 real 或 imag 参数的做法现在已被弃用；它应当仅作为单个位置参数被传入。 （由 Serhiy Storchaka 在 gh-109218 中贡献。）.)

- `calendar`: `calendar.January` 和 `calendar.February` 常量已被弃用并由 `calendar.JANUARY` 和 `calendar.FEBRUARY` 替代。 （由 Prince Roshan 在 gh-103636 中贡献。）

- `codeobject.co_lnotab`: 改用 `codeobject.co_lines()` 方法。

- `datetime`:

  - `utcnow()`: 使用 `datetime.datetime.now(tz=datetime.UTC)`。

  - `utcfromtimestamp()`: 使用 `datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)`。

- `gettext`: 复数值必须是一个整数。

- `importlib`:

  - `cache_from_source()` debug_override 形参已被弃用：改用 optimization 形能耐。

- `importlib.metadata`:

  - `EntryPoints` 元组接口。

  - 返回值中隐式的 `None`。

- `mailbox`: 对 StringIO 输入和文本模式的使用已被弃用，改用 BytesIO 和二进制模式。

- `os`: 在多线程的进程中调用 `os.register_at_fork()`。

- `pydoc.ErrorDuringImport`: 使用元组值作为 exc_info 形参的做法已被弃用，应使用异常实例。

- `re`: 现在对于正则表达式中的数字分组引用和分组名称将应用更严格的规则。 现在只接受 ASCII 数字序列作为数字引用。 字节串模式和替换字符串中的分组名称现在只能包含 ASCII 字母和数字以及下划线。 （由 Serhiy Storchaka 在 gh-91760 中贡献。）

- `sre_compile`, `sre_constants` 和 `sre_parse` 模块。

- `shutil`: `rmtree()` 的 onerror 形参在 Python 3.12 中已被弃用；请改用 onexc 形参。

- `ssl` 选项和协议：

  - `ssl.SSLContext` 不带 protocol 参数的做法已被弃用。

  - `ssl.SSLContext`: `set_npn_protocols()` 和 `selected_npn_protocol()` 已被弃用：请改用 ALPN.

  - `ssl.OP_NO_SSL*` 选项

  - `ssl.OP_NO_TLS*` 选项

  - `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` 的方法：

  - `threading.Condition.notifyAll()`: 使用 `notify_all()`。

  - `threading.Event.isSet()`: 使用 `is_set()`。

  - `threading.Thread.isDaemon()`, `threading.Thread.setDaemon()`: 使用 `threading.Thread.daemon` 属性。

  - `threading.Thread.getName()`, `threading.Thread.setName()`: 使用 `threading.Thread.name` 属性。

  - `threading.currentThread()`: 使用 `threading.current_thread()`。

  - `threading.activeCount()`: 使用 `threading.active_count()`。

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

- `unittest.IsolatedAsyncioTestCase`: 从测试用例返回不为 `None` 的值的做法已被弃用。

- `urllib.parse` 函数已被弃用：改用 `urlparse()`

  - `splitattr()`

  - `splithost()`

  - `splitnport()`

  - `splitpasswd()`

  - `splitport()`

  - `splitquery()`

  - `splittag()`

  - `splittype()`

  - `splituser()`

  - `splitvalue()`

  - `to_bytes()`

- `urllib.request`: 发起请求的 `URLopener` 和 `FancyURLopener` 方式已被弃用。 改用更新 `urlopen()` 函数和方法。

- `wsgiref`: `SimpleHandler.stdout.write()` 不应执行部分写入。

- `xml.etree.ElementTree`: 对 `Element` 的真值测试已被弃用。 在未来的发布版中它将始终返回 `True`。 建议改用显式的 `len(elem)` 或 `elem is not None` 测试。

- `zipimport.zipimporter.load_module()` 已被弃用：请改用 `exec_module()`。

## C API 的弃用项

### 计划在 Python 3.14 中移除

- `PyDictObject` 中的 `ma_version_tag` 字段用于扩展模块 ( PEP 699 ; gh-101193 )。

- 创建 `immutable types` 的可变基础 ( gh-95388 )。

- 用于配置 Python 的初始化的函数，在 Python 3.11 中已弃用：

  - `PySys_SetArgvEx()`: 改为设置 `PyConfig.argv`。

  - `PySys_SetArgv()`: 改为设置 `PyConfig.argv`。

  - `Py_SetProgramName()`: 改为设置 `PyConfig.program_name`。

  - `Py_SetPythonHome()`: 改为设置 `PyConfig.home`。

  `Py_InitializeFromConfig()` API 应与 `PyConfig` 一起使用。

- 全局配置变量：

  - `Py_DebugFlag`: 改用 `PyConfig.parser_debug`。

  - `Py_VerboseFlag`: 改用 `PyConfig.verbose`。

  - `Py_QuietFlag`: 改用 `PyConfig.quiet`。

  - `Py_InteractiveFlag`: 改用 `PyConfig.interactive`。

  - `Py_InspectFlag`: 改用 `PyConfig.inspect`。

  - `Py_OptimizeFlag`: 改用 `PyConfig.optimization_level`。

  - `Py_NoSiteFlag`: 改用 `PyConfig.site_import`。

  - `Py_BytesWarningFlag`: 改用 `PyConfig.bytes_warning`。

  - `Py_FrozenFlag`: 改用 `PyConfig.pathconfig_warnings`。

  - `Py_IgnoreEnvironmentFlag`: 改用 `PyConfig.use_environment`。

  - `Py_DontWriteBytecodeFlag`: 改用 `PyConfig.write_bytecode`。

  - `Py_NoUserSiteDirectory`: 改用 `PyConfig.user_site_directory`。

  - `Py_UnbufferedStdioFlag`: 改用 `PyConfig.buffered_stdio`。

  - `Py_HashRandomizationFlag`: 改用 `PyConfig.use_hash_seed` 和 `PyConfig.hash_seed`。

  - `Py_IsolatedFlag`: 改用 `PyConfig.isolated`。

  - `Py_LegacyWindowsFSEncodingFlag`: 改用 `PyPreConfig.legacy_windows_fs_encoding`。

  - `Py_LegacyWindowsStdioFlag`: 改用 `PyConfig.legacy_windows_stdio`。

  - `Py_FileSystemDefaultEncoding`: 改用 `PyConfig.filesystem_encoding`。

  - `Py_HasFileSystemDefaultEncoding`: 改用 `PyConfig.filesystem_encoding`。

  - `Py_FileSystemDefaultEncodeErrors`: 改用 `PyConfig.filesystem_errors`。

  - `Py_UTF8Mode`: 改用 `PyPreConfig.utf8_mode`。 (参见 `Py_PreInitialize()`)

  `Py_InitializeFromConfig()` API 应与 `PyConfig` 一起使用。

### Python 3.15 中的待移除功能

- 捆绑的 `libmpdecimal` 副本。

- The `PyImport_ImportModuleNoBlock()`: 改用 `PyImport_ImportModule()`。

- `PyWeakref_GetObject()` 和 `PyWeakref_GET_OBJECT()`：改用 `PyWeakref_GetRef()`。

- `Py_UNICODE` 类型和 `Py_UNICODE_WIDE` 宏：改用 `wchar_t`。

- Python 初始化函数

  - `PySys_ResetWarnOptions()`: 改为清除 `sys.warnoptions` 和 `warnings.filters`。

  - `Py_GetExecPrefix()`: 改为获取 `sys.exec_prefix`。

  - `Py_GetPath()`: 改为获取 `sys.path`。

  - `Py_GetPrefix()`: 改为获取 `sys.prefix`。

  - `Py_GetProgramFullPath()`: 改为获取 `sys.executable`。

  - `Py_GetProgramName()`: 改为获取 `sys.executable`。

  - `Py_GetPythonHome()`: 改为获取 `PyConfig.home` 或 `PYTHONHOME` 环境变量。

### 计划在未来版本中移除

以下 API 已被弃用，将被移除，但目前尚未确定移除日期。

- `Py_TPFLAGS_HAVE_FINALIZE`: 自 Python 3.8 起不再需要。

- `PyErr_Fetch()`: 改用 `PyErr_GetRaisedException()`。

- `PyErr_NormalizeException()`: 改用 `PyErr_GetRaisedException()`。

- `PyErr_Restore()`: 改用 `PyErr_SetRaisedException()`。

- `PyModule_GetFilename()`: 改用 `PyModule_GetFilenameObject()`。

- `PyOS_AfterFork()`: 改用 `PyOS_AfterFork_Child()`。

- `PySlice_GetIndicesEx()`: 改用 `PySlice_Unpack()` and `PySlice_AdjustIndices()`。

- `PyUnicode_AsDecodedObject()`: 改用 `PyCodec_Decode()`。

- `PyUnicode_AsDecodedUnicode()`: 改用 `PyCodec_Decode()`。

- `PyUnicode_AsEncodedObject()`: 改用 `PyCodec_Encode()`。

- `PyUnicode_AsEncodedUnicode()`: 改用 `PyCodec_Encode()`。

- `PyUnicode_READY()`: 自 Python 3.12 起不再需要

- `PyErr_Display()`: 改用 `PyErr_DisplayException()`。

- `_PyErr_ChainExceptions()`: 改用 `_PyErr_ChainExceptions1()`。

- `PyBytesObject.ob_shash` 成员：改为调用 `PyObject_Hash()`。

- `PyDictObject.ma_version_tag` 成员。

- 线程本地存储 (TLS) API：

  - `PyThread_create_key()`: 改用 `PyThread_tss_alloc()`。

  - `PyThread_delete_key()`: 改用 `PyThread_tss_free()`。

  - `PyThread_set_key_value()`: 改用 `PyThread_tss_set()`。

  - `PyThread_get_key_value()`: 改用 `PyThread_tss_get()`。

  - `PyThread_delete_key_value()`: 改用 `PyThread_tss_delete()`。

  - `PyThread_ReInitTLS()`: 自 Python 3.7 起不再需要。