弃用

计划在 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 中贡献。）

• tkinter:

  • tkinter.Variable 的方法 trace_variable(), trace() (trace_variable() 的别名), trace_vdelete() 和 trace_vinfo()，自 Python 3.14 起已被弃用，计划在 Python 3.17 中移除。 请改用 trace_add(), trace_remove() 和 trace_info()。 （由 Serhiy Storchaka 在 gh-120220 中贡献。）

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

  • 修改 IMAP4.file 的做法现已被弃用并计划在 Python 3.19 中移除。 该属性现已不再使用并且修改其值不会自动关闭当前文件。

    在 Python 3.14 之前，该属性被用于为 IMAP4 实现相应的 read() 和 readline() 方法但在此之后情况已发生改变。

• tkinter:

  • tkinter.filedialog.askopenfiles() has been deprecated since Python 3.16. Iterate over the names returned by askopenfilenames() and open them one by one instead. (Contributed by Serhiy Storchaka in gh-152638.)

计划在 Python 3.20 中移除

• 调用 struct.Struct 的 __new__() 方法不带 format 参数的做法已被弃用并将在 Python 3.20 中移除。 在已初始化的 Struct 对象上调用 __init__() 方法的做法已被弃用并将在 Python 3.20 中移除。

  （由 Sergey B Kirpichev 和 Serhiy Storchaka 在 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

• abc

  • Soft-deprecated since Python 3.3 abc.abstractclassmethod, abc.abstractstaticmethod, and abc.abstractproperty now raise a DeprecationWarning. These classes will be removed in Python 3.21, instead use abc.abstractmethod() with classmethod(), staticmethod(), and property respectively.

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

• struct:

  • Soft-deprecated since Python 3.15, using 'F' and 'D' type codes are now deprecated. These codes will be removed in Python 3.21. Use instead two-letter forms 'Zf' and 'Zd'.

• tempfile:

  • tempfile._TemporaryFileWrapper will be removed in Python 3.21. Use the public tempfile.TemporaryFileWrapper 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() 已弃用，对于路径前缀请使用 os.path.commonpath()。 os.path.commonprefix() 函数被弃用是由于其误导性的名称和模块。 使用该函数获取路径前缀是不安全的，尽管它被包括在一个用于操作路径的模块中，使用此函数很容易意外地将路径遍历安全漏洞引入 Python 程序中。

• 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() 和 re.Pattern.match() 已被设为 soft deprecated 而应改用新的 re.prefixmatch() 和 re.Pattern.prefixmatch() API，它们作为替代性的、更明白的显式名称被添加进来。 这样做的目的是为了遵循 Python 之禅的 "明白胜于隐晦" 原则以消除对 match 具体含义理解所造成的混淆。 大多数其他语言的正则表达式库都使用名为 match 的 API 来表示to mean what Python 一直以来所称为的 search。

  我们 没有 计划移除旧的 match() 名称，因为它已在代码中使用超过 30。 支持较旧 Python 的代码应当继续使用 match()，而新的代码应当首选 prefixmatch()。 参见 prefixmatch() vs. match()。

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

C API 的弃用项

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

  • PyGen_New(): (no replacement).

  • PyGen_NewWithQualName(): (no replacement).

  • PyCoro_New(): (no replacement).

  • PyAsyncGen_New(): (no replacement).

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

计划在 Python 3.19 中移除

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

计划在 Python 3.20 中移除

• _PyObject_CallMethodId(), _PyObject_GetAttrId() 和 _PyUnicode_FromId() 自 3.15 起已弃用并将在 3.20 中移除。 作为替代，请使用 PyUnicode_InternFromString() 并将结果缓存在模块状态中，然后调用 PyObject_CallMethod() 或 PyObject_GetAttr()。 （由 Victor Stinner 在 gh-141049 中贡献。）

• PyComplexObject 中的 cval 字段 (gh-128813)。 使用 PyComplex_AsCComplex() 和 PyComplex_FromCComplex() 在 Python 复数和 C Py_complex 表示形式之间进行转换。

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