弃用

计划在 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()。

• 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，并且大部分未经测试。

• sysconfig:

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

• 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:

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

  • When using the functional syntax of TypedDicts, failing to pass a value to the fields parameter (TD = TypedDict("TD")) or passing None (TD = TypedDict("TD", None)) has been deprecated since Python 3.13. Use class TD(TypedDict): pass or TD = TypedDict("TD", {}) to create a TypedDict with zero field.

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

• wave:

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

• zipimport:

  • 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 and -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:

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

• sys:

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

• sysconfig:

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

• tarfile:

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

计划在 Python 3.17 中移除

• typing:

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

计划在 Python 3.19 中移除

• ctypes:

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

计划在未来版本中移除

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

• argparse：

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

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

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

• 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 中贡献。）

• codecs：codecs.open() 请改用 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()。

• 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)。

• 内部类 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() 。

C API 的弃用项

计划在 Python 3.15 中移除

• 捆绑的 libmpdecimal 副本。

• PyImport_ImportModuleNoBlock(): 改用 PyImport_ImportModule()。

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

• Py_UNICODE 类型和 Py_UNICODE_WIDE 宏：改用 wchar_t。

• 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 or PyConfig_Get("optimization_level")。

  • Py_NoSiteFlag: 改用 PyConfig.site_import 或 PyConfig_Get("site_import")。

  • Py_BytesWarningFlag: 改用 PyConfig.bytes_warning or 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.18 中移除

• 弃用的私有函数 (gh-128863):

  • _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_WriteUTF8(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()。

  在 Python 3.13 和更旧的版本中可以使用 pythoncapi-compat 项目 来获取这些新的公有函数。

计划在未来版本中移除

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