diff --git a/library/warnings.po b/library/warnings.po index 35a798ed78..98fa8f8903 100644 --- a/library/warnings.po +++ b/library/warnings.po @@ -3,13 +3,15 @@ # This file is distributed under the same license as the Python package. # # Translators: +# Adrian Liaw , 2018 +# Dr-XYZ , 2025 msgid "" msgstr "" "Project-Id-Version: Python 3.13\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2024-11-03 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 16:15+0000\n" -"Last-Translator: Adrian Liaw \n" +"PO-Revision-Date: 2025-07-14 13:00+0800\n" +"Last-Translator: Dr-XYZ \n" "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" "tw)\n" "Language: zh_TW\n" @@ -34,23 +36,33 @@ msgid "" "program. For example, one might want to issue a warning when a program uses " "an obsolete module." msgstr "" +"警告訊息通常會在需要提醒使用者程式中的某些狀況時發出,而該狀況(通常)不至於" +"需要引發例外並終止程式。舉例來說,當程式使用一個過時的模組時,就可能會需要發" +"出警告。" #: ../../library/warnings.rst:18 msgid "" "Python programmers issue warnings by calling the :func:`warn` function " -"defined in this module. (C programmers use :c:func:`PyErr_WarnEx`; " -"see :ref:`exceptionhandling` for details)." +"defined in this module. (C programmers use :c:func:`PyErr_WarnEx`; see :ref:" +"`exceptionhandling` for details)." msgstr "" +"Python 程式設計師可以透過呼叫此模組中定義的 :func:`warn` 函式來發出警告。(C " +"語言的程式設計師則使用 :c:func:`PyErr_WarnEx`;詳情請參閱 :ref:" +"`exceptionhandling`)。" #: ../../library/warnings.rst:22 msgid "" "Warning messages are normally written to :data:`sys.stderr`, but their " "disposition can be changed flexibly, from ignoring all warnings to turning " -"them into exceptions. The disposition of warnings can vary based on " -"the :ref:`warning category `, the text of the warning " +"them into exceptions. The disposition of warnings can vary based on the :" +"ref:`warning category `, the text of the warning " "message, and the source location where it is issued. Repetitions of a " "particular warning for the same source location are typically suppressed." msgstr "" +"警告訊息通常會被寫入 :data:`sys.stderr`,但它們的處理方式可以被彈性地更改,從" +"忽略所有警告到將它們轉為例外都可以。警告的處理方式會根據 :ref:`警告類別 " +"`、警告訊息的文本,以及發出警告的原始碼位置而有所不同。在" +"同一個原始碼位置重複出現的特定警告通常會被抑制。" #: ../../library/warnings.rst:29 msgid "" @@ -59,15 +71,20 @@ msgid "" "next, if a message is to be issued, it is formatted and printed using a user-" "settable hook." msgstr "" +"警告控制有兩個階段:首先,每當發出一個警告時,會先決定是否該發出訊息;接著," +"如果要發出訊息,它會使用一個可由使用者設定的掛鉤 (hook) 來格式化並印出。" #: ../../library/warnings.rst:33 msgid "" -"The determination whether to issue a warning message is controlled by " -"the :ref:`warning filter `, which is a sequence of matching " -"rules and actions. Rules can be added to the filter by " -"calling :func:`filterwarnings` and reset to its default state by " -"calling :func:`resetwarnings`." +"The determination whether to issue a warning message is controlled by the :" +"ref:`warning filter `, which is a sequence of matching rules " +"and actions. Rules can be added to the filter by calling :func:" +"`filterwarnings` and reset to its default state by calling :func:" +"`resetwarnings`." msgstr "" +"是否要發出警告訊息是由 :ref:`警告過濾器 ` 所控制,它是一連串" +"的匹配規則和動作。可以透過呼叫 :func:`filterwarnings` 來新增規則到過濾器中," +"並透過呼叫 :func:`resetwarnings` 將其重設為預設狀態。" #: ../../library/warnings.rst:38 msgid "" @@ -76,22 +93,29 @@ msgid "" "the message by calling :func:`formatwarning`, which is also available for " "use by custom implementations." msgstr "" +"警告訊息的印出是透過呼叫 :func:`showwarning` 來完成,而它可以被覆寫;此函式的" +"預設實作會透過呼叫 :func:`formatwarning` 來格式化訊息,它也可以被自訂的實作使" +"用。" #: ../../library/warnings.rst:44 msgid "" ":func:`logging.captureWarnings` allows you to handle all warnings with the " "standard logging infrastructure." msgstr "" +":func:`logging.captureWarnings` 允許你使用標準的 logging 基礎設施來處理所有警" +"告。" #: ../../library/warnings.rst:51 msgid "Warning Categories" -msgstr "" +msgstr "警告類別" #: ../../library/warnings.rst:53 msgid "" "There are a number of built-in exceptions that represent warning categories. " "This categorization is useful to be able to filter out groups of warnings." msgstr "" +"有許多內建的例外代表警告類別。這種分類方式對於能夠過濾掉特定群組的警告很有" +"用。" #: ../../library/warnings.rst:56 msgid "" @@ -99,6 +123,8 @@ msgid "" "exceptions>`, they are documented here, because conceptually they belong to " "the warnings mechanism." msgstr "" +"雖然這些在技術上是 :ref:`內建例外 `,但它們" +"被記錄在這裡,因為從概念上來說,它們屬於警告機制的一部分。" #: ../../library/warnings.rst:60 msgid "" @@ -106,10 +132,12 @@ msgid "" "standard warning categories. A warning category must always be a subclass " "of the :exc:`Warning` class." msgstr "" +"使用者程式碼可以透過繼承其中一個標準警告類別來定義額外的警告類別。一個警告類" +"別必須永遠是 :exc:`Warning` 類別的子類別。" #: ../../library/warnings.rst:64 msgid "The following warnings category classes are currently defined:" -msgstr "" +msgstr "目前定義了以下警告類別: ::" #: ../../library/warnings.rst:69 msgid "Class" @@ -127,7 +155,7 @@ msgstr ":exc:`Warning`" msgid "" "This is the base class of all warning category classes. It is a subclass " "of :exc:`Exception`." -msgstr "" +msgstr "這是所有警告類別的基底類別。它是 :exc:`Exception` 的子類別。" #: ../../library/warnings.rst:75 msgid ":exc:`UserWarning`" @@ -135,7 +163,7 @@ msgstr ":exc:`UserWarning`" #: ../../library/warnings.rst:75 msgid "The default category for :func:`warn`." -msgstr "" +msgstr ":func:`warn` 的預設類別。" #: ../../library/warnings.rst:77 msgid ":exc:`DeprecationWarning`" @@ -147,6 +175,8 @@ msgid "" "intended for other Python developers (ignored by default, unless triggered " "by code in ``__main__``)." msgstr "" +"關於已棄用功能的警告的基底類別,當這些警告是針對其他 Python 開發者時(預設為" +"忽略,除非由 ``__main__`` 中的程式碼觸發)。" #: ../../library/warnings.rst:82 msgid ":exc:`SyntaxWarning`" @@ -154,7 +184,7 @@ msgstr ":exc:`SyntaxWarning`" #: ../../library/warnings.rst:82 msgid "Base category for warnings about dubious syntactic features." -msgstr "" +msgstr "關於可疑語法功能的警告的基底類別。" #: ../../library/warnings.rst:85 msgid ":exc:`RuntimeWarning`" @@ -162,7 +192,7 @@ msgstr ":exc:`RuntimeWarning`" #: ../../library/warnings.rst:85 msgid "Base category for warnings about dubious runtime features." -msgstr "" +msgstr "關於可疑 runtime 功能的警告的基底類別。" #: ../../library/warnings.rst:88 msgid ":exc:`FutureWarning`" @@ -173,6 +203,8 @@ msgid "" "Base category for warnings about deprecated features when those warnings are " "intended for end users of applications that are written in Python." msgstr "" +"關於已棄用功能的警告的基底類別,當這些警告是針對以 Python 編寫的應用程式的終" +"端使用者時。" #: ../../library/warnings.rst:93 msgid ":exc:`PendingDeprecationWarning`" @@ -182,7 +214,7 @@ msgstr ":exc:`PendingDeprecationWarning`" msgid "" "Base category for warnings about features that will be deprecated in the " "future (ignored by default)." -msgstr "" +msgstr "關於未來將被棄用的功能的警告的基底類別(預設為忽略)。" #: ../../library/warnings.rst:97 msgid ":exc:`ImportWarning`" @@ -192,7 +224,7 @@ msgstr ":exc:`ImportWarning`" msgid "" "Base category for warnings triggered during the process of importing a " "module (ignored by default)." -msgstr "" +msgstr "在引入模組過程中觸發的警告的基底類別(預設為忽略)。" #: ../../library/warnings.rst:101 msgid ":exc:`UnicodeWarning`" @@ -200,7 +232,7 @@ msgstr ":exc:`UnicodeWarning`" #: ../../library/warnings.rst:101 msgid "Base category for warnings related to Unicode." -msgstr "" +msgstr "與 Unicode 相關的警告的基底類別。" #: ../../library/warnings.rst:104 msgid ":exc:`BytesWarning`" @@ -209,7 +241,7 @@ msgstr ":exc:`BytesWarning`" #: ../../library/warnings.rst:104 msgid "" "Base category for warnings related to :class:`bytes` and :class:`bytearray`." -msgstr "" +msgstr "與 :class:`bytes` 和 :class:`bytearray` 相關的警告的基底類別。" #: ../../library/warnings.rst:107 msgid ":exc:`ResourceWarning`" @@ -218,7 +250,7 @@ msgstr ":exc:`ResourceWarning`" #: ../../library/warnings.rst:107 msgid "" "Base category for warnings related to resource usage (ignored by default)." -msgstr "" +msgstr "與資源使用相關的警告的基底類別(預設為忽略)。" #: ../../library/warnings.rst:111 msgid "" @@ -227,16 +259,19 @@ msgid "" "changing its behaviour. They are now distinguished based on their intended " "audience and the way they're handled by the default warnings filters." msgstr "" +"在過去,:exc:`DeprecationWarning` 和 :exc:`FutureWarning` 是根據一個功能是被" +"完全移除還是改變其行為來區分的。它們現在是根據其目標受眾以及預設警告過濾器處" +"理它們的方式來區分。" #: ../../library/warnings.rst:122 msgid "The Warnings Filter" -msgstr "" +msgstr "警告過濾器" #: ../../library/warnings.rst:124 msgid "" "The warnings filter controls whether warnings are ignored, displayed, or " "turned into errors (raising an exception)." -msgstr "" +msgstr "警告過濾器控制警告是被忽略、顯示,還是轉為錯誤(引發一個例外)。" #: ../../library/warnings.rst:127 msgid "" @@ -246,18 +281,22 @@ msgid "" "determines the disposition of the match. Each entry is a tuple of the form " "(*action*, *message*, *category*, *module*, *lineno*), where:" msgstr "" +"從概念上講,警告過濾器維護一個有序的過濾器規格串列;任何特定的警告都會依次與" +"串列中的每個過濾器規格進行比對,直到找到匹配項;過濾器決定了匹配項的處理方" +"式。每個條目都是一個 (*action*, *message*, *category*, *module*, *lineno*) 形" +"式的元組,其中: ::" #: ../../library/warnings.rst:133 msgid "*action* is one of the following strings:" -msgstr "" +msgstr "*action* 是以下字串之一: ::" #: ../../library/warnings.rst:136 msgid "Value" -msgstr "" +msgstr "值" #: ../../library/warnings.rst:136 msgid "Disposition" -msgstr "" +msgstr "處理方式" #: ../../library/warnings.rst:138 msgid "``\"default\"``" @@ -267,7 +306,7 @@ msgstr "``\"default\"``" msgid "" "print the first occurrence of matching warnings for each location (module + " "line number) where the warning is issued" -msgstr "" +msgstr "為發出警告的每個位置(模組 + 行號)印出第一次出現的匹配警告" #: ../../library/warnings.rst:142 msgid "``\"error\"``" @@ -275,7 +314,7 @@ msgstr "``\"error\"``" #: ../../library/warnings.rst:142 msgid "turn matching warnings into exceptions" -msgstr "" +msgstr "將匹配的警告轉為例外" #: ../../library/warnings.rst:144 msgid "``\"ignore\"``" @@ -283,7 +322,7 @@ msgstr "``\"ignore\"``" #: ../../library/warnings.rst:144 msgid "never print matching warnings" -msgstr "" +msgstr "永不印出匹配的警告" #: ../../library/warnings.rst:146 msgid "``\"always\"``" @@ -291,7 +330,7 @@ msgstr "``\"always\"``" #: ../../library/warnings.rst:146 msgid "always print matching warnings" -msgstr "" +msgstr "總是印出匹配的警告" #: ../../library/warnings.rst:148 msgid "``\"module\"``" @@ -301,7 +340,7 @@ msgstr "``\"module\"``" msgid "" "print the first occurrence of matching warnings for each module where the " "warning is issued (regardless of line number)" -msgstr "" +msgstr "為發出警告的每個模組印出第一次出現的匹配警告(不論行號)" #: ../../library/warnings.rst:152 msgid "``\"once\"``" @@ -310,22 +349,28 @@ msgstr "``\"once\"``" #: ../../library/warnings.rst:152 msgid "" "print only the first occurrence of matching warnings, regardless of location" -msgstr "" +msgstr "只印出第一次出現的匹配警告,不論位置" #: ../../library/warnings.rst:156 msgid "" "*message* is a string containing a regular expression that the start of the " -"warning message must match, case-insensitively. In :option:`-W` " -"and :envvar:`PYTHONWARNINGS`, *message* is a literal string that the start " -"of the warning message must contain (case-insensitively), ignoring any " -"whitespace at the start or end of *message*." +"warning message must match, case-insensitively. In :option:`-W` and :envvar:" +"`PYTHONWARNINGS`, *message* is a literal string that the start of the " +"warning message must contain (case-insensitively), ignoring any whitespace " +"at the start or end of *message*." msgstr "" +"*message* 是一個包含正規表示式的字串,警告訊息的開頭必須與其匹配(不區分大小" +"寫)。在 :option:`-W` 和 :envvar:`PYTHONWARNINGS` 中,*message* 是一個字面字" +"串,警告訊息的開頭必須包含該字串(不區分大小寫),並忽略 *message* 開頭或結尾" +"的任何空白字元。" #: ../../library/warnings.rst:162 msgid "" "*category* is a class (a subclass of :exc:`Warning`) of which the warning " "category must be a subclass in order to match." msgstr "" +"*category* 是一個類別(:exc:`Warning` 的子類別),警告類別必須是它的子類別才" +"能匹配。" #: ../../library/warnings.rst:165 msgid "" @@ -335,56 +380,72 @@ msgid "" "qualified module name must be equal to (case-sensitively), ignoring any " "whitespace at the start or end of *module*." msgstr "" +"*module* 是一個包含正規表示式的字串,完整限定模組名稱的開頭必須與其匹配(區分" +"大小寫)。在 :option:`-W` 和 :envvar:`PYTHONWARNINGS` 中,*module* 是一個字面" +"字串,完整限定模組名稱必須與其相等(區分大小寫),並忽略 *module* 開頭或結尾" +"的任何空白字元。" #: ../../library/warnings.rst:171 msgid "" "*lineno* is an integer that the line number where the warning occurred must " "match, or ``0`` to match all line numbers." msgstr "" +"*lineno* 是一個整數,發出警告的行號必須與其匹配,或者為 ``0`` 以匹配所有行" +"號。" #: ../../library/warnings.rst:174 msgid "" "Since the :exc:`Warning` class is derived from the built-in :exc:`Exception` " "class, to turn a warning into an error we simply raise ``category(message)``." msgstr "" +"由於 :exc:`Warning` 類別衍生自內建的 :exc:`Exception` 類別,要將警告轉為錯" +"誤,我們只需引發 ``category(message)``。" #: ../../library/warnings.rst:177 msgid "" "If a warning is reported and doesn't match any registered filter then the " "\"default\" action is applied (hence its name)." msgstr "" +"如果一個警告被回報且不匹配任何已註冊的過濾器,則會套用 \"default\" 動作(因此得" +"名)。" #: ../../library/warnings.rst:185 msgid "Repeated Warning Suppression Criteria" -msgstr "" +msgstr "重複警告的抑制標準" #: ../../library/warnings.rst:187 msgid "" "The filters that suppress repeated warnings apply the following criteria to " "determine if a warning is considered a repeat:" -msgstr "" +msgstr "抑制重複警告的過濾器會套用以下標準來判斷一個警告是否被視為重複: ::" #: ../../library/warnings.rst:189 msgid "" "``\"default\"``: A warning is considered a repeat only if the (*message*, " "*category*, *module*, *lineno*) are all the same." msgstr "" +"``\"default\"``:只有當 (*message*, *category*, *module*, *lineno*) 都相同" +"時,警告才被視為重複。" #: ../../library/warnings.rst:190 msgid "" "``\"module\"``: A warning is considered a repeat if the (*message*, " "*category*, *module*) are the same, ignoring the line number." msgstr "" +"``\"module\"``:如果 (*message*, *category*, *module*) 相同,則警告被視為重" +"複,忽略行號。" #: ../../library/warnings.rst:191 msgid "" "``\"once\"``: A warning is considered a repeat if the (*message*, " "*category*) are the same, ignoring the module and line number." msgstr "" +"``\"once\"``:如果 (*message*, *category*) 相同,則警告被視為重複,忽略模組和" +"行號。" #: ../../library/warnings.rst:197 msgid "Describing Warning Filters" -msgstr "" +msgstr "描述警告過濾器" #: ../../library/warnings.rst:199 msgid "" @@ -395,12 +456,16 @@ msgid "" "module parses these when it is first imported (invalid options are ignored, " "after printing a message to :data:`sys.stderr`)." msgstr "" +"警告過濾器由傳遞給 Python 直譯器命令列的 :option:`-W` 選項和 :envvar:" +"`PYTHONWARNINGS` 環境變數初始化。直譯器會將所有提供條目的引數未經直譯地儲存" +"在 :data:`sys.warnoptions` 中;:mod:`warnings` 模組在首次引入時會剖析這些引數" +"(無效選項會被忽略,並在向 :data:`sys.stderr` 印出一條訊息後)。" #: ../../library/warnings.rst:206 msgid "" "Individual warnings filters are specified as a sequence of fields separated " "by colons::" -msgstr "" +msgstr "個別的警告過濾器被指定為一系列由冒號分隔的欄位: ::" #: ../../library/warnings.rst:209 msgid "action:message:category:module:line" @@ -409,12 +474,16 @@ msgstr "action:message:category:module:line" #: ../../library/warnings.rst:211 msgid "" "The meaning of each of these fields is as described in :ref:`warning-" -"filter`. When listing multiple filters on a single line (as " -"for :envvar:`PYTHONWARNINGS`), the individual filters are separated by " -"commas and the filters listed later take precedence over those listed before " -"them (as they're applied left-to-right, and the most recently applied " -"filters take precedence over earlier ones)." +"filter`. When listing multiple filters on a single line (as for :envvar:" +"`PYTHONWARNINGS`), the individual filters are separated by commas and the " +"filters listed later take precedence over those listed before them (as " +"they're applied left-to-right, and the most recently applied filters take " +"precedence over earlier ones)." msgstr "" +"這些欄位中每一個的含義都如 :ref:`warning-filter` 中所述。當在單一行中列出多個" +"過濾器時(例如 :envvar:`PYTHONWARNINGS`),個別的過濾器會以逗號分隔,且後面列" +"出的過濾器優先於前面列出的過濾器(因為它們是從左到右應用的,而最近應用的過濾" +"器優先於較早的過濾器)。" #: ../../library/warnings.rst:218 msgid "" @@ -422,6 +491,8 @@ msgid "" "particular category, or warnings raised by particular modules or packages. " "Some examples::" msgstr "" +"常用的警告過濾器適用於所有警告、特定類別的警告,或由特定模組或套件引發的警" +"告。一些範例如下: ::" #: ../../library/warnings.rst:222 msgid "" @@ -435,10 +506,17 @@ msgid "" "\"mymodule\"\n" "error:::mymodule # Convert warnings to errors in \"mymodule\"" msgstr "" +"default # 顯示所有警告(即使是預設忽略的警告)\n" +"ignore # 忽略所有警告\n" +"error # 將所有警告轉換為錯誤\n" +"error::ResourceWarning # 將 ResourceWarning 訊息視為錯誤\n" +"default::DeprecationWarning # 顯示 DeprecationWarning 訊息\n" +"ignore,default:::mymodule # 只回報由 \"mymodule\" 觸發的警告\n" +"error:::mymodule # 將 \"mymodule\" 中的警告轉換為錯誤" #: ../../library/warnings.rst:234 msgid "Default Warning Filter" -msgstr "" +msgstr "預設警告過濾器" #: ../../library/warnings.rst:236 msgid "" @@ -446,12 +524,15 @@ msgid "" "by the :option:`-W` command-line option, the :envvar:`PYTHONWARNINGS` " "environment variable and calls to :func:`filterwarnings`." msgstr "" +"預設情況下,Python 會安裝數個警告過濾器,這些過濾器可以被 :option:`-W` 命令列" +"選項、:envvar:`PYTHONWARNINGS` 環境變數以及對 :func:`filterwarnings` 的呼叫所" +"覆寫。" #: ../../library/warnings.rst:240 msgid "" "In regular release builds, the default warning filter has the following " "entries (in order of precedence)::" -msgstr "" +msgstr "在常規的發行建置中,預設的警告過濾器有以下條目(按優先順序排列): ::" #: ../../library/warnings.rst:243 msgid "" @@ -471,19 +552,23 @@ msgstr "" msgid "" "In a :ref:`debug build `, the list of default warning filters " "is empty." -msgstr "" +msgstr "在 :ref:`偵錯建置 ` 中,預設警告過濾器串列是空的。" #: ../../library/warnings.rst:251 msgid "" -":exc:`DeprecationWarning` is now ignored by default in addition " -"to :exc:`PendingDeprecationWarning`." +":exc:`DeprecationWarning` is now ignored by default in addition to :exc:" +"`PendingDeprecationWarning`." msgstr "" +"除了 :exc:`PendingDeprecationWarning` 之外,:exc:`DeprecationWarning` 現在也" +"預設被忽略。" #: ../../library/warnings.rst:255 msgid "" ":exc:`DeprecationWarning` is once again shown by default when triggered " "directly by code in ``__main__``." msgstr "" +"當直接由 ``__main__`` 中的程式碼觸發時,:exc:`DeprecationWarning` 會再次預設" +"顯示。" #: ../../library/warnings.rst:259 msgid "" @@ -491,20 +576,26 @@ msgid "" "instead configured via :data:`sys.warnoptions` when :option:`-b` is " "specified twice." msgstr "" +":exc:`BytesWarning` 不再出現在預設過濾器串列中,而是在指定 :option:`-b` 兩次" +"時,透過 :data:`sys.warnoptions` 進行設定。" #: ../../library/warnings.rst:268 msgid "Overriding the default filter" -msgstr "" +msgstr "覆寫預設過濾器" #: ../../library/warnings.rst:270 msgid "" "Developers of applications written in Python may wish to hide *all* Python " "level warnings from their users by default, and only display them when " -"running tests or otherwise working on the application. " -"The :data:`sys.warnoptions` attribute used to pass filter configurations to " -"the interpreter can be used as a marker to indicate whether or not warnings " -"should be disabled::" +"running tests or otherwise working on the application. The :data:`sys." +"warnoptions` attribute used to pass filter configurations to the interpreter " +"can be used as a marker to indicate whether or not warnings should be " +"disabled::" msgstr "" +"以 Python 編寫的應用程式的開發者可能希望預設對其使用者隱藏 *所有* Python 層級" +"的警告,並且只在執行測試或以其他方式處理應用程式時才顯示它們。用於將過濾器設" +"定傳遞給直譯器的 :data:`sys.warnoptions` 屬性可以用作一個標記,以指示是否應停" +"用警告: ::" #: ../../library/warnings.rst:276 msgid "" @@ -526,6 +617,8 @@ msgid "" "that *all* warnings are displayed by default for the code under test, using " "code like::" msgstr "" +"建議 Python 程式碼的測試執行器開發者,應確保在預設情況下,為受測程式碼顯示 *" +"所有* 警告,可使用如下程式碼: ::" #: ../../library/warnings.rst:286 msgid "" @@ -536,6 +629,12 @@ msgid "" " warnings.simplefilter(\"default\") # Change the filter in this process\n" " os.environ[\"PYTHONWARNINGS\"] = \"default\" # Also affect subprocesses" msgstr "" +"import sys\n" +"\n" +"if not sys.warnoptions:\n" +" import os, warnings\n" +" warnings.simplefilter(\"default\") # 在此行程中更改過濾器\n" +" os.environ[\"PYTHONWARNINGS\"] = \"default\" # 也會影響子行程" #: ../../library/warnings.rst:293 msgid "" @@ -544,6 +643,9 @@ msgid "" "messages are made visible by default, using code like the following (where " "``user_ns`` is the module used to execute code entered interactively)::" msgstr "" +"最後,建議在 ``__main__`` 以外的命名空間中執行使用者程式碼的互動式 shell 開發" +"者,應確保 :exc:`DeprecationWarning` 訊息預設為可見,可使用如下程式碼(其中 " +"``user_ns`` 是用於執行互動式輸入程式碼的模組): ::" #: ../../library/warnings.rst:298 msgid "" @@ -557,7 +659,7 @@ msgstr "" #: ../../library/warnings.rst:306 msgid "Temporarily Suppressing Warnings" -msgstr "" +msgstr "暫時抑制警告" #: ../../library/warnings.rst:308 msgid "" @@ -566,6 +668,9 @@ msgid "" "have been explicitly configured via the command line), then it is possible " "to suppress the warning using the :class:`catch_warnings` context manager::" msgstr "" +"如果你正在使用的程式碼,你知道它會引發一個警告(例如一個已棄用的函式),但你" +"不想看到這個警告(即使警告已透過命令列明確設定),那麼可以使用 :class:" +"`catch_warnings` 情境管理器來抑制該警告: ::" #: ../../library/warnings.rst:313 msgid "" @@ -596,6 +701,10 @@ msgid "" "threaded application. If two or more threads use the :class:`catch_warnings` " "context manager at the same time, the behavior is undefined." msgstr "" +"在情境管理器中,所有警告都將被直接忽略。這允許你在使用已知的已棄用程式碼時不" +"必看到警告,同時又不會抑制其他可能不知道自己正在使用已棄用程式碼的程式碼所發" +"出的警告。注意:這只能在單一執行緒的應用程式中得到保證。如果兩個或多個執行緒" +"同時使用 :class:`catch_warnings` 情境管理器,其行為是未定義的。" #: ../../library/warnings.rst:334 msgid "Testing Warnings" @@ -608,6 +717,9 @@ msgid "" "facilitate your testing. For instance, do the following to capture all " "raised warnings to check::" msgstr "" +"要測試程式碼引發的警告,請使用 :class:`catch_warnings` 情境管理器。透過它,你" +"可以暫時改變警告過濾器以方便你的測試。例如,執行以下操作來捕獲所有引發的警告" +"以進行檢查: ::" #: ../../library/warnings.rst:341 msgid "" @@ -626,6 +738,20 @@ msgid "" " assert issubclass(w[-1].category, DeprecationWarning)\n" " assert \"deprecated\" in str(w[-1].message)" msgstr "" +"import warnings\n" +"\n" +"def fxn():\n" +" warnings.warn(\"deprecated\", DeprecationWarning)\n" +"\n" +"with warnings.catch_warnings(record=True) as w:\n" +" # 讓所有警告總是會被觸發。\n" +" warnings.simplefilter(\"always\")\n" +" # 觸發一個警告。\n" +" fxn()\n" +" # 驗證一些事情\n" +" assert len(w) == 1\n" +" assert issubclass(w[-1].category, DeprecationWarning)\n" +" assert \"deprecated\" in str(w[-1].message)" #: ../../library/warnings.rst:356 msgid "" @@ -635,6 +761,9 @@ msgid "" "filters are set the warning will not be seen again unless the warnings " "registry related to the warning has been cleared." msgstr "" +"也可以使用 ``error`` 而非 ``always`` 來讓所有警告都變成例外。需要注意的一點" +"是,如果一個警告因為 ``once``/``default`` 規則已經被引發過,那麼無論設定什麼" +"過濾器,這個警告都不會再出現,除非與該警告相關的警告註冊表已被清除。" #: ../../library/warnings.rst:362 msgid "" @@ -646,6 +775,11 @@ msgid "" "application. If two or more threads use the :class:`catch_warnings` context " "manager at the same time, the behavior is undefined." msgstr "" +"一旦情境管理器退出,警告過濾器就會恢復到進入情境時的狀態。這可以防止測試在不" +"同測試之間以意想不到的方式更改警告過濾器,從而導致不確定的測試結果。模組中" +"的 :func:`showwarning` 函式也會恢復到其原始值。注意:這只能在單一執行緒的應用" +"程式中得到保證。如果兩個或多個執行緒同時使用 :class:`catch_warnings` 情境管理" +"器,其行為是未定義的。" #: ../../library/warnings.rst:370 msgid "" @@ -656,10 +790,14 @@ msgid "" "continues to increase after each operation, or else delete the previous " "entries from the warnings list before each new operation)." msgstr "" +"在測試多個會引發同類警告的操作時,重要的是要以一種能確認每個操作都在引發新警" +"告的方式來進行測試(例如,將警告設定為引發例外,並檢查操作是否引發例外;檢查" +"警告串列的長度在每次操作後是否持續增加;或者在每次新操作前從警告串列中刪除先" +"前的條目)。" #: ../../library/warnings.rst:381 msgid "Updating Code For New Versions of Dependencies" -msgstr "" +msgstr "為新版相依套件更新程式碼" #: ../../library/warnings.rst:383 msgid "" @@ -667,6 +805,8 @@ msgid "" "(rather than end users of applications written in Python) are ignored by " "default." msgstr "" +"主要針對 Python 開發者(而非以 Python 編寫的應用程式的終端使用者)的警告類別" +"預設會被忽略。" #: ../../library/warnings.rst:386 msgid "" @@ -676,6 +816,10 @@ msgid "" "order to receive timely notifications of future breaking API changes " "(whether in the standard library or third party packages)." msgstr "" +"值得注意的是,這個「預設忽略」串列包括 :exc:`DeprecationWarning`(除了 " +"``__main__`` 以外的所有模組),這意味著開發者應該確保在測試他們的程式碼時,讓" +"通常被忽略的警告可見,以便及時收到未來 API 破壞性變更的通知(無論是在標準函式" +"庫還是第三方套件中)。" #: ../../library/warnings.rst:392 msgid "" @@ -683,6 +827,8 @@ msgid "" "runner will take care of implicitly enabling all warnings when running tests " "(the test runner provided by the :mod:`unittest` module does this)." msgstr "" +"在理想情況下,程式碼會有一個合適的測試套件,而測試執行器會在執行測試時負責隱" +"式地啟用所有警告(:mod:`unittest` 模組提供的測試執行器就是這樣做的)。" #: ../../library/warnings.rst:396 msgid "" @@ -695,10 +841,16 @@ msgid "" "W` (e.g. :option:`!-W error`). See the :option:`-W` flag for more details on " "what is possible." msgstr "" +"在較不理想的情況下,可以透過將 :option:`-Wd <-W>` 傳遞給 Python 直譯器(這" +"是 :option:`!-W default` 的簡寫)或在環境中設定 ``PYTHONWARNINGS=default`` 來" +"檢查應用程式是否使用了已棄用的介面。這會為所有警告啟用預設處理,包括那些預設" +"被忽略的警告。要更改對遇到的警告所採取的動作,你可以更改傳遞給 :option:`-W` " +"的引數(例如 :option:`!-W error`)。有關更多可能性的詳細資訊,請參閱 :option:" +"`-W` 旗標。" #: ../../library/warnings.rst:409 msgid "Available Functions" -msgstr "" +msgstr "可用的函式" #: ../../library/warnings.rst:414 msgid "" @@ -712,6 +864,13 @@ msgid "" "`. The *stacklevel* argument can be used by wrapper " "functions written in Python, like this::" msgstr "" +"發出一個警告,或者可能忽略它或引發一個例外。*category* 引數(如果提供)必須是" +"一個 :ref:`警告類別 `;它預設為 :exc:`UserWarning`。或" +"者,*message* 可以是一個 :exc:`Warning` 實例,在這種情況下 *category* 將被忽" +"略,並使用 ``message.__class__``。在這種情況下,訊息文本將是 " +"``str(message)``。如果發出的特定警告被 :ref:`警告過濾器 ` 轉" +"為錯誤,此函式會引發一個例外。*stacklevel* 引數可以被以 Python 編寫的包裝函式" +"使用,如下所示: ::" #: ../../library/warnings.rst:423 msgid "" @@ -727,6 +886,8 @@ msgid "" "the source of ``deprecated_api`` itself (since the latter would defeat the " "purpose of the warning message)." msgstr "" +"這會讓警告指向 ``deprecated_api`` 的呼叫者,而不是 ``deprecated_api`` 本身的" +"原始碼(因為後者會違背警告訊息的目的)。" #: ../../library/warnings.rst:430 msgid "" @@ -739,6 +900,11 @@ msgid "" "stacklevel)``. To cause a warning to be attributed to the caller from " "outside of the current package you might write::" msgstr "" +"*skip_file_prefixes* 關鍵字引數可用於指示在計算堆疊層級時應忽略哪些堆疊幀。當" +"你希望警告總是在套件外部的呼叫點出現,而固定的 *stacklevel* 不適用於所有呼叫" +"路徑或難以維護時,這會很有用。如果提供,它必須是一個字串的元組。當提供前綴" +"時,stacklevel 會被隱式地覆寫為 ``max(2, stacklevel)``。要讓警告歸因於目前套" +"件外部的呼叫者,你可以這樣寫: ::" #: ../../library/warnings.rst:439 msgid "" @@ -756,6 +922,19 @@ msgid "" "def another_way(**kw):\n" " lower.one_way(**kw)" msgstr "" +"# example/lower.py\n" +"_warn_skips = (os.path.dirname(__file__),)\n" +"\n" +"def one_way(r_luxury_yacht=None, t_wobbler_mangrove=None):\n" +" if r_luxury_yacht:\n" +" warnings.warn(\"Please migrate to t_wobbler_mangrove=.\",\n" +" skip_file_prefixes=_warn_skips)\n" +"\n" +"# example/higher.py\n" +"from . import lower\n" +"\n" +"def another_way(**kw):\n" +" lower.one_way(**kw)" #: ../../library/warnings.rst:453 msgid "" @@ -763,12 +942,14 @@ msgid "" "``package.higher.another_way()`` call sites only from calling code living " "outside of ``example`` package." msgstr "" +"這使得警告只會從存在於 ``example`` 套件之外的呼叫程式碼中,指向 ``example." +"lower.one_way()`` 和 ``package.higher.another_way()`` 的呼叫點。" #: ../../library/warnings.rst:457 ../../library/warnings.rst:483 msgid "" -"*source*, if supplied, is the destroyed object which emitted " -"a :exc:`ResourceWarning`." -msgstr "" +"*source*, if supplied, is the destroyed object which emitted a :exc:" +"`ResourceWarning`." +msgstr "*source*\\ (如果提供)是發出 :exc:`ResourceWarning` 的已銷毀物件。" #: ../../library/warnings.rst:460 msgid "Added *source* parameter." @@ -789,6 +970,11 @@ msgid "" "of :exc:`Warning` or *message* may be a :exc:`Warning` instance, in which " "case *category* will be ignored." msgstr "" +"這是一個 :func:`warn` 功能的低階介面,明確傳入訊息、類別、檔名和行號,以及可" +"選的模組名稱和註冊表(應為模組的 ``__warningregistry__`` 字典)。模組名稱預設" +"為去掉 ``.py`` 的檔名;如果沒有傳入註冊表,警告將永遠不會被抑制。*message* 必" +"須是字串,*category* 必須是 :exc:`Warning` 的子類別,或者 *message* 可以是 :" +"exc:`Warning` 的實例,在這種情況下 *category* 將被忽略。" #: ../../library/warnings.rst:478 msgid "" @@ -797,6 +983,8 @@ msgid "" "displaying source for modules found in zipfiles or other non-filesystem " "import sources)." msgstr "" +"*module_globals*\\ (如果提供)應該是發出警告的程式碼所使用的全域命名空間。(此" +"引數用於支援顯示在 zip 檔案或其他非檔案系統引入來源中找到的模組的原始碼)。" #: ../../library/warnings.rst:486 msgid "Add the *source* parameter." @@ -807,20 +995,28 @@ msgid "" "Write a warning to a file. The default implementation calls " "``formatwarning(message, category, filename, lineno, line)`` and writes the " "resulting string to *file*, which defaults to :data:`sys.stderr`. You may " -"replace this function with any callable by assigning to " -"``warnings.showwarning``. *line* is a line of source code to be included in " -"the warning message; if *line* is not supplied, :func:`showwarning` will try " -"to read the line specified by *filename* and *lineno*." +"replace this function with any callable by assigning to ``warnings." +"showwarning``. *line* is a line of source code to be included in the warning " +"message; if *line* is not supplied, :func:`showwarning` will try to read the " +"line specified by *filename* and *lineno*." msgstr "" +"將警告寫入一個檔案。預設實作會呼叫 ``formatwarning(message, category, " +"filename, lineno, line)`` 並將結果字串寫入 *file*,預設為 :data:`sys." +"stderr`。你可以透過賦值給 ``warnings.showwarning`` 來用任何可呼叫物件取代此函" +"式。*line* 是要包含在警告訊息中的一行原始碼;如果未提供 *line*,:func:" +"`showwarning` 將嘗試讀取由 *filename* 和 *lineno* 指定的行。" #: ../../library/warnings.rst:503 msgid "" "Format a warning the standard way. This returns a string which may contain " "embedded newlines and ends in a newline. *line* is a line of source code to " -"be included in the warning message; if *line* is not " -"supplied, :func:`formatwarning` will try to read the line specified by " -"*filename* and *lineno*." +"be included in the warning message; if *line* is not supplied, :func:" +"`formatwarning` will try to read the line specified by *filename* and " +"*lineno*." msgstr "" +"以標準方式格式化警告。這會回傳一個可能包含嵌入換行符並以換行符結尾的字串。" +"*line* 是要包含在警告訊息中的一行原始碼;如果未提供 *line*,:func:" +"`formatwarning` 將嘗試讀取由 *filename* 和 *lineno* 指定的行。" #: ../../library/warnings.rst:512 msgid "" @@ -833,15 +1029,23 @@ msgid "" "particular warning. Omitted arguments default to a value that matches " "everything." msgstr "" +"在 :ref:`警告過濾器規格 ` 串列中插入一個條目。預設情況下,條" +"目會插入到最前面;如果 *append* 為 true,則會插入到最後面。這會檢查引數的型" +"別,編譯 *message* 和 *module* 的正規表示式,並將它們作為一個元組插入到警告過" +"濾器串列中。如果兩個條目都匹配一個特定的警告,那麼串列中較靠前的條目會覆寫較" +"後面的條目。省略的引數預設為一個能匹配所有內容的值。" #: ../../library/warnings.rst:524 msgid "" "Insert a simple entry into the list of :ref:`warnings filter specifications " -"`. The meaning of the function parameters is as " -"for :func:`filterwarnings`, but regular expressions are not needed as the " -"filter inserted always matches any message in any module as long as the " -"category and line number match." +"`. The meaning of the function parameters is as for :func:" +"`filterwarnings`, but regular expressions are not needed as the filter " +"inserted always matches any message in any module as long as the category " +"and line number match." msgstr "" +"在 :ref:`警告過濾器規格 ` 串列中插入一個簡單的條目。函式參數" +"的含義與 :func:`filterwarnings` 相同,但不需要正規表示式,因為只要類別和行號" +"匹配,插入的過濾器總是會匹配任何模組中的任何訊息。" #: ../../library/warnings.rst:533 msgid "" @@ -849,10 +1053,12 @@ msgid "" "to :func:`filterwarnings`, including that of the :option:`-W` command line " "options and calls to :func:`simplefilter`." msgstr "" +"重設警告過濾器。這會捨棄所有先前對 :func:`filterwarnings` 的呼叫效果,包括 :" +"option:`-W` 命令列選項和對 :func:`simplefilter` 的呼叫。" #: ../../library/warnings.rst:540 msgid "Decorator to indicate that a class, function or overload is deprecated." -msgstr "" +msgstr "用來指示一個類別、函式或重載 (overload) 已被棄用的裝飾器。" #: ../../library/warnings.rst:542 msgid "" @@ -861,10 +1067,13 @@ msgid "" "` will also generate a diagnostic on usage of the " "deprecated object." msgstr "" +"當此裝飾器應用於一個物件時,在使用該物件時,可能會在 runtime 發出棄用警告。:" +"term:`靜態型別檢查器 ` 也會在使用已棄用物件時產生診斷訊" +"息。" #: ../../library/warnings.rst:547 msgid "Usage::" -msgstr "" +msgstr "用法: ::" #: ../../library/warnings.rst:549 msgid "" @@ -885,6 +1094,22 @@ msgid "" "@overload\n" "def g(x: str) -> int: ..." msgstr "" +"from warnings import deprecated\n" +"from typing import overload\n" +"\n" +"@deprecated(\"改用 B\")\n" +"class A:\n" +" pass\n" +"\n" +"@deprecated(\"改用 g\")\n" +"def f():\n" +" pass\n" +"\n" +"@overload\n" +"@deprecated(\"對 int 的支援已棄用\")\n" +"def g(x: int) -> int: ...\n" +"@overload\n" +"def g(x: str) -> int: ..." #: ../../library/warnings.rst:566 msgid "" @@ -897,35 +1122,47 @@ msgid "" "further up the stack. Static type checker behavior is not affected by the " "*category* and *stacklevel* arguments." msgstr "" +"由 *category* 指定的警告將在使用已棄用物件時於 runtime 發出。對於函式,這發生" +"在呼叫時;對於類別,發生在實例化和建立子類別時。如果 *category* 是 ``None``," +"則在 runtime 不會發出警告。*stacklevel* 決定了警告發出的位置。如果它是 ``1``\\ " +"(預設值),警告會在已棄用物件的直接呼叫者處發出;如果更高,它會在堆疊的更上" +"層發出。靜態型別檢查器的行為不受 *category* 和 *stacklevel* 引數的影響。" #: ../../library/warnings.rst:577 msgid "" "The deprecation message passed to the decorator is saved in the " "``__deprecated__`` attribute on the decorated object. If applied to an " -"overload, the decorator must be after the :func:`@overload " -"` decorator for the attribute to exist on the overload as " -"returned by :func:`typing.get_overloads`." +"overload, the decorator must be after the :func:`@overload ` decorator for the attribute to exist on the overload as returned " +"by :func:`typing.get_overloads`." msgstr "" +"傳遞給裝飾器的棄用訊息會儲存在被裝飾物件的 ``__deprecated__`` 屬性中。如果應" +"用於重載,裝飾器必須在 :func:`@overload ` 裝飾器之後,這樣屬" +"性才會存在於 :func:`typing.get_overloads` 回傳的重載上。" #: ../../library/warnings.rst:584 msgid "See :pep:`702`." -msgstr "" +msgstr "參閱 :pep:`702`。" #: ../../library/warnings.rst:589 msgid "Available Context Managers" -msgstr "" +msgstr "可用的情境管理器" #: ../../library/warnings.rst:593 msgid "" "A context manager that copies and, upon exit, restores the warnings filter " -"and the :func:`showwarning` function. If the *record* argument " -"is :const:`False` (the default) the context manager returns :class:`None` on " -"entry. If *record* is :const:`True`, a list is returned that is " -"progressively populated with objects as seen by a custom :func:`showwarning` " -"function (which also suppresses output to ``sys.stdout``). Each object in " -"the list has attributes with the same names as the arguments " -"to :func:`showwarning`." -msgstr "" +"and the :func:`showwarning` function. If the *record* argument is :const:" +"`False` (the default) the context manager returns :class:`None` on entry. If " +"*record* is :const:`True`, a list is returned that is progressively " +"populated with objects as seen by a custom :func:`showwarning` function " +"(which also suppresses output to ``sys.stdout``). Each object in the list " +"has attributes with the same names as the arguments to :func:`showwarning`." +msgstr "" +"一個情境管理器,它會複製並在退出時恢復警告過濾器和 :func:`showwarning` 函式。" +"如果 *record* 引數為 :const:`False`\\ (預設值),情境管理器在進入時回傳 :class:" +"`None`。如果 *record* 為 :const:`True`,則會回傳一個串列,該串列會由自訂的 :" +"func:`showwarning` 函式(該函式也會抑制對 ``sys.stdout`` 的輸出)所看到的物件" +"逐步填充。串列中的每個物件都具有與 :func:`showwarning` 的引數同名的屬性。" #: ../../library/warnings.rst:602 msgid "" @@ -933,6 +1170,8 @@ msgid "" "returned when you import :mod:`warnings` whose filter will be protected. " "This argument exists primarily for testing the :mod:`warnings` module itself." msgstr "" +"*module* 引數接受一個模組,用以取代預設的 :mod:`warnings` 模組,而該(被傳" +"入)模組的過濾器將會受到保護。此引數主要用於測試 :mod:`warnings` 模組本身。" #: ../../library/warnings.rst:607 msgid "" @@ -940,12 +1179,14 @@ msgid "" "to :func:`simplefilter` as if it were called immediately on entering the " "context." msgstr "" +"如果 *action* 引數不是 ``None``,則其餘引數會傳遞給 :func:`simplefilter`,就" +"像在進入情境時立即呼叫它一樣。" #: ../../library/warnings.rst:611 msgid "" "See :ref:`warning-filter` for the meaning of the *category* and *lineno* " "parameters." -msgstr "" +msgstr "有關 *category* 和 *lineno* 參數的含義,請參閱 :ref:`warning-filter`。" #: ../../library/warnings.rst:616 msgid "" @@ -954,6 +1195,9 @@ msgid "" "filter specifications. This means the context manager is modifying global " "state and therefore is not thread-safe." msgstr "" +":class:`catch_warnings` 管理器的工作原理是替換然後再恢復模組的 :func:" +"`showwarning` 函式和內部過濾器規格串列。這意味著情境管理器正在修改全域狀態," +"因此不是執行緒安全的。" #: ../../library/warnings.rst:624 msgid "Added the *action*, *category*, *lineno*, and *append* parameters."