已棄用項目
**********


Python 3.14 中待移除的項目
==========================

* "argparse"："argparse.BooleanOptionalAction" 的 *type*、*choices* 和
  *metavar* 參數已被棄用，將在 3.14 中移除。 (由 Nikita Sobolev 於
  gh-92248 貢獻。)

* "ast"：自 Python 3.8 起，下列功能已在文件中被棄用，現在在存取或使用
  時會於 runtime 發出 "DeprecationWarning"，並將在 Python 3.14 中移除
  ：

  * "ast.Num"

  * "ast.Str"

  * "ast.Bytes"

  * "ast.NameConstant"

  * "ast.Ellipsis"

  請改用 "ast.Constant"。（由 Serhiy Storchaka 於 gh-90953 貢獻。）

* "asyncio"：

  * 已棄用並將在 Python 3.14 中移除的 child watcher 類別：
    "MultiLoopChildWatcher"、"FastChildWatcher"、
    "AbstractChildWatcher" 和 "SafeChildWatcher"。 (由 Kumar Aditya 於
    gh-94597 貢獻。)

  * "asyncio.set_child_watcher()"、"asyncio.get_child_watcher()"、
    "asyncio.AbstractEventLoopPolicy.set_child_watcher()" 和
    "asyncio.AbstractEventLoopPolicy.get_child_watcher()" 已被棄用並將
    在 Python 3.14 中移除。（由 Kumar Aditya 於 gh-94597 貢獻。）

  * 預設事件迴圈策略的 "get_event_loop()" 方法現在會在沒有設定目前事件
    迴圈且決定建立一個時發出 "DeprecationWarning"。 (由 Serhiy
    Storchaka 和 Guido van Rossum 於 gh-100160 貢獻。)

* "builtins": "bool(NotImplemented)" now emits a "DeprecationWarning"
  and will raise a "TypeError" in Python 3.14. (Contributed by Jelle
  Zijlstra in gh-118767.)

* "email"：已棄用 "email.utils.localtime()" 中的 *isdst* 參數。（由
  Alan Williams 於 gh-72346 貢獻。）

* "importlib.abc" 的已棄用類別：

  * "importlib.abc.ResourceReader"

  * "importlib.abc.Traversable"

  * "importlib.abc.TraversableResources"

  請改用 "importlib.resources.abc" 類別：

  * "importlib.resources.abc.Traversable"

  * "importlib.resources.abc.TraversableResources"

  （由 Jason R. Coombs 和 Hugo van Kemenade 貢獻於 gh-93963。）

* "itertools" 有不以文件記錄、效率低下、過去常有 bug 且不一致的 copy、
  deepcopy 和 pickle 操作支援。將在 3.14 中移除以大幅減少程式碼量和維
  護負擔。 (由 Raymond Hettinger 於 gh-101588 貢獻。)

* "multiprocessing"：預設的啟動方法將在 Linux、BSD 和其他非 macOS
  POSIX 平台上更改為更安全的 方法，目前 "'fork'" 是預設值 (gh-84559)。
  對此增加一個 runtime 警告被認為太過擾人，因為 大多數程式碼不會在意。
  請使用 "get_context()" 或 "set_start_method()" API 來明確指定你的程
  式碼何時*需要* "'fork'"。請參閱 Contexts and start methods。

* "pathlib"：已棄用 "is_relative_to()" 和 "relative_to()"：額外引數的
  傳遞已被棄用。

* "pkgutil"："find_loader()" 和 "get_loader()" 現在會引發
  "DeprecationWarning"；請改用 "importlib.util.find_spec()"。 (由
  Nikita Sobolev 於 gh-97850 貢獻。)

* "pty"：

  * "master_open()"：請用 "pty.openpty()"。

  * "slave_open()"：請用 "pty.openpty()"。

* "sqlite3"：

  * "version" 和 "version_info"。

  * "execute()" 和 "executemany()"，如果使用 named placeholders 且
    *parameters* 是序列而不是 "dict"。

* "urllib"："urllib.parse.Quoter" 已被棄用：它並非預期的公開 API。(由
  Gregory P. Smith 於 gh-88168 貢獻。)


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

  * 過時且很少使用的 "CGIHTTPRequestHandler" 自 Python 3.13 起已被棄用
    。不存在直接的替代。*任何東西*都比 CGI 更好地將 Web 伺服器與請求處
    理程序介接起來。

  * 自 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()" 已自 Python 3.13 被棄用。請用
    "os.path.isreserved()" 來偵測 Windows 上的保留路徑。

* "platform"：

  * 自 Python 3.13 起，"java_ver()" 已被棄用。此函式僅對 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"：自 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" 模組中使用了八年之後，它尚未得到任何主要型別檢
    查器的支援。

* "wave"：

  * 已棄用 "Wave_read" 和 "Wave_write" 類別的 "getmark()"、"setmark()"
    和 "getmarkers()" 方法自 Python 3.13 被棄用。


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 貢獻。）

* "builtins"：

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

* "shutil"：

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

* "symtable"：

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

* "sys"：

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

* "tarfile"：

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


Pending removal in 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"：

  * Before Python 3.14, old-style unions were implemented using the
    private class "typing._UnionGenericAlias". This class is no longer
    needed for the implementation, but it has been retained for
    backward compatibility, with removal scheduled for Python 3.17.
    Users should use documented introspection helpers like
    "typing.get_origin()" and "typing.get_args()" instead of relying
    on private implementation details.

  * "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.)


Pending removal in Python 3.18
==============================

* "decimal":

  * The non-standard and undocumented "Decimal" format specifier
    "'N'", which is only supported in the "decimal" module's C
    implementation, has been deprecated since Python 3.13.
    (Contributed by Serhiy Storchaka in gh-89902.)


未來版本中的待移除項目
======================

以下 API 將在未來被移除，雖然目前尚未安排移除日期。

* "argparse"：已棄用巢狀引數群組和巢狀互斥群組。

* "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 貢獻。)

* "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 貢獻。）

* "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)。

* "unittest.IsolatedAsyncioTestCase"：從測試案例中回傳非 "None" 的值已
  被棄用。

* "urllib.parse" 已棄用函式：請改用 "urlparse()"。

  * "splitattr()"

  * "splithost()"

  * "splitnport()"

  * "splitpasswd()"

  * "splitport()"

  * "splitquery()"

  * "splittag()"

  * "splittype()"

  * "splituser()"

  * "splitvalue()"

  * "to_bytes()"

* "urllib.request"：呼叫請求的 "URLopener" 和 "FancyURLopener" 風格已
  被棄用。請改用更新的 "urlopen()" 函式和方法。

* "wsgiref"："SimpleHandler.stdout.write()" 不應該進行部分寫入。

* "xml.etree.ElementTree"：已棄用對 "Element" 的真值測試。在未來版本中
  ，它將始終回傳 "True"。請改用明確的 "len(elem)" 或 "elem is not
  None" 測試。

* "zipimport.zipimporter.load_module()" 已被棄用：請改用
  "exec_module()"。


C API 的棄用項目
================


Python 3.14 中待移除的項目
--------------------------

* "PyDictObject" 中的 "ma_version_tag" 欄位，用於擴充模組 (**PEP 699**
  ；gh-101193)。

* 使用可變基底建立"不可變型別" (gh-95388)。

* 設定 Python 初始化的函式，Python 3.11 中已被棄用：

  * "PySys_SetArgvEx()"：請改以 "PyConfig.argv" 設定。

  * "PySys_SetArgv()"：請改以 "PyConfig.argv" 設定。

  * "Py_SetProgramName()`()"：請改以 "PyConfig.program_name" 設定。

  * "Py_SetPythonHome()"：請改以 "PyConfig.home" 設定。

  "Py_InitializeFromConfig()" API 應該與 "PyConfig" 一起使用。

* 全域設定變數：

  * "Py_DebugFlag"：請改用 "PyConfig.parser_debug"。

  * "Py_VerboseFlag"：請改用 "PyConfig.verbose"。

  * "Py_QuietFlag"：請改用 "PyConfig.quiet"。

  * "Py_InteractiveFlag"：請改用 "PyConfig.interactive"。

  * "Py_InspectFlag"：請改用 "PyConfig.inspect"。

  * "Py_OptimizeFlag"：請改用 "PyConfig.optimization_level"。

  * "Py_NoSiteFlag"：請改用 "PyConfig.site_import"。

  * "Py_BytesWarningFlag"：請改用 "PyConfig.bytes_warning"。

  * "Py_FrozenFlag"：請改用 "PyConfig.pathconfig_warnings"。

  * "Py_IgnoreEnvironmentFlag"：請改用 "PyConfig.use_environment"。

  * "Py_DontWriteBytecodeFlag"：請改用 "PyConfig.write_bytecode"。

  * "Py_NoUserSiteDirectory"：請改用 "PyConfig.user_site_directory"。

  * "Py_UnbufferedStdioFlag"：請改用 "PyConfig.buffered_stdio"。

  * "Py_HashRandomizationFlag"：請改用 "PyConfig.use_hash_seed" 和
    "PyConfig.hash_seed"。

  * "Py_IsolatedFlag"：請改用 "PyConfig.isolated"。

  * "Py_LegacyWindowsFSEncodingFlag"：請改用
    "PyPreConfig.legacy_windows_fs_encoding"。

  * "Py_LegacyWindowsStdioFlag"：請改用
    "PyConfig.legacy_windows_stdio"。

  * "Py_FileSystemDefaultEncoding"：請改用
    "PyConfig.filesystem_encoding"。

  * "Py_HasFileSystemDefaultEncoding"：請改用
    "PyConfig.filesystem_encoding"。

  * "Py_FileSystemDefaultEncodeErrors"：請改用
    "PyConfig.filesystem_errors"。

  * "Py_UTF8Mode"：請改用 "PyPreConfig.utf8_mode"。（請見
    "Py_PreInitialize()"）

  "Py_InitializeFromConfig()" API 應該與 "PyConfig" 一起使用。


Python 3.15 中待移除的項目
--------------------------

* "PyImport_ImportModuleNoBlock()"：請改用 "PyImport_ImportModule()"。

* "PyWeakref_GetObject()" 和 "PyWeakref_GET_OBJECT()"：請改用
  "PyWeakref_GetRef()"。

* "Py_UNICODE" 型別與 "Py_UNICODE_WIDE" 巨集：請改用 "wchar_t"。

* Python 初始化函式：

  * "PySys_ResetWarnOptions()"：請改為清除 "sys.warnoptions" 和
    "warnings.filters"。

  * "Py_GetExecPrefix()"：請改用 "sys.base_exec_prefix" 與
    "sys.exec_prefix"。

  * "Py_GetPath()"：請改用 "sys.path"。

  * "Py_GetPrefix()"：請改用 "sys.base_prefix" 與 "sys.prefix"。

  * "Py_GetProgramFullPath()"：請改用 "sys.executable"。

  * "Py_GetProgramName()"：請改用 "sys.executable"。

  * "Py_GetPythonHome()"：請改用 "PyConfig.home" 或 "PYTHONHOME" 環境
    變數。


未來版本中的待移除項目
----------------------

下列 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_AsDecodedObject()"：請改用 "PyCodec_Decode()"。

* "PyUnicode_AsDecodedUnicode()"：請改用 "PyCodec_Decode()"。

* "PyUnicode_AsEncodedObject()"：請改用 "PyCodec_Encode()"。

* "PyUnicode_AsEncodedUnicode()"：請改用 "PyCodec_Encode()"。

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

* "PyErr_Display()"：請改用 "PyErr_DisplayException()"。

* "_PyErr_ChainExceptions()"：請改用 "_PyErr_ChainExceptions1"。

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

* "PyDictObject.ma_version_tag" 成員。

* 執行緒局部儲存 (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 起不再需要。
