弃用
****


Pending removal in 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 起已被弃用。

* "locale":

  * "getdefaultlocale()" 函数自 Python 3.11 起已被弃用。 最初计划在
    Python 3.13 中移除它 (gh-90817)，但已被推迟至 Python 3.15。 请改用
    "getlocale()", "setlocale()" 和 "getencoding()"。 （由 Hugo van
    Kemenade 在 gh-111187 中贡献。）

* "pathlib":

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

* "platform":

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

* "threading":

  * 在 Python 3.15 中 "RLock()" 将不再接受参数。 传入参数的做法自
    Python 3.14 起已被弃用，因为 Python 版本不接受任何参数，而 C 版本
    允许任意数量的位置或关键字参数，但会忽略所有参数。

* "types":

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

* "typing":

  * The undocumented keyword argument syntax for creating "NamedTuple"
    classes (for example, "Point = NamedTuple("Point", x=int, y=int)")
    has been deprecated since Python 3.13. Use the class-based syntax
    or the functional syntax instead.

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

* "wave":

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


计划在 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()"。 （由 Jiahao Li 和 Kumar
    Aditya 在 gh-122875 中贡献。）

* "builtins":

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

* "shutil":

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

* "symtable":

  * "Class.get_methods" 方法自 Python 3.14 起被弃用。

* "sys":

  * "_enablelegacywindowsfsencoding()" 函数自 Python 3.13 起被弃用。
    请改用 "PYTHONLEGACYWINDOWSFSENCODING" 环境变量。

* "tarfile":

  * 未写入文档也未被使用的 "TarFile.tarfile" 属性自 Python 3.13 起被弃
    用。


Pending removal in future versions
==================================

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

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

* "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":

  * "load_module()" 方法：改用 "exec_module()"。

  * "cache_from_source()" *debug_override* 形参已被弃用：改用
    *optimization* 形参。

* "importlib.metadata":

  * "EntryPoints" 元组接口。

  * 返回值中隐式的 "None"。

* "logging": "warn()" 方法自 Python 3.3 起已被弃用，请改用 "warning()"
  。

* "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"

* "sysconfig.is_python_build()" *check_home* 形参已被弃用并会被忽略。

* "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()"

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

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

* "zipimport.zipimporter.load_module()" 已被弃用：请改用
  "exec_module()"。


C API deprecations
==================


Pending removal in 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.base_exec_prefix" 和
    "sys.exec_prefix"。

  * "Py_GetPath()": 改为获取 "sys.path"。

  * "Py_GetPrefix()": 改为获取 "sys.base_prefix" 和 "sys.prefix"。

  * "Py_GetProgramFullPath()": 改为获取 "sys.executable"。

  * "Py_GetProgramName()": 改为获取 "sys.executable"。

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


Pending removal in future versions
----------------------------------

以下 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 起不再需要。
