弃用

计划在 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:

  • The obsolete and rarely used CGIHTTPRequestHandler has been deprecated since Python 3.13. No direct replacement exists. Anything is better than CGI to interface a web server with a request handler.

  • 用于 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() has been deprecated since Python 3.13. Use os.path.isreserved() to detect reserved paths on Windows.

• platform:

  • platform.java_ver() has been deprecated since Python 3.13. This function is only useful for Jython support, has a confusing API, and is largely untested.

• 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 起已被弃用。 请改用基于类的语法或函数语法。

  • 当使用 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:

  • The getmark(), setmark() and getmarkers() methods of the Wave_read and Wave_write classes have been deprecated since Python 3.13.

• zipimport:

  • zipimport.zipimporter.load_module() has been deprecated since Python 3.10. Use exec_module() instead. (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 中移除

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

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

• ctypes:

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

• hashlib:

  • In hash function constructors such as new() or the direct hash-named constructors such as md5() and sha256(), their optional initial data parameter could also be passed a keyword argument named data= or string= in various hashlib implementations.

    Support for the string keyword argument name is now deprecated and slated for removal in Python 3.19.

    Before Python 3.13, the string keyword parameter was not correctly supported depending on the backend implementation of hash functions. Prefer passing the initial data as a positional argument for maximum backwards compatibility.

计划在未来版本中移除

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

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

• The PyImport_ImportModuleNoBlock(): Use PyImport_ImportModule() instead.

• PyWeakref_GetObject() and PyWeakref_GET_OBJECT(): Use PyWeakref_GetRef() instead. The pythoncapi-compat project can be used to get PyWeakref_GetRef() on Python 3.12 and older.

• 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(): Use PyConfig_Get("module_search_paths") (sys.path) instead.

  • Py_GetPrefix(): Use PyConfig_Get("base_prefix") (sys.base_prefix) instead. Use PyConfig_Get("prefix") (sys.prefix) if virtual environments need to be handled.

  • Py_GetExecPrefix(): Use PyConfig_Get("base_exec_prefix") (sys.base_exec_prefix) instead. Use PyConfig_Get("exec_prefix") (sys.exec_prefix) if virtual environments need to be handled.

  • Py_GetProgramFullPath(): Use PyConfig_Get("executable") (sys.executable) instead.

  • Py_GetProgramName(): Use PyConfig_Get("executable") (sys.executable) instead.

  • Py_GetPythonHome(): Use PyConfig_Get("home") or the PYTHONHOME environment variable instead.

  在 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(): Clear sys.warnoptions and warnings.filters instead.

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

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

Pending removal in Python 3.20

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

计划在未来版本中移除

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