弃用项

计划在 Python 3.15 中移除

• 导入系统

  • 在设置模块的 __cached__ 属性时，若未同时设置 __spec__.cached，此行为已被弃用。在 Python 3.15 中，导入系统或标准库将不再设置或考虑 __cached__ 属性。(由 gh-97879 贡献)

  • 在设置模块的 __package__ 属性时，若未同时设置 __spec__.parent，此行为已被弃用。在 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 起弃用。要检测 Windows 上的保留路径，请使用 os.path.isreserved()。

• platform:

  • java_ver() 已自 Python 3.13 起弃用。此函数仅对 Jython 支持有用，其 API 令人困惑，且基本未经测试。

• sysconfig:

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

• threading:

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

• types:

  • types.CodeType：访问 co_lnotab 已在 PEP 626 中自 3.10 版起弃用，并计划在 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 起弃用。要创建一个没有字段的 TypedDict，请使用 class TD(TypedDict): pass 或 TD = TypedDict("TD", {})。

  • 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()。（由 Jiahao Li 在 gh-125746 中贡献。）

计划在 Python 3.16 中移除

• 导入系统

  • 在设置模块的 __loader__ 属性时，若未同时设置 __spec__.loader，此行为已被弃用。在 Python 3.16 中，导入系统或标准库将不再设置或考虑 __loader__ 属性。

• array:

  • 'u' 格式代码（wchar_t）自 Python 3.3 起在文档中被弃用，自 Python 3.13 起在运行时被弃用。请改用 'w' 格式代码（Py_UCS4）来处理 Unicode 字符。

• asyncio:

  • asyncio.iscoroutinefunction() 已被弃用，并将在 Python 3.16 中移除；请改用 inspect.iscoroutinefunction()。（由 Jiahao Li 和 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() 或带 loop_factory 参数的 asyncio.Runner 来使用期望的事件循环实现。

    例如，在 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:

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

• sys:

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

• sysconfig:

  • sysconfig.expand_makefile_vars() 函数已自 Python 3.14 起弃用。请改用 sysconfig.get_paths() 的 vars 参数。

• tarfile:

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

计划在 Python 3.17 中移除

• collections.abc:

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

    要测试 obj 是否在运行时实现了缓冲区协议，请使用 isinstance(obj, collections.abc.Buffer)。在类型注解中，请使用 Buffer 或显式指定代码支持的类型的联合类型（例如 bytes | bytearray | memoryview）。

    ByteString 最初旨在作为一个抽象类，作为 bytes 和 bytearray 的超类型。然而，由于该抽象基类（ABC）从未有过任何方法，所以知道一个对象是 ByteString 的实例实际上并不能提供任何关于该对象的有用信息。其他常见的缓冲区类型，如 memoryview，也从未被理解为 ByteString 的子类型（无论是在运行时还是通过静态类型检查器）。

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

• typing:

  • 在 Python 3.14 之前，旧式联合类型是通过私有类 typing._UnionGenericAlias 实现的。该类对于实现已不再需要，但为了向后兼容而保留，并计划在 Python 3.17 中移除。用户应使用文档化的内省辅助工具，如 typing.get_origin() 和 typing.get_args()，而不是依赖于私有实现细节。

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

    要测试 obj 是否在运行时实现了缓冲区协议，请使用 isinstance(obj, collections.abc.Buffer)。在类型注解中，请使用 Buffer 或显式指定代码支持的类型的联合类型（例如 bytes | bytearray | memoryview）。

    ByteString 最初旨在作为一个抽象类，作为 bytes 和 bytearray 的超类型。然而，由于该抽象基类（ABC）从未有过任何方法，所以知道一个对象是 ByteString 的实例实际上并不能提供任何关于该对象的有用信息。其他常见的缓冲区类型，如 memoryview，也从未被理解为 ByteString 的子类型（无论是在运行时还是通过静态类型检查器）。

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

计划在 Python 3.19 中移除

• ctypes:

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

计划在未来版本中移除

以下 API 将在未来移除，但目前尚未确定移除日期。

• argparse:

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

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

  • 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 的实例。

  • 将 int() 委托给 __trunc__() 方法的做法。

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

• 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 已被弃用。

  • 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 中移除

• PyImport_ImportModuleNoBlock()：请改用 PyImport_ImportModule()。

• PyWeakref_GetObject() 和 PyWeakref_GET_OBJECT()：请改用 PyWeakref_GetRef()。可以使用 pythoncapi-compat 项目 在 Python 3.12 及更早版本中获得 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 环境变量。

  可以使用 pythoncapi-compat 项目 在 Python 3.13 及更早版本中获得 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、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 中移除

• 以下私有函数已被弃用，并计划在 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 中贡献。）

计划在未来版本中移除

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