已棄用項目

Python 3.15 中待移除的項目

• 引入系統 (import system)：

  • 在模組上設定 __cached__ 而沒有設定 __spec__.cached 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 __cached__。(gh-97879)

  • 在模組上設定 __package__ 而沒有設定 __spec__.parent 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 __package__。(gh-97879)

• ctypes：

  • 自 Python 3.13 起，未記錄的 ctypes.SetPointerType() 函式已被棄用。

• 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 3.13 起，python -m http.server 命令列介面的 --cgi 旗標已被棄用。

• importlib：

  • load_module() method：請改用 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：

  • RLock() 在 Python 3.15 中將不接受任何引數。自 Python 3.14 起，傳遞任何引數的用法已被棄用，因為 Python 版本不允許任何引數，但 C 版本允許任意數量的位置或關鍵字引數，並忽略每個引數。

• types：

  • types.CodeType：自 3.10 起，存取 co_lnotab 已在 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 棄用。請改用基於類別的語法或函式語法 (functional syntax)。

  • 當使用 TypedDict 的函式語法時，未傳遞值給 fields 參數 (TD = TypedDict("TD")) 或傳遞 None (TD = TypedDict("TD", None)) 的做法自 Python 3.13 起已被棄用。請使用 class TD(TypedDict): pass 或 TD = TypedDict("TD", {}) 來建立具有零個欄位的 TypedDict。

  • 自 Python 3.13 起，typing.no_type_check_decorator() 裝飾器函式已被棄用。在 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 中待移除的項目

• 引入系統 (import system)：

  • 在模組上設定 __loader__ 而沒有設定 __spec__.loader 的做法將於 Python 3.16 被棄用。在 Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 __loader__。

• array：

  • 自 Python 3.3 起，'u' 格式碼 (wchar_t) 在文件中已被棄用，自 Python 3.13 起在 runtime 已被棄用。請使用 '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() 或 asyncio.Runner 搭配 loop_factory 來使用所需的事件迴圈實作。

    例如在 Windows 上使用 asyncio.SelectorEventLoop：

    import asyncio
    
    async def main():
        ...
    
    asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
    

    （由 Kumar Aditya 於 gh-127949 貢獻。）

• builtins：

  • 自 Python 3.12 起，布林型別的位元反轉 ~True 或 ~False 已被棄用，因為它會產生不預期且不直觀的結果（-2 和 -1）。使用 not x 代替布林值的邏輯否定。在極少數情況下，你需要對底層的整數進行位元反轉，請明確轉換為 ~int(x) (~int(x))。

• functools：

  • 自 Python 3.14 起，使用 function 或 sequence 關鍵字引數呼叫 functools.reduce() 的 Python 實作已被棄用。

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

  • 自 Python 3.14 起，ExecError 例外已被棄用。自 Python 3.4 以來，它尚未被 shutil 中的任何函式使用，現在是 RuntimeError 的別名。

• symtable：

  • 自 Python 3.14 起，Class.get_methods 方法已被棄用。

• sys：

  • 自 Python 3.13 起，_enablelegacywindowsfsencoding() 函式已被棄用。請改用 PYTHONLEGACYWINDOWSFSENCODING 環境變數。

• sysconfig：

  • 自 Python 3.14 起，sysconfig.expand_makefile_vars() 函式已被棄用。請改用 sysconfig.get_paths() 的 vars 引數。

• tarfile：

  • 自 Python 3.13 起，未以文件記錄和未被使用的 TarFile.tarfile 屬性已被棄用。

Python 3.17 中待移除的項目

• collections.abc：

  • collections.abc.ByteString is scheduled for removal in Python 3.17.

    Use isinstance(obj, collections.abc.Buffer) to test if obj implements the buffer protocol at runtime. For use in type annotations, either use Buffer or a union that explicitly specifies the types your code supports (e.g., bytes | bytearray | memoryview).

    ByteString was originally intended to be an abstract class that would serve as a supertype of both bytes and bytearray. However, since the ABC never had any methods, knowing that an object was an instance of ByteString never actually told you anything useful about the object. Other common buffer types such as memoryview were also never understood as subtypes of ByteString (either at runtime or by static type checkers).

    See PEP 688 for more details. (Contributed by Shantanu Jain in gh-91896.)

• typing：

  • 在 Python 3.14 之前，舊式聯集是使用私有類別 typing._UnionGenericAlias 實作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移除。使用者應該改用文件中記錄的內省輔助函式，例如 typing.get_origin() 和 typing.get_args()，或者依賴私有實作細節。

  • typing.ByteString, deprecated since Python 3.9, is scheduled for removal in Python 3.17.

    Use isinstance(obj, collections.abc.Buffer) to test if obj implements the buffer protocol at runtime. For use in type annotations, either use Buffer or a union that explicitly specifies the types your code supports (e.g., bytes | bytearray | memoryview).

    ByteString was originally intended to be an abstract class that would serve as a supertype of both bytes and bytearray. However, since the ABC never had any methods, knowing that an object was an instance of ByteString never actually told you anything useful about the object. Other common buffer types such as memoryview were also never understood as subtypes of ByteString (either at runtime or by static type checkers).

    See PEP 688 for more details. (Contributed by Shantanu Jain in 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.

Pending removal in Python 3.20

• The __version__ attribute has been deprecated in these standard library modules and will be removed in Python 3.20. Use sys.version_info instead.

  • argparse

  • csv

  • ctypes.macholib

  • ipaddress

  • json

  • logging (__date__ also deprecated)

  • optparse

  • pickle

  • platform

  • re

  • socketserver

  • tabnanny

  • tkinter.font

  • tkinter.ttk

  (Contributed by Hugo van Kemenade in gh-76007.)

未來版本中的待移除項目

以下 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：請改用 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：自 Python 3.3 起，warn() 方法已被棄用，請改用 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 已被棄用。

  • 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 都將提供一個相容性 shim。（由 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.

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

  應改用帶有 PyConfig 的 Py_InitializeFromConfig() API。

• 全域配置變數：

  • 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()）

  應改用帶有 PyConfig 的 Py_InitializeFromConfig() API 來設定這些選項。或者也可以使用 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 project 來取得這些於 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() 和 PySlice_AdjustIndices()。

• PyUnicode_READY()：自 Python 3.12 起不再需要

• PyErr_Display()：請改用 PyErr_DisplayException()。

• _PyErr_ChainExceptions()：請改用 _PyErr_ChainExceptions1。

• PyBytesObject.ob_shash 成員：請改為呼叫 PyObject_Hash()。

• 執行緒局部儲存 (Thread Local Storage, 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 起不再需要。