# 弃用

## 计划在 Python 3.15 中移除

- 导入系统：

  - 当设置 `__spec__.cached` 失败时在模块上设置 `__cached__` 的做法已被弃用。 在 Python 3.15 中，`__cached__` 将不会再被导入系统或标准库设置或纳入其考量。 (gh-97879)

  - 当设置 `__spec__.parent` 失败时在模块上设置 `__package__` 的做法已被弃用。在 Python 3.15 中，`__package__` 将不会再被导入系统或标准库纳入考虑。 (gh-97879)

- `ctypes`:

  - 未写入文档的 `ctypes.SetPointerType()` 函数自 Python 3.13 起已被弃用。

- `http.server`:

  - 过时且很少被使用的 `CGIHTTPRequestHandler` 自 Python 3.13 起已被弃用。 不存在直接的替代品。 对于建立带有请求处理器的 Web 服务器接口 任何东西 都比 CGI 强。

  - 用于 python -m http.server 命令行界面的 `--cgi` 旗标自 Python 3.13 起已被弃用。

- `importlib`:

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

- `pathlib`:

  - `.PurePath.is_reserved()` 自 Python 3.13 起已被弃用。 请使用 `os.path.isreserved()` 来检测 Windows 上的保留路径。

- `platform`:

  - `platform.java_ver()` 自 Python 3.13 起已被弃用。 此函数仅对 Jython 支持有用，具有令人困惑的 API，并且大部分未经测试。

- `sysconfig`:

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

- `threading`:

  - `RLock()` will take no arguments in Python 3.15. Passing any arguments has been deprecated since Python 3.14, as the Python version does not permit any arguments, but the C version allows any number of positional or keyword arguments, ignoring every argument.

- `types`:

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

- `typing`:

  - 未写入文档的用于创建 `NamedTuple` 类的关键字参数语法 (例如 `Point = NamedTuple("Point", x=int, y=int)`) 自 Python 3.13 起已被弃用。 请改用基于类的语法或函数语法。

  - 当使用 `TypedDict` 的函数式语法时，不向 fields 形参传递值 (`TD = TypedDict("TD")`) 或传递 `None` (`TD = TypedDict("TD", None)`) 的做法自 Python 3.13 起已被弃用。请改用 `class TD(TypedDict): pass` 或 `TD = TypedDict("TD", {})` 来创建一个零字段的 TypedDict。

  - `typing.no_type_check_decorator()` 装饰器自 Python 3.13 起已被弃用。 存在于 `typing` 模块八年之后，它仍未被任何主要类型检查器所支持。

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

- `wave`:

  - `Wave_read` 和 `Wave_write` 类的 `getmark()`, `setmark()` 和 `getmarkers()` 方法自 Python 3.13 起已被弃用。

- `zipimport`:

  - `zipimport.zipimporter.load_module()` 自 Python 3.10 起已被弃用。 请改用 `exec_module()`。 (gh-125746。)

## 计划在 Python 3.16 中移除

- 导入系统：

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

- `array`:

  - `'u'` 格式代码 (`wchar_t`) 自 Python 3.3 起已在文档中弃用并自 Python 3.13 起在运行时弃用。对于 Unicode 字符请改用 `'w'` 格式代码 (`Py_UCS4`)。

- `asyncio`:

  - `asyncio.iscoroutinefunction()` 已被弃用并将在 Python 3.16 中移除，请改用 `inspect.iscoroutinefunction()`。 （由李佳昊和 Kumar Aditya 在 gh-122875 中贡献。）

  - `asyncio` 策略系统已被弃用并将在 Python 3.16 中移除。具体而言，是弃用了下列类和函数：

    - `asyncio.AbstractEventLoopPolicy`

    - `asyncio.DefaultEventLoopPolicy`

    - `asyncio.WindowsSelectorEventLoopPolicy`

    - `asyncio.WindowsProactorEventLoopPolicy`

    - `asyncio.get_event_loop_policy()`

    - `asyncio.set_event_loop_policy()`

    用户应当使用 `asyncio.run()` 或 `asyncio.Runner` 并附带 loop_factory 以使用想要的事件循环实现。

    例如，在 Windows 上使用 `asyncio.SelectorEventLoop`:

        import asyncio

        async def main():
            ...

        asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)

    （由 Kumar Aditya 在 gh-127949 中贡献。）

- `builtins`:

  - 对布尔类型 `~True` 或 `~False` 执行按位取反的操作自 Python 3.12 起已被弃用，因为它会产生奇怪和不直观的结果 (`-2` 和 `-1`)。请改用 `not x` 来对布尔值执行逻辑否操作。对于需要对下层整数执行按位取反操作的少数场合，请显式地将其转换为 `int` (`~int(x)`)。

- `functools`:

  - 调用 `functools.reduce()` 的 Python 实现并传入 function 或 sequence 作为关键字参数的做法自 Python 3.14 起已被弃用。

- `logging`:

  - 使用 strm 参数对自定义日志记录处理器提供支持的做法已被弃用并计划在 Python 3.16 中移除。改为使用 stream 参数定义处理器。 （由 Mariusz Felisiak 在 gh-115032 中贡献。）

- `mimetypes`:

  - 有效扩展以 "." 开头或在 `mimetypes.MimeTypes.add_type()` 中为空。未加点的扩展已弃用，在 Python 3.16 中将引发 `ValueError`。 （由 Hugo van Kemenade 在 gh-75223 中贡献。）

- `shutil`:

  - `ExecError` 异常自 Python 3.14 起已被弃用。它自 Python 3.4 起就未被 `shutil` 中的任何函数所使用，现在是 `RuntimeError` 的一个别名。

- `symtable`:

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

- `sys`:

  - The `_enablelegacywindowsfsencoding()` function has been deprecated since Python 3.13. Use the `PYTHONLEGACYWINDOWSFSENCODING` environment variable instead.

- `sysconfig`:

  - 自 Python 3.14 起，`sysconfig.expand_makefile_vars()` 函数已被弃用。请使用 `sysconfig.get_paths()` 的 `vars` 参数代替。

- `tarfile`:

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

## 计划在 Python 3.17 中移除

- `datetime`:

  - 使用不带年份的包含 `%e` (月份日期序号) 的格式字符串的 `strptime()` 调用自 Python 3.15 起已被弃用。 （由 Stan Ulbrych 在 gh-70647 中贡献。）

- `collections.abc`:

  - `collections.abc.ByteString` 计划在 Python 3.17 中移除。

    使用 `isinstance(obj, collections.abc.Buffer)` 来测试 `obj` 是否在运行时实现了 缓冲区协议。要用于类型标注，则使用 `Buffer` 或是显式指明你的代码所支持类型的并集 (例如 `bytes | bytearray | memoryview`)。

    `ByteString` 原本是想作为 `bytes` 和 `bytearray` 的超类型的抽象基类提供。 不过，由于该 ABC 从未有任何方法，知道一个对象是 `ByteString` 的实例并不能真正告诉你有关该对象的任何有用信息。其他常见缓冲区类型如 `memoryview` 同样不能被当作是 `ByteString` 的子类型（无论是在运行时还是对于静态类型检查器）。

    请参阅 PEP 688 了解详情。 （由 Shantanu Jain 在 gh-91896 中贡献。）

- `encodings`:

  - 将非 ascii encoding 名称传给 `encodings.normalize_encoding()` 的做法已被弃用并计划在 Python 3.17 中移除。 （由 Stan Ulbrych 在 gh-136702 中贡献。）

- `webbrowser`:

  - `webbrowser.MacOSXOSAScript` 已被弃用并改用 `webbrowser.MacOS`。 (gh-137586)

- `typing`:

  - 在 Python 3.14 之前，旧式的联合是通过私有类 `typing._UnionGenericAlias` 实现的。实现已不再需要该类，但为向后兼容性保留了该类，并计划在 Python 3.17 中删除。用户应使用记录在案的内省助手函数，如 `typing.get_origin()` 和 `typing.get_args()`，而不是依赖于私有的实现细节。

  - `typing.ByteString` 自 Python 3.9 起已被弃用，计划在 Python 3.17 中移除。

    使用 `isinstance(obj, collections.abc.Buffer)` 来测试 `obj` 是否在运行时实现了 缓冲区协议。要用于类型标注，则使用 `Buffer` 或是显式指明你的代码所支持类型的并集 (例如 `bytes | bytearray | memoryview`)。

    `ByteString` 原本是想作为 `bytes` 和 `bytearray` 的超类型的抽象基类提供。 不过，由于该 ABC 从未有任何方法，知道一个对象是 `ByteString` 的实例并不能真正告诉你有关该对象的任何有用信息。其他常见缓冲区类型如 `memoryview` 同样不能被当作是 `ByteString` 的子类型（无论是在运行时还是对于静态类型检查器）。

    请参阅 PEP 688 了解详情。 （由 Shantanu Jain 在 gh-91896 中贡献。）

## 计划在 Python 3.18 中移除

- 当需要一个文件描述符时将不再接受布尔值。 （由 Serhiy Storchaka 在 gh-82626 中贡献。）

- `decimal`:

  - 非标准且未写入文档的 `Decimal` 格式说明符 `'N'`，它仅在 `decimal` 模块的 C 实现中受到支持，自 Python 3.13 起已被弃用。 （由 Serhiy Storchaka 在 gh-89902 中贡献。）

- 由 PEP 829 定义的弃用：

  - 在 `name.pth` 文件中的 `import` 行会被静默地忽略。

  （由 Barry Warsaw 在 gh-148641 中贡献。）

## 计划在 Python 3.19 中移除

- `ctypes`:

  - 在非 Windows 平台上，通过设置 `_pack_` 而非 `_layout_`，隐式切换到与 MSVC 兼容的结构布局。

- `hashlib`:

  - 在哈希函数构造器如 `new()` 或者直接使用哈希算法名称的构造器如 `md5()` 和 `sha256()` 中，它们可选的初始数据形参在不同的 `hashlib` 实现中也可使用名为 `data=` 或 `string=` 的关键字参数形式传入。

    对 `string` 关键字参数名称的支持现已被弃用并计划在 Python 3.19 中移除。

    在 Python 3.13 之前，`string` 关键字形参没有根据哈希函数的后端实现得到正确的支持。 建议将初始数据作为位置参数传入以获得最大的向下兼容性。

- `http.cookies`:

  - `http.cookies.Morsel.js_output()` 已被弃用并将在 Python 3.19 中移除。

  - `http.cookies.BaseCookie.js_output()` 已被弃用并将在 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.

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

- 在这些标准库模块中的 `__version__`, `version` 和 `VERSION` 属性已被弃用并将在 Python 3.20 中移除。 请改用 `sys.version_info`。

  - `argparse`

  - `csv`

  - `ctypes`

  - `ctypes.macholib`

  - `decimal` (改用 `decimal.SPEC_VERSION`)

  - `http.server`

  - `imaplib`

  - `ipaddress`

  - `json`

  - `logging` (`__date__` 也已被弃用)

  - `optparse`

  - `pickle`

  - `platform`

  - `re`

  - `socketserver`

  - `tabnanny`

  - `tarfile`

  - `tkinter.font`

  - `tkinter.ttk`

  - `wsgiref.simple_server`

  - `xml.etree.ElementTree`

  - `xml.sax.expatreader`

  - `xml.sax.handler`

  - `zlib`

  （由 Hugo van Kemenade 和 Stan Ulbrych 在 gh-76007 中贡献。）

- 由 PEP 829 定义的弃用：

  - 为在 `name.pth` 文件中找到的 `import` 行产生警告。

  - `name.pth` 文件将不再以默认语言区域编码格式解码。 它们 必须 使用 `utf-8-sig` 编码。

  （由 Barry Warsaw 在 gh-148641 中贡献。）

- `ast`:

  - 创建抽象 AST 节点 (如 `ast.AST` 或 `ast.expr`) 的做法已被弃用并将在 Python 3.20 中引发错误。

## Pending removal in Python 3.21

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

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

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

- `argparse`:

  - 嵌套参数组和嵌套互斥组已被弃用。

  - 将未写入文档的关键字参数 prefix_chars 传递给 `add_argument_group()` 的做法现在已被弃用。

  - `argparse.FileType` 类型转换器已弃用。

- `builtins`:

  - 生成器: `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` 的实例。

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

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

- `codecs`: 请使用 `open()` 代替 `codecs.open()`。 (gh-133038)

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

- `logging`: `warn()` 方法自 Python 3.3 起已被弃用，请改用 `warning()`.

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

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

- `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`: 使用元组值作为 exc_info 形参的做法已被弃用，应使用异常实例。

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

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

- 内部类 `typing._UnionGenericAlias` 不再用于实现 `typing.Union`。为了保持使用该私有类的用户的兼容性，将至少在 Python 3.17 之前提供兼容性垫片。 （由 Jelle Zijlstra 在 gh-105499 中贡献。）

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

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

  - `splitattr()`

  - `splithost()`

  - `splitnport()`

  - `splitpasswd()`

  - `splitport()`

  - `splitquery()`

  - `splittag()`

  - `splittype()`

  - `splituser()`

  - `splitvalue()`

  - `to_bytes()`

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

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

- `sys._clear_type_cache()` 已弃用，请改用 `sys._clear_internal_caches()`。

## 软弃用

尚无计划移除 soft deprecated API。

- `re.match()` and `re.Pattern.match()` are now soft deprecated in favor of the new `re.prefixmatch()` and `re.Pattern.prefixmatch()` APIs, which have been added as alternate, more explicit names. These are intended to be used to alleviate confusion around what match means by following the Zen of Python's "Explicit is better than implicit" mantra. Most other language regular expression libraries use an API named match to mean what Python has always called search.

  We do not plan to remove the older `match()` name, as it has been used in code for over 30 years. Code supporting older versions of Python should continue to use `match()`, while new code should prefer `prefixmatch()`. See prefixmatch() vs. match().

  （由 Gregory P. Smith 在 gh-86519 以及 Hugo van Kemenade 在 gh-148100 中贡献。）

## C API 的弃用项

### 计划在 Python 3.15 中移除

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

- `PyWeakref_GetObject()` 和 `PyWeakref_GET_OBJECT()`: 改用 `PyWeakref_GetRef()`。 在 Python 3.12 及更旧的版本中可以使用 pythoncapi-compat 项目 来获取 `PyWeakref_GetRef()`。

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

- `PyUnicode_AsDecodedUnicode()`: 改用 `PyCodec_Decode()`；请注意某些编解码器 (例如 "base64") 可能返回 `str` 以外的类型，比如 `bytes`。

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

- `PyUnicode_AsEncodedUnicode()`: 使用 `PyCodec_Encode()` 代替；请注意，某些编解码器（如 "base64"）可能返回 `bytes` 之外的类型，如 `str`。

- Python 初始化函数，Python 3.13 中弃用：

  - `Py_GetPath()`: 改用 `PyConfig_Get("module_search_paths")` (`sys.path`)。

  - `Py_GetPrefix()`: 改用 `PyConfig_Get("base_prefix")` (`sys.base_prefix`)。 如果需要处理 虚拟环境 则使用 `PyConfig_Get("prefix")` (`sys.prefix`)。

  - `Py_GetExecPrefix()`: 改用 `PyConfig_Get("base_exec_prefix")` (`sys.base_exec_prefix`)。 如果需要处理 虚拟环境 则使用 `PyConfig_Get("exec_prefix")` (`sys.exec_prefix`)。

  - `Py_GetProgramFullPath()`: 改用 `PyConfig_Get("executable")` (`sys.executable`)。

  - `Py_GetProgramName()`: 改用 `PyConfig_Get("executable")` (`sys.executable`)。

  - `Py_GetPythonHome()`: 改用 `PyConfig_Get("home")` 或 `PYTHONHOME` 环境变量。

  在 Python 3.13 和更旧的版本中可以使用 pythoncapi-compat 项目 来获取 `PyConfig_Get()` 。

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

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

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

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

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

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

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

- 全局配置变量：

  - `Py_DebugFlag`: 改用 `PyConfig.parser_debug` 或 `PyConfig_Get("parser_debug")`.

  - `Py_VerboseFlag`: 改用 `PyConfig.verbose` 或 `PyConfig_Get("verbose")`.

  - `Py_QuietFlag`: 改用 `PyConfig.quiet` 或 `PyConfig_Get("quiet")`.

  - `Py_InteractiveFlag`: 改用 `PyConfig.interactive` 或 `PyConfig_Get("interactive")`.

  - `Py_InspectFlag`: 改用 `PyConfig.inspect` 或 `PyConfig_Get("inspect")`.

  - `Py_OptimizeFlag`: 改用 `PyConfig.optimization_level` 或 `PyConfig_Get("optimization_level")`.

  - `Py_NoSiteFlag`: 改用 `PyConfig.site_import` 或 `PyConfig_Get("site_import")`.

  - `Py_BytesWarningFlag`: 改用 `PyConfig.bytes_warning` 或 `PyConfig_Get("bytes_warning")`.

  - `Py_FrozenFlag`: 使用 `PyConfig.pathconfig_warnings` 或 `PyConfig_Get("pathconfig_warnings")` 代替。

  - `Py_IgnoreEnvironmentFlag`: 使用 `PyConfig.use_environment` 或 `PyConfig_Get("use_environment")` 代替。

  - `Py_DontWriteBytecodeFlag`: 使用 `PyConfig.write_bytecode` 或 `PyConfig_Get("write_bytecode")` 代替。

  - `Py_NoUserSiteDirectory`: 使用 `PyConfig.user_site_directory` 或 `PyConfig_Get("user_site_directory")` 代替。

  - `Py_UnbufferedStdioFlag`: 使用 `PyConfig.buffered_stdio` 或 `PyConfig_Get("buffered_stdio")` 代替。

  - `Py_HashRandomizationFlag`: 使用 `PyConfig.use_hash_seed` 和 `PyConfig.hash_seed` 或 `PyConfig_Get("hash_seed")` 代替。

  - `Py_IsolatedFlag`: 使用 `PyConfig.isolated` 或 `PyConfig_Get("isolated")` 代替。

  - `Py_LegacyWindowsFSEncodingFlag`: 使用 `PyPreConfig.legacy_windows_fs_encoding` 或 `PyConfig_Get("legacy_windows_fs_encoding")` 代替。

  - `Py_LegacyWindowsStdioFlag`: 使用 `PyConfig.legacy_windows_stdio` 或 `PyConfig_Get("legacy_windows_stdio")` 代替。

  - `Py_FileSystemDefaultEncoding`,:c:var:!Py_HasFileSystemDefaultEncoding: 使用 `PyConfig.filesystem_encoding` 或 `PyConfig_Get("filesystem_encoding")` 代替。

  - `Py_FileSystemDefaultEncodeErrors`: 使用 `PyConfig.filesystem_errors` 或 `PyConfig_Get("filesystem_errors")` 代替。

  - `Py_UTF8Mode`: 使用 `PyPreConfig.utf8_mode` 或 `PyConfig_Get("utf8_mode")` 代替。 (参见 `Py_PreInitialize()`).

  `Py_InitializeFromConfig()` API 应与 `PyConfig` 一起使用，以设置这些选项。或者使用 `PyConfig_Get()` 在运行时获取这些选项。

### 计划在 Python 3.16 中移除

- 捆绑的 `libmpdec` 副本。

### 计划在 Python 3.18 中移除

- 以下私有函数已被弃用，并计划在 Python 3.18 中移除：

  - `_PyBytes_Join()`: 使用 `PyBytes_Join()`。

  - `_PyDict_GetItemStringWithError()`: 使用 `PyDict_GetItemStringRef()`.

  - `_PyDict_Pop()`: 使用 `PyDict_Pop()`。

  - `_PyLong_Sign()`: 使用 `PyLong_GetSign()`。

  - `_PyLong_FromDigits()` 和 `_PyLong_New()`: 使用 `PyLongWriter_Create()`.

  - `_PyThreadState_UncheckedGet()`: 使用 `PyThreadState_GetUnchecked()`.

  - `_PyUnicode_AsString()`: 使用 `PyUnicode_AsUTF8()`。

  - `_PyUnicodeWriter_Init()`: 将 `_PyUnicodeWriter_Init(&writer)` 替换为 `writer = PyUnicodeWriter_Create(0)`.

  - `_PyUnicodeWriter_Finish()`: 将 `_PyUnicodeWriter_Finish(&writer)` 替换为 `PyUnicodeWriter_Finish(writer)`。

  - `_PyUnicodeWriter_Dealloc()`: 将 `_PyUnicodeWriter_Dealloc(&writer)` 替换为 `PyUnicodeWriter_Discard(writer)`。

  - `_PyUnicodeWriter_WriteChar()`: 将 `_PyUnicodeWriter_WriteChar(&writer, ch)` 替换为 `PyUnicodeWriter_WriteChar(writer, ch)`.

  - `_PyUnicodeWriter_WriteStr()`: 将 `_PyUnicodeWriter_WriteStr(&writer, str)` 替换为 `PyUnicodeWriter_WriteStr(writer, str)`.

  - `_PyUnicodeWriter_WriteSubstring()`: 将 `_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)` 替换为 `PyUnicodeWriter_WriteSubstring(writer, str, start, end)`.

  - `_PyUnicodeWriter_WriteASCIIString()`: 请将 `_PyUnicodeWriter_WriteASCIIString(&writer, str)` 替换为 `PyUnicodeWriter_WriteASCII(writer, str)`.

  - `_PyUnicodeWriter_WriteLatin1String()`: 将 `_PyUnicodeWriter_WriteLatin1String(&writer, str)` 替换为 `PyUnicodeWriter_WriteUTF8(writer, str)`.

  - `_PyUnicodeWriter_Prepare()`: (无替代)。

  - `_PyUnicodeWriter_PrepareKind()`: (无替代)。

  - `_Py_HashPointer()`: 使用 `Py_HashPointer()`。

  - `_Py_fopen_obj()`: 使用 `Py_fopen()`。

  pythoncapi-compat 项目 可被用于在 Python 3.13 及更早版本中获取这些新的公有函数。 （由 Victor Stinner 在 gh-128863 中贡献。）

### 计划在 Python 3.19 中移除

- PEP 456 对于字符串哈希方案定义的嵌入方支持。

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

- `Py_MATH_PIl` 和 `Py_MATH_El` 宏。

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

以下 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()` 和 `PySlice_AdjustIndices()`.

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

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

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

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

- 线程本地存储 (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 起不再需要。