diff --git a/howto/logging.po b/howto/logging.po index a8a3738ef3..2f3ac5a7dc 100644 --- a/howto/logging.po +++ b/howto/logging.po @@ -1,9 +1,9 @@ -# SOME DESCRIPTIVE TITLE. -# Copyright (C) 2001-2022, Python Software Foundation +# Copyright (C) 2001-2024, Python Software Foundation # This file is distributed under the same license as the Python package. # # Translators: # 文俊 高 , 2016 +# CTHua , 2023 msgid "" msgstr "" "Project-Id-Version: Python 3.12\n" @@ -18,10 +18,11 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Weblate 4.16.4\n" #: ../../howto/logging.rst:3 msgid "Logging HOWTO" -msgstr "如何使用 Logging 模組" +msgstr "如何使用日誌記錄 (Logging)" #: ../../howto/logging.rst:0 msgid "Author" @@ -32,10 +33,13 @@ msgid "Vinay Sajip " msgstr "Vinay Sajip " #: ../../howto/logging.rst:11 +#, fuzzy msgid "" "This page contains tutorial information. For links to reference information " "and a logging cookbook, please see :ref:`tutorial-ref-links`." msgstr "" +"此頁面包含教學資訊。有關參考資訊和日誌記錄手冊的鏈接,請參閱 :ref:`tutorial-" +"ref-links`。" #: ../../howto/logging.rst:15 msgid "Basic Logging Tutorial" @@ -67,19 +71,22 @@ msgid "" "func:`critical`. To determine when to use logging, see the table below, " "which states, for each of a set of common tasks, the best tool to use for it." msgstr "" +"日誌(Logging)提供方便使用的一組簡單紀錄函式。這些函式包括::func:`debug`、:" +"func:`info`、:func:`warning`、:func:`error` 和 :func:`critical`。如需確定何時" +"使用紀錄,請參見以下表格,其中列出每個常見工作的最佳工具。" #: ../../howto/logging.rst:34 msgid "Task you want to perform" -msgstr "" +msgstr "你想要執行的任務" #: ../../howto/logging.rst:34 msgid "The best tool for the task" -msgstr "" +msgstr "此任務最好的工具" #: ../../howto/logging.rst:36 msgid "" "Display console output for ordinary usage of a command line script or program" -msgstr "" +msgstr "對於命令行或程式的普通用法,結果會顯示在控制台" #: ../../howto/logging.rst:36 msgid ":func:`print`" @@ -89,49 +96,57 @@ msgstr ":func:`print`" msgid "" "Report events that occur during normal operation of a program (e.g. for " "status monitoring or fault investigation)" -msgstr "" +msgstr "報告在程式正常操作期間發生的事件(例如用於狀態監視或故障調查)" #: ../../howto/logging.rst:40 msgid "" ":func:`logging.info` (or :func:`logging.debug` for very detailed output for " "diagnostic purposes)" msgstr "" +":func:`logging.info` (或者在需要診斷用的詳細輸出時使用 :func:`logging." +"debug` )" #: ../../howto/logging.rst:45 msgid "Issue a warning regarding a particular runtime event" -msgstr "" +msgstr "針對特定的運行時事件發出警告" #: ../../howto/logging.rst:45 msgid "" ":func:`warnings.warn` in library code if the issue is avoidable and the " "client application should be modified to eliminate the warning" msgstr "" +"如果問題是可以避免的,那麼客戶端應該修改以消除警告,請在庫程式碼中使用 :func:" +"`warnings.warn` 警告" #: ../../howto/logging.rst:50 msgid "" ":func:`logging.warning` if there is nothing the client application can do " "about the situation, but the event should still be noted" msgstr "" +"如果客戶端應用程式無法處理該情況,但該事件仍應注意,可以使用 :func:`logging." +"warning`" #: ../../howto/logging.rst:55 msgid "Report an error regarding a particular runtime event" -msgstr "" +msgstr "回報與特定執行階段事件相關的錯誤" #: ../../howto/logging.rst:55 msgid "Raise an exception" -msgstr "" +msgstr "引發例外" #: ../../howto/logging.rst:58 msgid "" "Report suppression of an error without raising an exception (e.g. error " "handler in a long-running server process)" -msgstr "" +msgstr "報告錯誤但不引發異常(如長時間執行的伺服器進程中的錯誤處理程序)" #: ../../howto/logging.rst:58 msgid "" ":func:`logging.error`, :func:`logging.exception` or :func:`logging.critical` " "as appropriate for the specific error and application domain" msgstr "" +"根據錯誤及應用領域的特定需要,使用 :func:`logging.error`、:func:`logging." +"exception` 或 :func:`logging.critical`" #: ../../howto/logging.rst:65 msgid "" @@ -139,14 +154,16 @@ msgid "" "they are used to track. The standard levels and their applicability are " "described below (in increasing order of severity):" msgstr "" +"日誌紀錄函式的命名方式是根據它們所用於追蹤的事件等級或嚴重程度。以下是標準等" +"級及其可應用的範圍說明(按嚴重程度遞增排序):" #: ../../howto/logging.rst:72 ../../howto/logging.rst:866 msgid "Level" -msgstr "" +msgstr "等級" #: ../../howto/logging.rst:72 msgid "When it's used" -msgstr "" +msgstr "何時使用" #: ../../howto/logging.rst:74 ../../howto/logging.rst:876 msgid "``DEBUG``" @@ -155,7 +172,7 @@ msgstr "``DEBUG``" #: ../../howto/logging.rst:74 msgid "" "Detailed information, typically of interest only when diagnosing problems." -msgstr "" +msgstr "詳細的資訊,僅在診斷問題時才會有用。" #: ../../howto/logging.rst:77 ../../howto/logging.rst:874 msgid "``INFO``" @@ -163,7 +180,7 @@ msgstr "``INFO``" #: ../../howto/logging.rst:77 msgid "Confirmation that things are working as expected." -msgstr "" +msgstr "確認一切都按預期運作。" #: ../../howto/logging.rst:80 ../../howto/logging.rst:872 msgid "``WARNING``" @@ -175,6 +192,8 @@ msgid "" "problem in the near future (e.g. 'disk space low'). The software is still " "working as expected." msgstr "" +"一種意外發生的徵兆,或是暗示著未來可能出現問題(例如:「磁碟空間不足」),程" +"式還在按照預期運作。" #: ../../howto/logging.rst:85 ../../howto/logging.rst:870 msgid "``ERROR``" @@ -184,7 +203,7 @@ msgstr "``ERROR``" msgid "" "Due to a more serious problem, the software has not been able to perform " "some function." -msgstr "" +msgstr "因為有更嚴重的問題,軟體無法執行某些功能。" #: ../../howto/logging.rst:88 ../../howto/logging.rst:868 msgid "``CRITICAL``" @@ -194,7 +213,7 @@ msgstr "``CRITICAL``" msgid "" "A serious error, indicating that the program itself may be unable to " "continue running." -msgstr "" +msgstr "嚴重錯誤,表示此程式本身可能無法繼續執行。" #: ../../howto/logging.rst:92 msgid "" @@ -202,6 +221,8 @@ msgid "" "and above will be tracked, unless the logging package is configured to do " "otherwise." msgstr "" +"預設的級別是「警告」(``WARNING``),這意味著除非配置記錄器套件進行其他設定,否" +"則只會追蹤這個級別以上的事件。" #: ../../howto/logging.rst:96 msgid "" @@ -209,6 +230,8 @@ msgid "" "of handling tracked events is to print them to the console. Another common " "way is to write them to a disk file." msgstr "" +"被追蹤的事件可以採取不同的處理方式。處理追蹤事件最簡單的方法是將它們輸出到控" +"制台。另一個常見的方法是將它們寫入磁盤文件。" #: ../../howto/logging.rst:104 msgid "A simple example" @@ -216,14 +239,11 @@ msgstr "一個簡單範例" #: ../../howto/logging.rst:106 msgid "A very simple example is::" -msgstr "" -"一個非常簡單的例子是:\n" -"\n" -"::" +msgstr "在這裡舉一個簡單的例子: ::" #: ../../howto/logging.rst:112 msgid "If you type these lines into a script and run it, you'll see:" -msgstr "" +msgstr "若你將這幾行程式碼加入腳本中並且運行,你就能看到:" #: ../../howto/logging.rst:118 msgid "" @@ -234,10 +254,14 @@ msgid "" "explained later. The actual output can be formatted quite flexibly if you " "need that; formatting options will also be explained later." msgstr "" +"這段訊息顯示在控制台上。由於預設級別為 ``WARNING``,所以 ``INFO`` 訊息並未出" +"現。印出的訊息包含級別以及在 logging 呼叫中提供的事件說明,例如 'Watch " +"out!'。目前不必擔心 'root' 部分,稍後將會說明。如果你需要的話,可以彈性地格式" +"化實際輸出;相關選項也將在稍後說明。" #: ../../howto/logging.rst:127 msgid "Logging to a file" -msgstr "" +msgstr "將日誌寫入檔案" #: ../../howto/logging.rst:129 msgid "" @@ -246,6 +270,8 @@ msgid "" "Python interpreter, and don't just continue from the session described " "above::" msgstr "" +"一個非常普遍的情況是將日誌事件記錄在文件中,因此讓我們接著看看這個情況。請務" +"必在新啟動的 Python 直譯器中嘗試以下操作,而不是繼續以上描述的會話: ::" #: ../../howto/logging.rst:140 msgid "" @@ -255,12 +281,15 @@ msgid "" "passed, which determines how encoding errors are handled. For available " "values and the default, see the documentation for :func:`open`." msgstr "" +"新增了 *encoding* 引數。在早期的 Python 版本中,如果未指定,將使用 :func:" +"`open` 的預設編碼。儘管在上面的範例中沒有顯示,現在也可以傳遞 *errors* 引數," +"以決定如何處理編碼錯誤。可用的值與其預設值,請參閱 :func:`open` 的文件。" #: ../../howto/logging.rst:147 msgid "" "And now if we open the file and look at what we have, we should find the log " "messages:" -msgstr "" +msgstr "現在,如果我們打開文件並查看其內容,我們應該能夠找到日誌訊息:" #: ../../howto/logging.rst:157 msgid "" @@ -268,17 +297,21 @@ msgid "" "threshold for tracking. In this case, because we set the threshold to " "``DEBUG``, all of the messages were printed." msgstr "" +"這個範例同時也展示了如何設定日誌紀錄等級作為追蹤的門檻。在這個例子中,因為門" +"檻被設為 ``DEBUG``,所以所有的訊息都會被印出來。" #: ../../howto/logging.rst:161 msgid "" "If you want to set the logging level from a command-line option such as:" -msgstr "" +msgstr "如果你想要從命令列選項設置日誌級別,例如:" #: ../../howto/logging.rst:167 msgid "" "and you have the value of the parameter passed for ``--log`` in some " "variable *loglevel*, you can use::" msgstr "" +"如果你已經將 ``--log`` 引數的值存儲在某個變數 *loglevel* 中,你可以使用以下方" +"式: ::" #: ../../howto/logging.rst:172 msgid "" @@ -286,6 +319,8 @@ msgid "" "argument. You may want to error check any user input value, perhaps as in " "the following example::" msgstr "" +"要取得值以傳遞給 :func:`basicConfig` 的 *level* 引數,你可能會想檢查任何使用" +"者輸入的值,如下面的示例所示: ::" #: ../../howto/logging.rst:184 msgid "" @@ -295,6 +330,10 @@ msgid "" "off simple configuration facility, only the first call will actually do " "anything: subsequent calls are effectively no-ops." msgstr "" +":func:`basicConfig` 的呼叫應該放在任何關於 :func:`debug` 、 :func:`info` 等的" +"呼叫 *之前* ,否則這些功能就會以預設選項自動呼叫 :func:`basicConfig`。由於它" +"旨在作為一次性的簡單配置工具,只有第一個呼叫才能真正執行:後續的呼叫基本上是" +"無操作(no-ops)。" #: ../../howto/logging.rst:190 msgid "" @@ -303,26 +342,30 @@ msgid "" "afresh, not remembering the messages from earlier runs, you can specify the " "*filemode* argument, by changing the call in the above example to::" msgstr "" +"如果你多次運行上面的腳本,就會將每次成功執行時的訊息添加到名為 *example.log* " +"檔案中。如果你希望每次都從頭開始,不記住以前運行時的訊息,則可以指定 " +"*filemode* 引數,在上面範例中更改呼叫方式如下所示: ::" #: ../../howto/logging.rst:197 msgid "" "The output will be the same as before, but the log file is no longer " "appended to, so the messages from earlier runs are lost." msgstr "" +"輸出會和之前一樣,但不再新增在舊的紀錄檔內,因此之前執行的訊息都遺失了。" #: ../../howto/logging.rst:202 msgid "Logging from multiple modules" -msgstr "" +msgstr "紀錄多個模組" #: ../../howto/logging.rst:204 msgid "" "If your program consists of multiple modules, here's an example of how you " "could organize logging in it::" -msgstr "" +msgstr "如果你的程式包含多個模組,以下是一個有關如何組織日誌紀錄的範例: ::" #: ../../howto/logging.rst:228 msgid "If you run *myapp.py*, you should see this in *myapp.log*:" -msgstr "" +msgstr "當你執行 *myapp.py*,你會看到以下訊息在 *myapp.log*:" #: ../../howto/logging.rst:236 msgid "" @@ -334,20 +377,26 @@ msgid "" "to refer to the documentation beyond the tutorial level -- see :ref:`logging-" "advanced-tutorial`." msgstr "" +"是你應該看到的。你可以將此應用到多個模組,使用 *mylib.py* 中的模式。請注意," +"在這個簡單的使用模式下,除非查看事件描述,不然你無法透過查看日誌檔案得知訊息" +"來自於應用程式的哪個位置。若你要追蹤訊息的位置,請參考進階教學的文件--參閱 :" +"ref:`logging-advanced-tutorial`。" #: ../../howto/logging.rst:246 msgid "Logging variable data" -msgstr "" +msgstr "紀錄變數數據" #: ../../howto/logging.rst:248 msgid "" "To log variable data, use a format string for the event description message " "and append the variable data as arguments. For example::" msgstr "" +"為了紀錄變數資料,請使用格式字串作為事件描述訊息,並將變數資料逐一附加為引" +"數。例如: ::" #: ../../howto/logging.rst:254 msgid "will display:" -msgstr "" +msgstr "會顯示:" #: ../../howto/logging.rst:260 msgid "" @@ -358,20 +407,25 @@ msgid "" "options *are* supported, but exploring them is outside the scope of this " "tutorial: see :ref:`formatting-styles` for more information." msgstr "" +"正如你所看到的,將變量數據合併到事件描述消息中使用的是舊的 `%` 樣式的字符串格" +"式化方式。這是出於向後兼容,logging 包的發布日期先於新的格式化選項,如 :meth:" +"`str.format` 方法和 :class:`string.Template` 類別。雖然支援這些新的格式化選" +"項,但是探索這些選項超出了本教程的範圍:請參閱 :ref:`formatting-styles` 獲取" +"更多信息。" #: ../../howto/logging.rst:269 msgid "Changing the format of displayed messages" -msgstr "" +msgstr "變更顯示訊息的格式" #: ../../howto/logging.rst:271 msgid "" "To change the format which is used to display messages, you need to specify " "the format you want to use::" -msgstr "" +msgstr "如果你要變更顯示訊息使用的格式,需要指定你想使用的格式,如下: ::" #: ../../howto/logging.rst:280 msgid "which would print:" -msgstr "" +msgstr "將會印出:" #: ../../howto/logging.rst:288 msgid "" @@ -382,20 +436,25 @@ msgid "" "including variable data) and perhaps to display when the event occurred. " "This is described in the next section." msgstr "" +"需要注意的是,前面範例中出現的'root'已經消失。對於可以出現在格式字串中的完整" +"內容,你可以參閱 :ref:`logrecord-attributes` 的文件,簡單的使用方法是,只使" +"用 *levelname* (嚴重性)、*message* (事件描述,包括變數的值)和可能的顯示事" +"件發生時間。下一個段落會解釋這個。" #: ../../howto/logging.rst:297 msgid "Displaying the date/time in messages" -msgstr "" +msgstr "在訊息中顯示日期/時間" #: ../../howto/logging.rst:299 msgid "" "To display the date and time of an event, you would place '%(asctime)s' in " "your format string::" msgstr "" +"如果想要顯示事件的日期和時間,你可以在你的格式化字串中放置 '%(asctime)s': ::" #: ../../howto/logging.rst:306 msgid "which should print something like this:" -msgstr "" +msgstr "會顯示以下訊息:" #: ../../howto/logging.rst:312 msgid "" @@ -403,20 +462,22 @@ msgid "" "rfc:`3339`. If you need more control over the formatting of the date/time, " "provide a *datefmt* argument to ``basicConfig``, as in this example::" msgstr "" +"預設的時間/日期格式遵照 ISO8601 或 :rfc:`3339`。如果你想要有更多的時間/日期自" +"訂性,可以在 ``basicConfig`` 傳入 *datefmt* 的引數,如以下範例: ::" #: ../../howto/logging.rst:320 msgid "which would display something like this:" -msgstr "" +msgstr "會顯示以下訊息:" #: ../../howto/logging.rst:326 msgid "" "The format of the *datefmt* argument is the same as supported by :func:`time." "strftime`." -msgstr "" +msgstr "*datefmt* 引數的格式與 :func:`time.strftime` 支援的格式相同。" #: ../../howto/logging.rst:331 msgid "Next Steps" -msgstr "" +msgstr "下一步" #: ../../howto/logging.rst:333 msgid "" @@ -426,6 +487,9 @@ msgid "" "time in reading the following sections. If you're ready for that, grab some " "of your favourite beverage and carry on." msgstr "" +"這個基礎教學就到這裡了。它應該足以讓你開始使用記錄功能。日誌套件還提供了更多" +"功能,但如果想要充分利用它,你需要再花些時間閱讀以下部分。如果你準備好了,就" +"拿起你喜愛的飲料繼續閱讀吧。" #: ../../howto/logging.rst:339 msgid "" @@ -435,6 +499,10 @@ msgid "" "group (available at https://groups.google.com/g/comp.lang.python) and you " "should receive help before too long." msgstr "" +"如果你需要一個簡單的日誌記錄的功能,可以參考上面的例子將它添加到你自己的腳本" +"中。如果你遇到問題或不理解某些內容,可以在comp.lang.python Usenet 群組(網" +"址:https://groups.google.com/forum/#!forum/comp.lang.python)上發問,你會很" +"快得到幫助。" #: ../../howto/logging.rst:345 msgid "" @@ -442,42 +510,51 @@ msgid "" "slightly more advanced/in-depth tutorial than the basic one above. After " "that, you can take a look at the :ref:`logging-cookbook`." msgstr "" +"還在嗎?你可以繼續閱讀下面幾節,這比上面的基礎教學稍微進階/深入一些。之後,你" +"可以看看 :ref:`logging-cookbook`。" #: ../../howto/logging.rst:353 msgid "Advanced Logging Tutorial" -msgstr "" +msgstr "進階日誌記錄教學" #: ../../howto/logging.rst:355 +#, fuzzy msgid "" "The logging library takes a modular approach and offers several categories " "of components: loggers, handlers, filters, and formatters." msgstr "" +"日誌記錄庫採用模組化方法,並提供多種類別的元件:記錄器、處理程序、篩選器和格" +"式化程式。" #: ../../howto/logging.rst:358 msgid "Loggers expose the interface that application code directly uses." -msgstr "" +msgstr "記錄器(logger)公開應用程式可以直接使用的介面。" #: ../../howto/logging.rst:359 msgid "" "Handlers send the log records (created by loggers) to the appropriate " "destination." msgstr "" +"處理器 (handlers)將由記錄器 (loggers)建立的日誌紀錄 (log records) 傳送" +"到適當的目的地。" #: ../../howto/logging.rst:361 msgid "" "Filters provide a finer grained facility for determining which log records " "to output." -msgstr "" +msgstr "過濾器 (filters) 提供更精細的機制來決定輸出哪些日誌記錄。" #: ../../howto/logging.rst:363 msgid "Formatters specify the layout of log records in the final output." -msgstr "" +msgstr "格式化(formatters)器指定最終輸出中日誌記錄的佈局。" #: ../../howto/logging.rst:365 msgid "" "Log event information is passed between loggers, handlers, filters and " "formatters in a :class:`LogRecord` instance." msgstr "" +"日誌事件(log event)資訊在記錄器、處理器、 過濾器和格式化器之間透過 :class:" +"`LogRecord` 實例傳遞。" #: ../../howto/logging.rst:368 msgid "" @@ -489,18 +566,26 @@ msgid "" "want, and indicate the area of an application in which a logged message " "originates." msgstr "" +"紀錄是透過呼叫 :class:`Logger` 類別的實例方法(以下稱為 :dfn:`loggers` )來執" +"行。每個實例都有一個名稱,並藉由用點(句號)作為分隔符號的命名空間層次來進行" +"概念化排列。例如,名為 'scan' 的 logger 父級是記錄器 'scan.text'、'scan." +"html' 及 'scan.pdf'。記錄器名稱可以取任何你想要的,並且表示一個應用程式中產生" +"紀錄訊息的區域。" #: ../../howto/logging.rst:375 msgid "" "A good convention to use when naming loggers is to use a module-level " "logger, in each module which uses logging, named as follows::" msgstr "" +"命名記錄器的一個良好慣例是在每個使用記錄的模組中,使用模組級別的記錄器,命名" +"如下: ::" #: ../../howto/logging.rst:380 msgid "" "This means that logger names track the package/module hierarchy, and it's " "intuitively obvious where events are logged just from the logger name." msgstr "" +"這意味著日誌名稱追踪套件/模組階層,因此從日誌名稱可以直觀明瞭事件的記錄位置。" #: ../../howto/logging.rst:383 msgid "" @@ -510,6 +595,10 @@ msgid "" "the root logger. The functions and the methods have the same signatures. The " "root logger's name is printed as 'root' in the logged output." msgstr "" +"記錄器等級中階層的根稱為根記錄器。這是由函式 :func:`debug`、:func:`info`、:" +"func:`warning`、:func:`error` 和 :func:`critical` 使用的記錄器,這些函式僅調" +"用根記錄器的同名方法。這些函式和方法具有相同的簽章(signature)。根記錄器的名" +"稱在記錄輸出中顯示為 'root'。" #: ../../howto/logging.rst:389 msgid "" @@ -521,6 +610,11 @@ msgid "" "destination class if you have special requirements not met by any of the " "built-in handler classes." msgstr "" +"當然,以不同的目的地記錄訊息是可能的。該套件支援將日誌訊息寫入檔案、HTTP GET/" +"POST 位置、透過 SMTP 的電子郵件、通用的 sockets、隊列、或像 syslog 或 " +"Windows NT 事件日誌等作業系統特定的日誌機制。這些目的地由 :dfn:`handler` 類別" +"提供服務。如果你有特殊需求,而內建的 handler 類別無法滿足,則可以建立自己的日" +"誌目的地類別。" #: ../../howto/logging.rst:396 msgid "" @@ -533,10 +627,15 @@ msgid "" "displayed message before delegating to the root logger to do the actual " "message output." msgstr "" +"預設情況下,對於所有的日誌訊息都沒有設定目的地。你可以使用教程範例中的 :func:" +"`basicConfig` 指定目的地(例如控制台或檔案)。如果你呼叫 :func:`debug`、:" +"func:`info`、:func:`warning`、:func:`error` 和 :func:`critical` 函式,它們會" +"檢查是否設定目的地,如果沒有,它們會設置目的地為控制台(``sys.stderr``)以及" +"顯示信息的默認格式,然後委派給根記錄器來進行實際的訊息輸出。" #: ../../howto/logging.rst:404 msgid "The default format set by :func:`basicConfig` for messages is:" -msgstr "" +msgstr ":func:`basicConfig` 預設設定的訊息格式為:" #: ../../howto/logging.rst:410 msgid "" @@ -544,20 +643,22 @@ msgid "" "the *format* keyword argument. For all options regarding how a format string " "is constructed, see :ref:`formatter-objects`." msgstr "" +"你可以透過傳遞格式字符串到 :func:`basicConfig` 的 *format* 關鍵字引數來進行更" +"改。有關格式字符串構建的所有選項,請參閱 :ref:`formatter-objects`。" #: ../../howto/logging.rst:415 msgid "Logging Flow" -msgstr "" +msgstr "記錄流程" #: ../../howto/logging.rst:417 msgid "" "The flow of log event information in loggers and handlers is illustrated in " "the following diagram." -msgstr "" +msgstr "下面的圖表說明了記錄器(logger)和處理器(handler)中事件資訊的流動。" #: ../../howto/logging.rst:424 msgid "Loggers" -msgstr "" +msgstr "記錄器(Loggers)" #: ../../howto/logging.rst:426 msgid "" @@ -568,16 +669,20 @@ msgid "" "Third, logger objects pass along relevant log messages to all interested log " "handlers." msgstr "" +":class:`Logger` (紀錄器)物件有三個工作。首先,它們向應用程式程式碼公開多個" +"方法,讓應用程式可以在運行時記錄訊息。其次,紀錄器物件基於嚴重性(預設過濾方" +"式)或過濾器物件來決定要處理哪些日誌訊息。第三,紀錄器物件將相關的日誌訊息傳" +"遞給所有感興趣的日誌處理程序。" #: ../../howto/logging.rst:432 msgid "" "The most widely used methods on logger objects fall into two categories: " "configuration and message sending." -msgstr "" +msgstr "記錄器物件上最常使用的方法可分為兩類:配置和傳送訊息。" #: ../../howto/logging.rst:435 msgid "These are the most common configuration methods:" -msgstr "" +msgstr "以下是最常見的設定方法:" #: ../../howto/logging.rst:437 msgid "" @@ -587,6 +692,10 @@ msgid "" "INFO, the logger will handle only INFO, WARNING, ERROR, and CRITICAL " "messages and will ignore DEBUG messages." msgstr "" +":meth:`Logger.setLevel` 指定了一個 logger 所處理的最低嚴重性信息,其中 debug " +"是最低內建的嚴重性等級,而 critical 是最高內建的嚴重性等級。例如,如果嚴重性" +"等級是 INFO,logger 只處理 INFO、WARNING、ERROR 和 CRITICAL 訊息,而會忽略 " +"DEBUG 訊息。" #: ../../howto/logging.rst:443 msgid "" @@ -594,6 +703,9 @@ msgid "" "handler objects from the logger object. Handlers are covered in more detail " "in :ref:`handler-basic`." msgstr "" +":meth:`Logger.addHandler` 和 :meth:`Logger.removeHandler` 可以新增或移除處理" +"器物件到當前的記錄器物件(logger object)。有關處理器的詳細說明,請參閱 :ref:" +"`handler-basic`。" #: ../../howto/logging.rst:447 msgid "" @@ -601,17 +713,19 @@ msgid "" "filter objects from the logger object. Filters are covered in more detail " "in :ref:`filter`." msgstr "" +":meth:`Logger.addFilter` 和 :meth:`Logger.removeFilter` 分別是在記錄器對象中" +"新增和移除過濾器物件。更多關於過濾器的細節可以參閱 :ref:`filter`。" #: ../../howto/logging.rst:451 msgid "" "You don't need to always call these methods on every logger you create. See " "the last two paragraphs in this section." -msgstr "" +msgstr "你並不需要在每個你建立的記錄器上都呼叫這些方法,請參考此節的最後兩段。" #: ../../howto/logging.rst:454 msgid "" "With the logger object configured, the following methods create log messages:" -msgstr "" +msgstr "有了已配置的記錄器物件之後,下列這些方法可以產生日誌訊息:" #: ../../howto/logging.rst:456 msgid "" @@ -625,6 +739,12 @@ msgid "" "about a keyword of ``exc_info`` and use it to determine whether to log " "exception information." msgstr "" +":meth:`Logger.debug`、:meth:`Logger.info`、:meth:`Logger.warning`、:meth:" +"`Logger.error` 和 :meth:`Logger.critical` 建立一個包含訊息和相應名稱的日誌紀" +"錄。訊息實際上是格式化字串,可以包含 ``%s`` 、 ``%d`` 、 ``%f`` 等的標準字符" +"串替換語法。其餘引數都是對應於訊息中的替換欄位的物件列表。對於 ``**kwargs``," +"日誌記錄函式只關心參數中是否有 ``exc_info`` 的關鍵字,並使用它來確定是否記錄" +"異常訊息。" #: ../../howto/logging.rst:466 msgid "" @@ -632,6 +752,9 @@ msgid "" "error`. The difference is that :meth:`Logger.exception` dumps a stack trace " "along with it. Call this method only from an exception handler." msgstr "" +":meth:`Logger.exception` 這個方法建立的日誌訊息與 :meth:`Logger.error` 相近。" +"差別在於 :meth:`Logger.exception` 會附上一個程式執行時的堆疊(traceback)。請只" +"將此方法用於例外處理(exception handlers)。" #: ../../howto/logging.rst:470 msgid "" @@ -640,6 +763,8 @@ msgid "" "convenience methods listed above, but this is how to log at custom log " "levels." msgstr "" +":meth:`Logger.log` 需要額外的日誌級別當作明確引數。使用這種方式記錄日誌訊息會" +"比上述方法冗長一些,不過這是使用自定義日誌級別時如何記錄日誌的方式。" #: ../../howto/logging.rst:474 msgid "" @@ -652,6 +777,12 @@ msgid "" "loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all " "descendants of ``foo``." msgstr "" +":func:`getLogger` 會回傳一個指定名稱的日誌物件實例的參照,如果沒有指定名稱," +"則使用 ``root`` 當作其名稱。這些名稱是由點號分隔的層次結構。使用相同名字多次" +"呼叫 :func:`getLogger` 將回傳對相同日誌物件的參考。在層級 list(串列)中層級" +"更低的日誌物件是高級別日誌物件的子物件。例如,對於名稱為 ``foo`` 的日誌物件," +"名稱為 ``foo.bar``、``foo.bar.baz`` 和 ``foo.bam`` 的日誌物件都只是 ``foo`` " +"的子物件。" #: ../../howto/logging.rst:482 msgid "" @@ -664,6 +795,11 @@ msgid "" "the logger is used to determine whether the event is passed to the logger's " "handlers." msgstr "" +"記錄器有一個 *有效級別* 的概念。如果沒有在記錄器上明確設置級別,則使用其父級" +"別作為其有效級別。如果父級沒有設置明確的級別,則檢查 *它* 的父級別,依此類推 " +"- 搜索所有祖先(ancestors),直到找到明確設置的級別。根記錄器始終設置了明確的" +"級別(默認為 ``WARNING`` )。在決定是否處理事件時,記錄器的有效級別用於確定事" +"件是否傳遞給記錄器的處理器。" #: ../../howto/logging.rst:490 msgid "" @@ -674,10 +810,14 @@ msgid "" "needed. (You can, however, turn off propagation by setting the *propagate* " "attribute of a logger to ``False``.)" msgstr "" +"子記錄器會將訊息在其祖先(ancestor)記錄器所關聯的處理程式傳播,因此並不需要" +"為應用程式使用的所有記錄器定義和配置處理器。因此只需要為最高級別的記錄器配置" +"處理器,然後根據需要建立子記錄器即可。(你可以透過將記事本的 *propagate* 屬性" +"設置為 ``False`` 來關閉傳播)" #: ../../howto/logging.rst:501 msgid "Handlers" -msgstr "" +msgstr "處理器" #: ../../howto/logging.rst:503 msgid "" @@ -691,6 +831,12 @@ msgid "" "individual handlers where each handler is responsible for sending messages " "of a specific severity to a specific location." msgstr "" +":class:`~logging.Handler` 物件負責將適當的日誌訊息分派到處理器指定的目的地" +"(根據日誌訊息的嚴重性)。:class:`Logger` (日誌物件)可以使用 :meth:" +"`~Logger.addHandler` 方法向自己添加零個或多個處理器物件。作為一個範例場景,一" +"個應用程式可能想要將所有日誌訊息發送到一個日誌檔案、將所有錯誤或更高級別的日" +"誌訊息發送到 stdout、並將所有嚴重的日誌訊息發送到一個電子郵件地址。這種場景需" +"要三個獨立的處理器,其中每個處理器負責將特定嚴重性的訊息發送到特定位置。" #: ../../howto/logging.rst:513 msgid "" @@ -698,6 +844,8 @@ msgid "" "handlers`); the tutorials use mainly :class:`StreamHandler` and :class:" "`FileHandler` in its examples." msgstr "" +"標準函式庫中包含了相當多的處理器型別(請見 :ref:`useful-handlers`),本教學範" +"例主要會使用 :class:`StreamHandler` 與 :class:`FileHandler`。" #: ../../howto/logging.rst:517 msgid "" @@ -706,6 +854,8 @@ msgid "" "application developers who are using the built-in handler objects (that is, " "not creating custom handlers) are the following configuration methods:" msgstr "" +"對於應用程式開發人員而言,與處理器相關的方法非常少。當使用內置的處理程序物件 " +"(即未建立自定義處理程序) 時,似乎只有以下設置方法對應用程式開發人員有關:" #: ../../howto/logging.rst:522 msgid "" @@ -716,18 +866,25 @@ msgid "" "The level set in each handler determines which messages that handler will " "send on." msgstr "" +":meth:`~Handler.setLevel` 方法在日誌物件中同樣存在,它指定了將會被傳遞至目的" +"地的最低記錄等級。爲什麼有兩個 :func:`setLevel` 方法呢?記錄器中設置的等級決" +"定哪些消息程度會透過該日誌物件傳遞到其處理程序。每個處理器中設置的日誌等級則" +"決定該處理器需要發送哪些訊息。" #: ../../howto/logging.rst:528 msgid "" ":meth:`~Handler.setFormatter` selects a Formatter object for this handler to " "use." msgstr "" +":meth:`~Handler.setFormatter` 方法可為此處理器選擇一個格式化器物件使用。" #: ../../howto/logging.rst:531 msgid "" ":meth:`~Handler.addFilter` and :meth:`~Handler.removeFilter` respectively " "configure and deconfigure filter objects on handlers." msgstr "" +":meth:`~Handler.addFilter` 方法和 :meth:`~Handler.removeFilter` 方法可以分別" +"在處理器中設定或移除過濾物件。" #: ../../howto/logging.rst:534 msgid "" @@ -736,10 +893,13 @@ msgid "" "the interface that all handlers should have and establishes some default " "behavior that child classes can use (or override)." msgstr "" +"應用程式程式碼不應直接實例化和使用 :class:`Handler` 的實例。相反的,:class:" +"`Handler` 類別是一個基礎類別,它定義了所有處理器應具備的介面(interface),並" +"建立了某些子類別可以使用(或可以覆寫)的預設行為。" #: ../../howto/logging.rst:541 msgid "Formatters" -msgstr "" +msgstr "格式化器 (Formatters)" #: ../../howto/logging.rst:543 msgid "" @@ -750,12 +910,18 @@ msgid "" "takes three optional arguments -- a message format string, a date format " "string and a style indicator." msgstr "" +"格式化器對象(Formatter objects)設置記錄訊息的最終順序、結構和內容。和基礎" +"的 :class:`logging.Handler` 類別不同,應用程式程式碼可以實例化格式化器類別," +"不過如果應用程式需要特殊行為,則可能需要子類別繼承格式化器。構造函式" +"(condtructor)有三個可選引數 -- 訊息格式字串、日期格式字串和樣式指示器。" #: ../../howto/logging.rst:552 msgid "" "If there is no message format string, the default is to use the raw " "message. If there is no date format string, the default date format is:" msgstr "" +"如果沒有訊息格式字串,預設使用原始訊息。如果沒有日期格式字串,預設的日期格式" +"為:" #: ../../howto/logging.rst:559 msgid "" @@ -763,6 +929,8 @@ msgid "" "``'{'``, or ``'$'``. If one of these is not specified, then ``'%'`` will be " "used." msgstr "" +"在結尾處附加了毫秒,``style`` 是 ``'%'``,``'{'`` 和 ``'$'`` 的其中一個。如果" +"未指定其中任一個,則使用 ``'%'``。" #: ../../howto/logging.rst:562 msgid "" @@ -773,6 +941,11 @@ msgid "" "arguments), while if the style is ``'$'`` then the message format string " "should conform to what is expected by :meth:`string.Template.substitute`." msgstr "" +"如果 ``style`` 是 ``'%'``,則訊息格式字串使用 ``%()s`` 的樣式" +"字串替換;可能的鍵名已在 :ref:`logrecord-attributes` 中文件化。如果樣式是 " +"``'{'``,則假設訊息格式字串與 :meth:`str.format` 相容(使用關鍵字引數),而如" +"果樣式是 ``'$'``,則訊息格式字串應符合 :meth:`string.Template.substitute` 預" +"期的格式。" #: ../../howto/logging.rst:569 msgid "Added the ``style`` parameter." @@ -784,6 +957,8 @@ msgid "" "format, the severity of the message, and the contents of the message, in " "that order::" msgstr "" +"下列訊息格式字串將以人類可讀的方式記錄訊息時間、訊息嚴重性和訊息內容,按照這" +"個順序: ::" #: ../../howto/logging.rst:578 msgid "" @@ -795,32 +970,40 @@ msgid "" "want all logging times to be shown in GMT, set the ``converter`` attribute " "in the Formatter class (to ``time.gmtime`` for GMT display)." msgstr "" +"格式化器使用可自訂的函式,將紀錄的建立時間轉換為元組。預設使用 :func:`time." +"localtime`;如果要針對特定格式化器實例更改此設定,則將該實例的 ``converter`` " +"屬性設置為一個與 :func:`time.localtime` 或 :func:`time.gmtime` 等具有相同簽名" +"的函式。如果要為所有格式化器更改此設定,像是要在所有記錄時間顯示為 GMT 時間," +"可以在格式化器類別中設置 ``converter`` 屬性(以 ``time.gmtime`` 為 GMT 顯" +"示)。" #: ../../howto/logging.rst:588 msgid "Configuring Logging" -msgstr "" +msgstr "設定日誌(Logging)" #: ../../howto/logging.rst:592 msgid "Programmers can configure logging in three ways:" -msgstr "" +msgstr "程序員有三種設定日誌(Logging)的方式:" #: ../../howto/logging.rst:594 msgid "" "Creating loggers, handlers, and formatters explicitly using Python code that " "calls the configuration methods listed above." msgstr "" +"以 Python 程式碼方式呼叫上述設定方法來明確的生成紀錄器 (loggers)、處理器 " +"(handlers),以及格式器 (formatters)。" #: ../../howto/logging.rst:596 msgid "" "Creating a logging config file and reading it using the :func:`fileConfig` " "function." -msgstr "" +msgstr "使用 :func:`fileConfig` 函式來生成一個日誌設定檔並讀取它。" #: ../../howto/logging.rst:598 msgid "" "Creating a dictionary of configuration information and passing it to the :" "func:`dictConfig` function." -msgstr "" +msgstr "建立一個包含設定訊息的字典,並將其傳送給 :func:`dictConfig` 函式。" #: ../../howto/logging.rst:601 msgid "" @@ -828,11 +1011,13 @@ msgid "" "config-api`. The following example configures a very simple logger, a " "console handler, and a simple formatter using Python code::" msgstr "" +"請參閱 :ref:`logging-config-api` 來了解關於最後兩個選項的參考文件。以下示範設" +"定一個非常簡單的紀錄器、控制台處理器和一個使用Python程式碼的簡單格式化器: ::" #: ../../howto/logging.rst:631 msgid "" "Running this module from the command line produces the following output:" -msgstr "" +msgstr "在命令行執行這個模組將會產生下列輸出:" #: ../../howto/logging.rst:642 msgid "" @@ -840,15 +1025,17 @@ msgid "" "identical to those in the example listed above, with the only difference " "being the names of the objects::" msgstr "" +"以下Python模組建立了一個幾乎與上面列表中相同的記錄器(logger)、處理器" +"(handler),和格式化器(formatter),唯一不同之處在於對象名稱的改變: ::" #: ../../howto/logging.rst:661 msgid "Here is the logging.conf file:" -msgstr "" +msgstr "這是 logging.conf 檔案:" #: ../../howto/logging.rst:693 msgid "" "The output is nearly identical to that of the non-config-file-based example:" -msgstr "" +msgstr "輸出結果和非設定文件範例的幾乎完全相同:" #: ../../howto/logging.rst:704 msgid "" @@ -856,6 +1043,8 @@ msgid "" "Python code approach, mainly separation of configuration and code and the " "ability of noncoders to easily modify the logging properties." msgstr "" +"可以看出使用設定檔的方法相較於使用 Python 程式碼具有一些優點。主要包括分離設" +"定和程式碼、以及使得非開發人員能夠簡單地修改日誌屬性。" #: ../../howto/logging.rst:708 msgid "" @@ -867,6 +1056,11 @@ msgid "" "configuration. Please refer to the reference documentation for more " "information, and specify ``False`` for this parameter if you wish." msgstr "" +":func:`fileConfig` 函式帶有一個預設參數:``disable_existing_loggers``,其因向" +"後相容的考量而默認值為 ``True``。這可能不符合你的要求,除非它們或祖先" +"(ancestor)明確包含於設定當中,不然會因為它導致在呼叫 :func:`fileConfig` 前" +"已存在的非根記錄器(loggers) 被停用。如需更多資訊請查看參考文件並在本參數中指" +"定值 ``False``。" #: ../../howto/logging.rst:716 msgid "" @@ -876,6 +1070,10 @@ msgid "" "the logger-disabling behaviour described above, which may not be what you " "want - in which case, provide the key explicitly with a value of ``False``." msgstr "" +"傳遞給 :func:`dictConfig` 的字典也可以使用 ``disable_existing_loggers`` 作為" +"鍵的布林值,如果該項在字典中沒有明確指定,則預設會解釋為 ``True``。這導致了上" +"述關閉 Logger 的行為,可能不是你想要的行為;若是如此,請提供顯式的鍵並以值 " +"\"False\" 提供。" #: ../../howto/logging.rst:726 msgid "" @@ -887,6 +1085,11 @@ msgid "" "module ``mymodule``, where ``mypackage`` is available on the Python import " "path)." msgstr "" +"注意,設定檔中引用的類別名稱必須相對於日誌模組,或是可以透過正常匯入方式解析" +"的絕對值。因此你可以使用 :class:`~logging.handlers.WatchedFileHandler` (相對" +"於日誌模組),或者 ``mypackage.mymodule.MyHandler``\\ (表示在套件 " +"``mypackage`` 的模組 ``mymodule`` 中定義一個類別,並確認該套件已在 Python 匯" +"入路徑上)" #: ../../howto/logging.rst:734 msgid "" @@ -902,29 +1105,39 @@ msgid "" "can construct the dictionary in Python code, receive it in pickled form over " "a socket, or use whatever approach makes sense for your application." msgstr "" +"在 Python 3.2 中,引入了一種使用字典來保存設定資訊的新方法。這提供了上述配置" +"文件方法所提供功能的超集,是推薦用於新應用程式和部署的配置方法。因為 Python " +"字典被用來保存配置資訊,你可以使用不同的方式來填充字典,所以你有更多的選項來" +"進行配置。例如,你可以使用 JSON 格式的配置文件填充配置字典,或者如果你能夠存" +"取到 YAML 處理功能,則可以使用 YAML 格式的文件來填充配置字典。或者當然你可以" +"在 Python 程式碼中建立字典,或透過 socket 以序列化形式接收它,或使用任何對於" +"應用程式合理的方法。" #: ../../howto/logging.rst:746 msgid "" "Here's an example of the same configuration as above, in YAML format for the " "new dictionary-based approach:" -msgstr "" +msgstr "以下是與上述相同的設定範例,採用基於新字典的 YAML 格式:" #: ../../howto/logging.rst:770 msgid "" "For more information about logging using a dictionary, see :ref:`logging-" "config-api`." -msgstr "" +msgstr "欲了解如何使用字典進行紀錄,請參考 :ref:`logging-config-api`。" #: ../../howto/logging.rst:774 msgid "What happens if no configuration is provided" -msgstr "" +msgstr "如果未提供設定,會發生什麼" #: ../../howto/logging.rst:776 +#, fuzzy msgid "" "If no logging configuration is provided, it is possible to have a situation " "where a logging event needs to be output, but no handlers can be found to " "output the event." msgstr "" +"如果沒有提供日誌記錄配置,則可能會出現需要輸出日誌記錄事件,但找不到輸出該事" +"件的處理程序的情況。" #: ../../howto/logging.rst:780 msgid "" @@ -937,10 +1150,16 @@ msgid "" "handler's level is set to ``WARNING``, so all events at this and greater " "severities will be output." msgstr "" +"本事件使用 'handler of last resort' 輸出,該處理程序存儲在 :data:" +"`lastResort` 中。這個內部處理程序不與任何日誌記錄器相關聯,作用類似於 :class:" +"`~logging.StreamHandler`,將事件描述信息寫入當前值 ``sys.stderr``\\ (因此會" +"尊重任何已生效的重定向)。對消息不進行任何格式化處理,僅打印出基本的事件描述" +"信息。處理程序的級別設置為 ``WARNING``,因此將輸出該級別及更高級別的所有事" +"件。" #: ../../howto/logging.rst:791 msgid "For versions of Python prior to 3.2, the behaviour is as follows:" -msgstr "" +msgstr "在 Python 3.2 版本之前的版本,其行為如下:" #: ../../howto/logging.rst:793 msgid "" @@ -958,10 +1177,26 @@ msgstr "" msgid "" "To obtain the pre-3.2 behaviour, :data:`lastResort` can be set to ``None``." msgstr "" +"如果 :data:`raiseExceptions` 為 ``False``\\ (正式產品模式),則該事件將會被" +"靜默刪除。" + +#: ../../howto/logging.rst:796 +msgid "" +"If :data:`raiseExceptions` is ``True`` (development mode), a message 'No " +"handlers could be found for logger X.Y.Z' is printed once." +msgstr "" +"如果 :data:`raiseExceptions` 為 ``True``\\ (開發模式),則會列印訊息 'No " +"handlers could be found for logger X.Y.Z'(無法找到日誌記錄器 X.Y.Z 的處理程" +"序)。" + +#: ../../howto/logging.rst:799 +msgid "" +"To obtain the pre-3.2 behaviour, :data:`lastResort` can be set to ``None``." +msgstr "要獲得 3.2 之前的行為,可以將 :data:`lastResort` 設定為 ``None``。" #: ../../howto/logging.rst:805 msgid "Configuring Logging for a Library" -msgstr "" +msgstr "為函式庫設定日誌" #: ../../howto/logging.rst:807 msgid "" @@ -973,6 +1208,10 @@ msgid "" "of severity ``WARNING`` and greater will be printed to ``sys.stderr``. This " "is regarded as the best default behaviour." msgstr "" +"開發使用 logging 的函式庫時,應該注意函式庫如何使用 logging ,例如日誌記錄器" +"的名稱。也需要考慮到 logging 設定的配置方式。如果應用程式未使用日誌記錄且函式" +"庫程式碼有做出日誌記錄呼叫(如前一節所述),則會將所有大於或等於 ``WARNING`` " +"嚴重性事件列印至 ``sys.stderr`` 中。這被認為是最佳預設行為。" #: ../../howto/logging.rst:815 msgid "" @@ -985,6 +1224,11 @@ msgid "" "suitably configured then logging calls made in library code will send output " "to those handlers, as normal." msgstr "" +"如果因為某些原因,你 *不希望* 在缺乏任何記錄配置的情況下打印這些訊息,你可以" +"將一個什麼也不做的處理器附加到你函式庫的頂層記錄器。這樣可以避免打印訊息,因" +"為函式庫的事件都會找到對應的處理器:它只是不會產生任何輸出。如果函式庫使用者" +"為應用使用配置日誌,那麼該配置可能會添加一些處理器,如果級別被適當配置,那麼" +"在函式庫程式碼中進行的 logging 呼叫將像平常一樣將輸出發送到這些處理器中。" #: ../../howto/logging.rst:824 msgid "" @@ -996,6 +1240,11 @@ msgid "" "library *foo* is done using loggers with names matching 'foo.x', 'foo.x.y', " "etc. then the code::" msgstr "" +"logging 套件中包含了一個什麼也不做的處理器 (do-nothing handler): :class:" +"`~logging.NullHandler`\\ (自 Python 3.1 起)。你可以將此處理器的實例新增至被" +"函式庫使用的 logging 命名空間的頂層記錄器中,( *如果* 你希望在缺少日誌配置的" +"情況下防止函式庫產生的日誌事件被輸出至 ``sys.stderr``\\ )。如果函式庫 *foo* " +"使用的所有記錄器都符合名為 'foo.x','foo.x.y' 等的規則,則程式碼: ::" #: ../../howto/logging.rst:835 msgid "" @@ -1003,6 +1252,8 @@ msgid "" "libraries, then the logger name specified can be 'orgname.foo' rather than " "just 'foo'." msgstr "" +"應該要有預期的結果。如果一個組織生產了多個函式庫,則指定的記錄器名稱會是 " +"'orgname.foo',而不只是 'foo'。" #: ../../howto/logging.rst:839 msgid "" @@ -1013,6 +1264,9 @@ msgid "" "application developer to configure the logging verbosity or handlers of your " "library as they wish." msgstr "" +"強烈建議你 *不要記錄到根記錄器*。而是使用一個具有獨特並易於識別的名稱的記錄" +"器,例如你函式庫的頂層套件或模組的 ``__name__``。如果記錄到根日誌,應用程序開" +"發者將很難或無法在你的函式庫設置他們想要的logging詳細程度和處理器。" #: ../../howto/logging.rst:846 msgid "" @@ -1024,10 +1278,14 @@ msgid "" "handlers 'under the hood', you might well interfere with their ability to " "carry out unit tests and deliver logs which suit their requirements." msgstr "" +"非常建議你 *不要在你的處理器中添加除* :class:`~logging.NullHandler` *之外的記" +"錄器到你的函式庫*。這是因為處理器的配置取決於使用你函式庫的應用程式開發人員," +"他們會知道目標受眾以及適合使用那些處理器: 如果在 '幕後' 添加處理器,你可能會" +"干擾他們進行單元測試的能力,並且妨礙他們生成符合自己要求的日誌。" #: ../../howto/logging.rst:857 msgid "Logging Levels" -msgstr "" +msgstr "日誌層級" #: ../../howto/logging.rst:859 msgid "" @@ -1037,10 +1295,13 @@ msgid "" "define a level with the same numeric value, it overwrites the predefined " "value; the predefined name is lost." msgstr "" +"日誌等級的數值定義如下表所示。如果你想要定義自己的等級,並且需要使它們相對於" +"預定義的等級具有特定的值,這些內容會對你非常有幫助。如果你定義一個與預設數值" +"相同的等級,它會覆寫原先對應的預設值;原本預設的名稱也會消失。" #: ../../howto/logging.rst:866 msgid "Numeric value" -msgstr "" +msgstr "數值" #: ../../howto/logging.rst:868 msgid "50" @@ -1079,6 +1340,10 @@ msgid "" "the method call's, no logging message is actually generated. This is the " "basic mechanism controlling the verbosity of logging output." msgstr "" +"級別 (Levels) 也可以與記錄器相關聯,被開發人員設置或透過加載保存的日誌配置。" +"當在記錄器上調用logging方法時,該記錄器將其自身級別和與方法調用相關聯的級別進" +"行比較。如果記錄器的級別高於方法調用的級別,則實際上不會生成任何記錄消息。這" +"是控制日誌輸出冗長程度的基本機制。" #: ../../howto/logging.rst:888 msgid "" @@ -1086,6 +1351,8 @@ msgid "" "class. When a logger decides to actually log an event, a :class:`~logging." "LogRecord` instance is created from the logging message." msgstr "" +"記錄訊息被編碼成 :class:`~logging.LogRecord` 類別的實例。當記錄器決定要真正地" +"記錄事件時,會從日誌訊息建立 :class:`~logging.LogRecord` 的實例。" #: ../../howto/logging.rst:892 msgid "" @@ -1103,6 +1370,14 @@ msgid "" "message (unless the *propagate* flag for a logger is set to a false value, " "at which point the passing to ancestor handlers stops)." msgstr "" +"記錄訊息透過 :dfn:`handlers`\\ (它們是 :class:`Handler` 類別的子類別實例)的" +"分派機制進行處理。Handlers 負責確保一個已記錄的訊息(以 :class:`LogRecord` 的" +"形式)最終會出現在特定位置(或多個位置),該訊息對於目標受眾(如終端用戶、支" +"援人員、系統管理員、開發人員)非常有用。Handlers 負責處理特定目的地的 :class:" +"`LogRecord` 實例。每個記錄器可以有零個、一個或多個處理器與之關聯(透過 :" +"class:`Logger` 的 :meth:`~Logger.addHandler` 方法)。除了與記錄器直接關聯的任" +"何處理器,*調用所有祖先的處理器* 都會被調用以分派此訊息(除非某個處理器的 " +"*propagate* 旗標設置為 False,在這種情況下,傳遞到祖先的處理器就會停止)." #: ../../howto/logging.rst:906 msgid "" @@ -1113,10 +1388,14 @@ msgid "" "defined subclasses of :class:`Handler` will need to override this :meth:" "`~Handler.emit`." msgstr "" +"與記錄器一樣,處理器也可以有與其相關的層級。處理器的層級起到過濾器的作用,就" +"像記錄器的層級一樣。如果一個處理器決定實際分發事件,則使用 :meth:`~Handler." +"emit` 方法將訊息發送至目的地。大部分自定義的 :class:`Handler` 子類別都需要覆" +"蓋此 :meth:`~Handler.emit`。" #: ../../howto/logging.rst:915 msgid "Custom Levels" -msgstr "" +msgstr "自訂等級" #: ../../howto/logging.rst:917 msgid "" @@ -1130,26 +1409,32 @@ msgid "" "difficult for the using developer to control and/or interpret, because a " "given numeric value might mean different things for different libraries." msgstr "" +"定義自己的層級是可行的,但通常不是必要的,因為現有層級是根據實際經驗選擇的。" +"然而,如果你確實需要自定義層級,則在這樣做時應該非常小心,如果你正在開發函式" +"庫,則*自定義層級可能是一個非常糟糕的想法*。這是因為如果多個函式庫作者都定義" +"自己的自定義層級,那麼在一起使用這些函式庫時,日誌輸出可能會對使用開發人員的" +"控制或解釋造成困難,因為給定的數值可能對於不同的函式庫而言意味著不同的事情。" #: ../../howto/logging.rst:930 msgid "Useful Handlers" -msgstr "" +msgstr "有用的處理器" #: ../../howto/logging.rst:932 msgid "" "In addition to the base :class:`Handler` class, many useful subclasses are " "provided:" -msgstr "" +msgstr "除了基礎的 :class:`Handler` 類別,還提供了許多有用的子類別:" #: ../../howto/logging.rst:935 msgid "" ":class:`StreamHandler` instances send messages to streams (file-like " "objects)." msgstr "" +":class:`StreamHandler` 實例會將訊息傳送到資料流(與檔案相似的物件)中。" #: ../../howto/logging.rst:938 msgid ":class:`FileHandler` instances send messages to disk files." -msgstr "" +msgstr ":class:`FileHandler` 實例會將訊息傳送至磁碟檔案。" #: ../../howto/logging.rst:940 msgid "" @@ -1158,60 +1443,79 @@ msgid "" "directly. Instead, use :class:`~handlers.RotatingFileHandler` or :class:" "`~handlers.TimedRotatingFileHandler`." msgstr "" +":class:`~handlers.BaseRotatingHandler` 是處理紀錄檔案輪替的基礎類別。不建議直" +"接實例化,而是使用 :class:`~handlers.RotatingFileHandler` 或是 :class:" +"`~handlers.TimedRotatingFileHandler`。" #: ../../howto/logging.rst:945 msgid "" ":class:`~handlers.RotatingFileHandler` instances send messages to disk " "files, with support for maximum log file sizes and log file rotation." msgstr "" +":class:`~handlers.RotatingFileHandler` 的實例可以將訊息記錄到磁碟檔案中,支援" +"最大日誌檔大小和日誌檔輪替。" #: ../../howto/logging.rst:948 msgid "" ":class:`~handlers.TimedRotatingFileHandler` instances send messages to disk " "files, rotating the log file at certain timed intervals." msgstr "" +":class:`~handlers.TimedRotatingFileHandler` 實例會在特定時間間隔輪替日誌文件" +"並將訊息寫到磁碟檔案中。" #: ../../howto/logging.rst:951 msgid "" ":class:`~handlers.SocketHandler` instances send messages to TCP/IP sockets. " "Since 3.4, Unix domain sockets are also supported." msgstr "" +":class:`~handlers.SocketHandler` 實例會將訊息發送到 TCP/IP sockets 上。從 " +"3.4 開始,Unix domain sockets 也受支援。" #: ../../howto/logging.rst:954 msgid "" ":class:`~handlers.DatagramHandler` instances send messages to UDP sockets. " "Since 3.4, Unix domain sockets are also supported." msgstr "" +":class:`~handlers.DatagramHandler` 實例會將訊息發送到 UDP sockets。自 3.4 " +"起,也支援 Unix domain sockets。" #: ../../howto/logging.rst:957 msgid "" ":class:`~handlers.SMTPHandler` instances send messages to a designated email " "address." -msgstr "" +msgstr ":class:`~handlers.SMTPHandler` 實例會發送訊息到指定的電子郵件地址。" #: ../../howto/logging.rst:960 msgid "" ":class:`~handlers.SysLogHandler` instances send messages to a Unix syslog " "daemon, possibly on a remote machine." msgstr "" +":class:`~handlers.SysLogHandler` 實例可以將訊息發送至 Unix syslog daemon,其" +"中可能包含遠端機器的資訊。" #: ../../howto/logging.rst:963 msgid "" ":class:`~handlers.NTEventLogHandler` instances send messages to a Windows " "NT/2000/XP event log." msgstr "" +":class:`~handlers.NTEventLogHandler` 實例將訊息傳送至 Windows NT/2000/XP 事件" +"記錄。" #: ../../howto/logging.rst:966 msgid "" ":class:`~handlers.MemoryHandler` instances send messages to a buffer in " "memory, which is flushed whenever specific criteria are met." msgstr "" +":class:`~handlers.MemoryHandler` 實例將訊息儲存到記憶體緩衝區,在符合特定條件" +"時進行刷新。" #: ../../howto/logging.rst:969 msgid "" ":class:`~handlers.HTTPHandler` instances send messages to an HTTP server " "using either ``GET`` or ``POST`` semantics." msgstr "" +":class:`~handlers.HTTPHandler` 實例使用 ``GET`` 或 ``POST`` 來語意地向 HTTP " +"伺服器發送訊息。" #: ../../howto/logging.rst:972 msgid "" @@ -1220,12 +1524,17 @@ msgid "" "name. This handler is only useful on Unix-like systems; Windows does not " "support the underlying mechanism used." msgstr "" +":class:`~handlers.WatchedFileHandler` 實例會監看其所記錄的檔案。若該檔案變" +"更,則將關閉並使用新的文件名重新開啟。此處理程序僅在類Unix 系統上才有用,因" +"為 Windows 不支援所使用的底層機制。" #: ../../howto/logging.rst:977 msgid "" ":class:`~handlers.QueueHandler` instances send messages to a queue, such as " "those implemented in the :mod:`queue` or :mod:`multiprocessing` modules." msgstr "" +":class:`~handlers.QueueHandler` 實例將訊息發送到佇列中,例如在 :mod:`queue` " +"或 :mod:`multiprocessing` 模組中實作的那些佇列。" #: ../../howto/logging.rst:980 msgid "" @@ -1235,14 +1544,18 @@ msgid "" "the library user has not configured logging. See :ref:`library-config` for " "more information." msgstr "" +":class:`NullHandler` (空處理器) 的實例對錯誤訊息沒有作用。這些被程式庫開發者" +"使用,他們想要使用日誌紀錄(logging),但是希望避免當程式庫的使用者未配置日誌紀" +"錄時所顯示的 \"找不到與XXX相關聯之處理器No handlers could be found for " +"logger\" 訊息。參閱 :ref:`library-config` 以瞭解更多資訊。" #: ../../howto/logging.rst:986 msgid "The :class:`NullHandler` class." -msgstr "" +msgstr ":class:`NullHandler` 類別。" #: ../../howto/logging.rst:989 msgid "The :class:`~handlers.QueueHandler` class." -msgstr "" +msgstr ":class:`~handlers.QueueHandler` 類別。" #: ../../howto/logging.rst:992 msgid "" @@ -1251,6 +1564,9 @@ msgid "" "defined in a sub-module, :mod:`logging.handlers`. (There is also another sub-" "module, :mod:`logging.config`, for configuration functionality.)" msgstr "" +":class:`NullHandler`、:class:`StreamHandler` 和 :class:`FileHandler` 這三個類" +"別是在核心日誌套件中定義的。其他處理器則是在 :mod:`logging.handlers` 子模組中" +"定義(也有另一個名為 :mod:`logging.config` 的子模組,負責配置功能)。" #: ../../howto/logging.rst:997 msgid "" @@ -1258,6 +1574,8 @@ msgid "" "class:`Formatter` class. They are initialized with a format string suitable " "for use with the % operator and a dictionary." msgstr "" +"記錄訊息被格式化以便透過 :class:`Formatter` 類別的實例呈現。它們適用於 % 運算" +"子和字典的格式字串來進行初始化。" #: ../../howto/logging.rst:1001 msgid "" @@ -1266,6 +1584,8 @@ msgid "" "applied to each message in the batch), there is provision for header and " "trailer format strings." msgstr "" +"若要在一批訊息中套用格式,可使用 :class:`~handlers.BufferingFormatter` 實例。" +"除了針對批次中每個訊息所套用的格式字串外,還有提供標題和尾串格式字串。" #: ../../howto/logging.rst:1006 msgid "" @@ -1276,6 +1596,10 @@ msgid "" "consult all their filters for permission. If any filter returns a false " "value, the message is not processed further." msgstr "" +"當只使用日誌器或處理器的層級篩選時不足以滿足需求的時候,可以向 :class:" +"`Logger` 和 :class:`Handler` 實例中添加 :class:`Filter`\\ (透過其方法 :meth:" +"`~Handler.addFilter` )。在決定如何進一步處理訊息之前,日誌器和處理器會查詢所" +"有篩選程式碼是否允許。如果任何篩選程式回傳 false 值,則不再繼續處理此訊息。" #: ../../howto/logging.rst:1013 msgid "" @@ -1283,18 +1607,24 @@ msgid "" "name. If this feature is used, messages sent to the named logger and its " "children are allowed through the filter, and all others dropped." msgstr "" +":class:`Filter` 基本功能是可以按照特定記錄器名稱進行過濾。如果使用此功能,傳" +"送到已命名的記錄器及其子物件的訊息將透過篩檢程序,而所有其他訊息則會被放棄。" #: ../../howto/logging.rst:1021 msgid "Exceptions raised during logging" -msgstr "" +msgstr "記錄期間引發的異常" #: ../../howto/logging.rst:1023 +#, fuzzy msgid "" "The logging package is designed to swallow exceptions which occur while " "logging in production. This is so that errors which occur while handling " "logging events - such as logging misconfiguration, network or other similar " "errors - do not cause the application using logging to terminate prematurely." msgstr "" +"logging 套件的設計目標是在生產上運作時會忽略發生於記錄(log)中的例外狀況" +"(exception)。因此,在處理 logging 事件時,例如日誌配置不正確、網路或其他類似" +"型別的錯誤 - 不會導致使用 logging 的應用程式提前終止。" #: ../../howto/logging.rst:1028 msgid "" @@ -1303,14 +1633,21 @@ msgid "" "method of a :class:`Handler` subclass are passed to its :meth:`~Handler." "handleError` method." msgstr "" +":class:`SystemExit` 和 :class:`KeyboardInterrupt` 例外情況絕不會被忽略,其他" +"在 :class:`Handler` 的子類別中的 :meth:`~Handler.emit` 方法發生的例外狀況將會" +"傳遞到它的 :meth:`~Handler.handleError` 方法。" #: ../../howto/logging.rst:1033 +#, fuzzy msgid "" "The default implementation of :meth:`~Handler.handleError` in :class:" "`Handler` checks to see if a module-level variable, :data:`raiseExceptions`, " "is set. If set, a traceback is printed to :data:`sys.stderr`. If not set, " "the exception is swallowed." msgstr "" +":class:`Handler` 中的 :meth:`~Handler.handleError`預設實作會檢查模組層級變" +"數 :data:`raiseExceptions` 是否被設置。如有設置,臨界值將會輸出至寫入器 :" +"data:`sys.stderr` 而未被處理。" #: ../../howto/logging.rst:1039 msgid "" @@ -1319,10 +1656,13 @@ msgid "" "occur. It's advised that you set :data:`raiseExceptions` to ``False`` for " "production usage." msgstr "" +":data:`raiseExceptions` 的預設值為 ``True``。這是因為在開發時,通常希望能夠得" +"知任何例外情況的通知。建議你在產品使用時將 :data:`raiseExceptions` 設置為" +"「False」。" #: ../../howto/logging.rst:1049 msgid "Using arbitrary objects as messages" -msgstr "" +msgstr "將任意物件當作訊息" #: ../../howto/logging.rst:1051 msgid "" @@ -1335,10 +1675,15 @@ msgid "" "`~handlers.SocketHandler` emits an event by pickling it and sending it over " "the wire." msgstr "" +"在前幾個小節和範例中,都是使用字串做為處理事件的訊息(message)。但這不是唯一" +"的選擇,你可以傳遞任意物件當作訊息,當日誌系統需要將其轉換成字串表示式時會呼" +"叫它的 :meth:`~object.__str__` 方法。事實上,如果想要的話,甚至可以完全不計算" +"字串的表示 - 例如 :class:`~handlers.SocketHandler` 可以透過序列化(pickling)" +"事件並透過網路去發布它。" #: ../../howto/logging.rst:1062 msgid "Optimization" -msgstr "" +msgstr "最佳化" #: ../../howto/logging.rst:1064 msgid "" @@ -1350,12 +1695,18 @@ msgid "" "event would be created by the Logger for that level of call. You can write " "code like this::" msgstr "" +"訊息引數的格式化會被延遲到無法避免時才執行。即便如此,計算傳給日誌方法的引數" +"也是費時的,如果日誌會忽略事件並丟棄記錄,就應該要盡量避免計算它們。為了做出" +"決定,你可以呼叫 :meth:`~Logger.isEnabledFor` 方法(需要 level 引數)並回傳是" +"否記錄器會根據該呼叫等級建立事件。下面是範例程式碼: ::" #: ../../howto/logging.rst:1076 msgid "" "so that if the logger's threshold is set above ``DEBUG``, the calls to " "``expensive_func1`` and ``expensive_func2`` are never made." msgstr "" +"若記錄器的閾值設定高於 ``DEBUG``,則不會呼叫 ``expensive_func1`` 和 " +"``expensive_func2``。" #: ../../howto/logging.rst:1079 msgid "" @@ -1368,26 +1719,40 @@ msgid "" "need to be recomputed when the logging configuration changes dynamically " "while the application is running (which is not all that common)." msgstr "" +"在某些情況下,:meth:`~Logger.isEnabledFor` 本身可能比你想像的更昂貴(例如對於" +"僅在較高層級的記錄器中設置明確級別的深度記錄器中)。在這種情況下(或者如果你" +"想要避免在緊密循環中呼叫方法),你可以在局部變數或實例變數中快取對 :meth:" +"`~Logger.isEnabledFor` 的呼叫結果,並使用它來代替每次呼叫該方法。這樣的快取僅" +"需要在應用程式運行時動態更改日誌配置時重新計算(這並不是很常見)。" +<<<<<<< Updated upstream +#: ../../howto/logging.rst:1088 +||||||| Stash base +#: ../../howto/logging.rst:1087 +======= #: ../../howto/logging.rst:1088 +#, fuzzy +>>>>>>> Stashed changes msgid "" "There are other optimizations which can be made for specific applications " "which need more precise control over what logging information is collected. " "Here's a list of things you can do to avoid processing during logging which " "you don't need:" msgstr "" +"有些情況需要更精確地控制所收集的日誌資訊,可以進行其他特定應用程式的最佳化。" +"以下是一些可避免處理不必要記錄期間的操作列表:" #: ../../howto/logging.rst:1094 msgid "What you don't want to collect" -msgstr "" +msgstr "你不想收集的東西" #: ../../howto/logging.rst:1094 msgid "How to avoid collecting it" -msgstr "" +msgstr "如何避免收集它" #: ../../howto/logging.rst:1096 msgid "Information about where calls were made from." -msgstr "" +msgstr "有關從哪裡呼叫的資訊。" #: ../../howto/logging.rst:1096 msgid "" @@ -1395,40 +1760,45 @@ msgid "" "_getframe`, which may help to speed up your code in environments like PyPy " "(which can't speed up code that uses :func:`sys._getframe`)." msgstr "" +"將 ``logging._srcfile`` 設為 ``None``。可避免呼叫 :func:`sys._getframe`,這可" +"加快程式的速度,特別是像 PyPy 環境等無法使用 :func:`sys._getframe` 加速的情" +"況。" #: ../../howto/logging.rst:1102 msgid "Threading information." -msgstr "" +msgstr "執行緒資訊。" #: ../../howto/logging.rst:1102 msgid "Set ``logging.logThreads`` to ``False``." -msgstr "" +msgstr "將 ``logging.logThreads`` 設為 ``False``。" #: ../../howto/logging.rst:1104 msgid "Current process ID (:func:`os.getpid`)" -msgstr "" +msgstr "目前處理行程的 ID (:func:`os.getpid`\\ )" #: ../../howto/logging.rst:1104 msgid "Set ``logging.logProcesses`` to ``False``." -msgstr "" +msgstr "將 ``logging.logProcesses`` 設定為 ``False``。" #: ../../howto/logging.rst:1106 msgid "" "Current process name when using ``multiprocessing`` to manage multiple " "processes." -msgstr "" +msgstr "使用 ``multiprocessing`` 來管理多個程序時目前的程序名稱。" #: ../../howto/logging.rst:1106 msgid "Set ``logging.logMultiprocessing`` to ``False``." -msgstr "" +msgstr "將 ``logging.logMultiprocessing`` 設為 ``False``。" #: ../../howto/logging.rst:1109 +#, fuzzy msgid "Current :class:`asyncio.Task` name when using ``asyncio``." -msgstr "" +msgstr "使用“asyncio”時的當前 asyncio.Task 名稱。" #: ../../howto/logging.rst:1109 +#, fuzzy msgid "Set ``logging.logAsyncioTasks`` to ``False``." -msgstr "" +msgstr "將“logging.logAsyncioTasks”設定為“False”。" #: ../../howto/logging.rst:1113 msgid "" @@ -1436,10 +1806,12 @@ msgid "" "you don't import :mod:`logging.handlers` and :mod:`logging.config`, they " "won't take up any memory." msgstr "" +"請注意,核心日誌模組僅包含基本處理器(handler)。如果你不 import :mod:" +"`logging.handlers` 和 :mod:`logging.config` 的話,將不會佔用任何記憶體。" #: ../../howto/logging.rst:1120 msgid "Other resources" -msgstr "" +msgstr "其他資源" #: ../../howto/logging.rst:1125 msgid "Module :mod:`logging`" @@ -1447,7 +1819,7 @@ msgstr ":mod:`logging` 模組" #: ../../howto/logging.rst:1125 msgid "API reference for the logging module." -msgstr "" +msgstr "日誌模組的 API 參考文件。" #: ../../howto/logging.rst:1128 msgid "Module :mod:`logging.config`" @@ -1455,7 +1827,7 @@ msgstr ":mod:`logging.config` 模組" #: ../../howto/logging.rst:1128 msgid "Configuration API for the logging module." -msgstr "" +msgstr "日誌模組的設定 API。" #: ../../howto/logging.rst:1131 msgid "Module :mod:`logging.handlers`" @@ -1463,8 +1835,8 @@ msgstr ":mod:`logging.handlers` 模組" #: ../../howto/logging.rst:1131 msgid "Useful handlers included with the logging module." -msgstr "" +msgstr "日誌模組內含有許多實用的處理器。" #: ../../howto/logging.rst:1133 msgid ":ref:`A logging cookbook `" -msgstr "" +msgstr ":ref:`A logging cookbook `"