From 114129f17aeabe9567a4ef529d22c389a4510a87 Mon Sep 17 00:00:00 2001 From: kevinkuo Date: Sun, 29 Jan 2023 23:40:12 +0800 Subject: [PATCH 1/2] translate the part of asyncio-dev --- library/asyncio-dev.po | 695 +++++++++++++++++++++-------------------- 1 file changed, 349 insertions(+), 346 deletions(-) diff --git a/library/asyncio-dev.po b/library/asyncio-dev.po index f5335f0b4b..bb8388268e 100644 --- a/library/asyncio-dev.po +++ b/library/asyncio-dev.po @@ -1,346 +1,349 @@ -# Copyright (C) 2001-2022, Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.11\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2022-10-15 20:43+0000\n" -"PO-Revision-Date: 2022-06-11 15:29+0800\n" -"Last-Translator: Matt Wang \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Plural-Forms: nplurals=1; plural=0;\n" -"X-Generator: Poedit 3.1\n" - -#: ../../library/asyncio-dev.rst:7 -msgid "Developing with asyncio" -msgstr "使用 asyncio 開發" - -#: ../../library/asyncio-dev.rst:9 -msgid "" -"Asynchronous programming is different from classic \"sequential\" " -"programming." -msgstr "" -"非同步程式設計 (asynchronous programming) 與傳統的\"順序\"程式設計 " -"(sequential programming) 不同。" - -#: ../../library/asyncio-dev.rst:12 -msgid "" -"This page lists common mistakes and traps and explains how to avoid them." -msgstr "本頁列出常見的錯誤和陷阱，並解釋如何避免它們。" - -#: ../../library/asyncio-dev.rst:19 -msgid "Debug Mode" -msgstr "除錯模式" - -#: ../../library/asyncio-dev.rst:21 -msgid "" -"By default asyncio runs in production mode. In order to ease the " -"development asyncio has a *debug mode*." -msgstr "" -"在預設情況下 asyncio 以正式生產模式 (production mode) 執行。為了讓開發更輕" -"鬆，asyncio 還有一種\\ *除錯模式 (debug mode)*\\ 。" - -#: ../../library/asyncio-dev.rst:24 -msgid "There are several ways to enable asyncio debug mode:" -msgstr "有幾種方法可以啟用 asyncio 除錯模式：" - -#: ../../library/asyncio-dev.rst:26 -msgid "Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``." -msgstr "將 :envvar:`PYTHONASYNCIODEBUG` 環境變數設定為 ``1``。" - -#: ../../library/asyncio-dev.rst:28 -msgid "Using the :ref:`Python Development Mode `." -msgstr "使用 :ref:`Python 開發模式 (Development Mode) `。" - -#: ../../library/asyncio-dev.rst:30 -msgid "Passing ``debug=True`` to :func:`asyncio.run`." -msgstr "將 ``debug=True`` 傳遞給 :func:`asyncio.run`。" - -#: ../../library/asyncio-dev.rst:32 -msgid "Calling :meth:`loop.set_debug`." -msgstr "呼叫 :meth:`loop.set_debug`。" - -#: ../../library/asyncio-dev.rst:34 -msgid "In addition to enabling the debug mode, consider also:" -msgstr "除了啟用除錯模式外，還要考慮：" - -#: ../../library/asyncio-dev.rst:36 -msgid "" -"setting the log level of the :ref:`asyncio logger ` to :py:" -"data:`logging.DEBUG`, for example the following snippet of code can be run " -"at startup of the application::" -msgstr "" -"將 :ref:`asyncio logger（日誌記錄器） `\\ 的日誌級别設置為 :" -"py:data:`logging.DEBUG`，例如下面的程式片段可以在應用程式啟動時運行：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:42 -msgid "" -"configuring the :mod:`warnings` module to display :exc:`ResourceWarning` " -"warnings. One way of doing that is by using the :option:`-W` ``default`` " -"command line option." -msgstr "" -"配置 :mod:`warnings` 模組以顯示 :exc:`ResourceWarning` 警告。一種方法是使用 :" -"option:`-W` ``default`` 命令列選項。" - -#: ../../library/asyncio-dev.rst:47 -msgid "When the debug mode is enabled:" -msgstr "啟用除錯模式時：" - -#: ../../library/asyncio-dev.rst:49 -msgid "" -"asyncio checks for :ref:`coroutines that were not awaited ` and logs them; this mitigates the \"forgotten await\" " -"pitfall." -msgstr "" -"asyncio 會檢查\\ :ref:`未被等待的協程 `\\ 並" -"記錄他們；這會減輕\"被遺忘的等待 (forgotten await)\" 問題。" - -#: ../../library/asyncio-dev.rst:53 -msgid "" -"Many non-threadsafe asyncio APIs (such as :meth:`loop.call_soon` and :meth:" -"`loop.call_at` methods) raise an exception if they are called from a wrong " -"thread." -msgstr "" -"許多非執行緒安全 (non-threadsafe) 的 asyncio APIs（例如 :meth:`loop." -"call_soon` 和 :meth:`loop.call_at` 方法），如果從錯誤的執行緒呼叫就會引發例" -"外。" - -#: ../../library/asyncio-dev.rst:57 -msgid "" -"The execution time of the I/O selector is logged if it takes too long to " -"perform an I/O operation." -msgstr "" -"如果執行一個 I/O 操作花費的時間太長，則將 I/O 選擇器 (selector) 的執行時間記" -"錄到日誌中。" - -#: ../../library/asyncio-dev.rst:60 -msgid "" -"Callbacks taking longer than 100 milliseconds are logged. The :attr:`loop." -"slow_callback_duration` attribute can be used to set the minimum execution " -"duration in seconds that is considered \"slow\"." -msgstr "" -"執行時間超過 100 毫秒的回呼 (callback) 將會被記錄於日誌。屬性 :attr:`loop." -"slow_callback_duration` 可用於設定以秒為單位的最小執行持續時間，超過這個值執" -"行時間就會被視為\"緩慢\"。" - -#: ../../library/asyncio-dev.rst:68 -msgid "Concurrency and Multithreading" -msgstr "並行性和多執行緒 (Concurrency and Multithreading)" - -#: ../../library/asyncio-dev.rst:70 -msgid "" -"An event loop runs in a thread (typically the main thread) and executes all " -"callbacks and Tasks in its thread. While a Task is running in the event " -"loop, no other Tasks can run in the same thread. When a Task executes an " -"``await`` expression, the running Task gets suspended, and the event loop " -"executes the next Task." -msgstr "" -"事件迴圈在執行緒中運行（通常是主執行緒），並在其執行緒中執行所有回呼和 " -"Tasks（任務）。當一個 Task 在事件迴圈中運行時，沒有其他 Task 可以在同一個執行" -"緒中運行。當一個 Task 執行一個 ``await`` 運算式時，正在執行的 Task 會被暫停，" -"而事件迴圈會執行下一個 Task。" - -#: ../../library/asyncio-dev.rst:76 -msgid "" -"To schedule a :term:`callback` from another OS thread, the :meth:`loop." -"call_soon_threadsafe` method should be used. Example::" -msgstr "" -"要從不同的 OS 執行緒為一個 :term:`callback` 排程，應該使用 :meth:`loop." -"call_soon_threadsafe` 方法。例如：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:81 -msgid "" -"Almost all asyncio objects are not thread safe, which is typically not a " -"problem unless there is code that works with them from outside of a Task or " -"a callback. If there's a need for such code to call a low-level asyncio " -"API, the :meth:`loop.call_soon_threadsafe` method should be used, e.g.::" -msgstr "" -"幾乎所有 asyncio 物件都不支援執行緒安全 (thread safe)，這通常不是問題，除非" -"在 Task 或回呼函式之外有程式需要和它們一起運作。如果需要這樣的程式來呼叫低階 " -"asyncio API，應該使用 :meth:`loop.call_soon_threadsafe` 方法，例如：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:89 -msgid "" -"To schedule a coroutine object from a different OS thread, the :func:" -"`run_coroutine_threadsafe` function should be used. It returns a :class:" -"`concurrent.futures.Future` to access the result::" -msgstr "" -"要從不同的 OS 執行緒為一個協程物件排程，應該使用 :func:" -"`run_coroutine_threadsafe` 函式。它會回傳一個 :class:`concurrent.futures." -"Future` 以存取結果：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:102 -msgid "" -"To handle signals and to execute subprocesses, the event loop must be run in " -"the main thread." -msgstr "為了能夠處理訊號和執行子行程，事件迴圈必須於主執行緒中運行。" - -#: ../../library/asyncio-dev.rst:105 -msgid "" -"The :meth:`loop.run_in_executor` method can be used with a :class:" -"`concurrent.futures.ThreadPoolExecutor` to execute blocking code in a " -"different OS thread without blocking the OS thread that the event loop runs " -"in." -msgstr "" -":meth:`loop.run_in_executor` 方法可以和 :class:`concurrent.futures." -"ThreadPoolExecutor` 一起使用，這能夠在作業系統上另一個不同的執行緒中執行阻塞" -"程式，且避免阻塞執行事件迴圈的執行緒。" - -#: ../../library/asyncio-dev.rst:110 -msgid "" -"There is currently no way to schedule coroutines or callbacks directly from " -"a different process (such as one started with :mod:`multiprocessing`). The :" -"ref:`asyncio-event-loop-methods` section lists APIs that can read from pipes " -"and watch file descriptors without blocking the event loop. In addition, " -"asyncio's :ref:`Subprocess ` APIs provide a way to start " -"a process and communicate with it from the event loop. Lastly, the " -"aforementioned :meth:`loop.run_in_executor` method can also be used with a :" -"class:`concurrent.futures.ProcessPoolExecutor` to execute code in a " -"different process." -msgstr "" -"目前沒有什麼辦法能直接從另一個行程（例如透過 :mod:`multiprocessing` 啟動的程" -"序）來為協程或回呼排程。\\ :ref:`asyncio-event-loop-methods`\\ 小節列出了可以" -"從 pipes（管道）讀取並監視 file descriptor（檔案描述器）而不會阻塞事件迴圈的 " -"API。此外，asyncio 的\\ :ref:`子行程 ` API 提供了一種啟動" -"行程並從事件迴圈與其通訊的辦法。最後，之前提到的 :meth:`loop." -"run_in_executor` 方法也可和 :class:`concurrent.futures.ProcessPoolExecutor` " -"搭配使用，以在另一個行程中執行程式。" - -#: ../../library/asyncio-dev.rst:124 -msgid "Running Blocking Code" -msgstr "執行阻塞的程式" - -#: ../../library/asyncio-dev.rst:126 -msgid "" -"Blocking (CPU-bound) code should not be called directly. For example, if a " -"function performs a CPU-intensive calculation for 1 second, all concurrent " -"asyncio Tasks and IO operations would be delayed by 1 second." -msgstr "" -"不應該直接呼叫阻塞（CPU 密集型）程式。例如一個執行 1 秒 CPU 密集型計算的函" -"式，那麼所有並行非同步 Tasks 和 IO 操作都會被延遲 1 秒。" - -#: ../../library/asyncio-dev.rst:131 -msgid "" -"An executor can be used to run a task in a different thread or even in a " -"different process to avoid blocking the OS thread with the event loop. See " -"the :meth:`loop.run_in_executor` method for more details." -msgstr "" -"一個 executor（執行器）可以被用來在不同的執行緒、或甚至不同的行程中執行任務，" -"以避免使用事件迴圈阻塞 OS 執行緒。詳情請見 :meth:`loop.run_in_executor` 方" -"法。" - -#: ../../library/asyncio-dev.rst:140 -msgid "Logging" -msgstr "日誌記錄" - -#: ../../library/asyncio-dev.rst:142 -msgid "" -"asyncio uses the :mod:`logging` module and all logging is performed via the " -"``\"asyncio\"`` logger." -msgstr "" -"asyncio 使用 :mod:`logging` 模組，所有日誌記錄都是透過 ``\"asyncio\"`` " -"logger 執行的。" - -#: ../../library/asyncio-dev.rst:145 -msgid "" -"The default log level is :py:data:`logging.INFO`, which can be easily " -"adjusted::" -msgstr "" -"日誌級別被預設為 :py:data:`logging.INFO`，它可以很容易地被調整：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:151 -msgid "" -"Network logging can block the event loop. It is recommended to use a " -"separate thread for handling logs or use non-blocking IO. For example, see :" -"ref:`blocking-handlers`." -msgstr "" - -#: ../../library/asyncio-dev.rst:159 -msgid "Detect never-awaited coroutines" -msgstr "偵測從未被等待的 (never-awaited) 協程" - -#: ../../library/asyncio-dev.rst:161 -msgid "" -"When a coroutine function is called, but not awaited (e.g. ``coro()`` " -"instead of ``await coro()``) or the coroutine is not scheduled with :meth:" -"`asyncio.create_task`, asyncio will emit a :exc:`RuntimeWarning`::" -msgstr "" -"當協程函式被呼叫而不是被等待時（即執行 ``coro()`` 而不是 ``await coro()``）或" -"者協程沒有透過 :meth:`asyncio.create_task` 被排程，asyncio 將會發出 :exc:" -"`RuntimeWarning`：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:176 ../../library/asyncio-dev.rst:221 -msgid "Output::" -msgstr "" -"輸出：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:181 ../../library/asyncio-dev.rst:237 -msgid "Output in debug mode::" -msgstr "" -"除錯模式中的輸出：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:194 -msgid "" -"The usual fix is to either await the coroutine or call the :meth:`asyncio." -"create_task` function::" -msgstr "" -"常用的修復方法是去等待協程或者呼叫 :meth:`asyncio.create_task` 函式：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:202 -msgid "Detect never-retrieved exceptions" -msgstr "偵測從未被獲取的 (never-retrieved) 例外" - -#: ../../library/asyncio-dev.rst:204 -msgid "" -"If a :meth:`Future.set_exception` is called but the Future object is never " -"awaited on, the exception would never be propagated to the user code. In " -"this case, asyncio would emit a log message when the Future object is " -"garbage collected." -msgstr "" -"如果呼叫 :meth:`Future.set_exception`，但 Future 物件從未被等待，例外將無法被" -"傳播 (propagate) 到使用者程式。在這種情況下，當 Future 物件被垃圾回收 " -"(garbage collected) 時，asyncio 將發出一則日誌訊息。" - -#: ../../library/asyncio-dev.rst:209 -msgid "Example of an unhandled exception::" -msgstr "" -"未處理例外的例子：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:232 -msgid "" -":ref:`Enable the debug mode ` to get the traceback where " -"the task was created::" -msgstr "" -":ref:`啟用除錯模式 `\\ 以取得任務建立處的追蹤資訊 " -"(traceback)：\n" -"\n" -"::" +# Copyright (C) 2001-2022, Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.11\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2022-10-15 20:43+0000\n" +"PO-Revision-Date: 2023-01-29 23:26+0800\n" +"Last-Translator: Matt Wang \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/asyncio-dev.rst:7 +msgid "Developing with asyncio" +msgstr "使用 asyncio 開發" + +#: ../../library/asyncio-dev.rst:9 +msgid "" +"Asynchronous programming is different from classic \"sequential\" " +"programming." +msgstr "" +"非同步程式設計 (asynchronous programming) 與傳統的\"順序\"程式設計 " +"(sequential programming) 不同。" + +#: ../../library/asyncio-dev.rst:12 +msgid "" +"This page lists common mistakes and traps and explains how to avoid them." +msgstr "本頁列出常見的錯誤和陷阱，並解釋如何避免它們。" + +#: ../../library/asyncio-dev.rst:19 +msgid "Debug Mode" +msgstr "除錯模式" + +#: ../../library/asyncio-dev.rst:21 +msgid "" +"By default asyncio runs in production mode. In order to ease the " +"development asyncio has a *debug mode*." +msgstr "" +"在預設情況下 asyncio 以正式生產模式 (production mode) 執行。為了讓開發更輕" +"鬆，asyncio 還有一種\\ *除錯模式 (debug mode)*\\ 。" + +#: ../../library/asyncio-dev.rst:24 +msgid "There are several ways to enable asyncio debug mode:" +msgstr "有幾種方法可以啟用 asyncio 除錯模式：" + +#: ../../library/asyncio-dev.rst:26 +msgid "Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``." +msgstr "將 :envvar:`PYTHONASYNCIODEBUG` 環境變數設定為 ``1``。" + +#: ../../library/asyncio-dev.rst:28 +msgid "Using the :ref:`Python Development Mode `." +msgstr "使用 :ref:`Python 開發模式 (Development Mode) `。" + +#: ../../library/asyncio-dev.rst:30 +msgid "Passing ``debug=True`` to :func:`asyncio.run`." +msgstr "將 ``debug=True`` 傳遞給 :func:`asyncio.run`。" + +#: ../../library/asyncio-dev.rst:32 +msgid "Calling :meth:`loop.set_debug`." +msgstr "呼叫 :meth:`loop.set_debug`。" + +#: ../../library/asyncio-dev.rst:34 +msgid "In addition to enabling the debug mode, consider also:" +msgstr "除了啟用除錯模式外，還要考慮：" + +#: ../../library/asyncio-dev.rst:36 +msgid "" +"setting the log level of the :ref:`asyncio logger ` to :py:" +"data:`logging.DEBUG`, for example the following snippet of code can be run " +"at startup of the application::" +msgstr "" +"將 :ref:`asyncio logger（日誌記錄器） `\\ 的日誌級别設置為 :" +"py:data:`logging.DEBUG`，例如下面的程式片段可以在應用程式啟動時運行：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:42 +msgid "" +"configuring the :mod:`warnings` module to display :exc:`ResourceWarning` " +"warnings. One way of doing that is by using the :option:`-W` ``default`` " +"command line option." +msgstr "" +"配置 :mod:`warnings` 模組以顯示 :exc:`ResourceWarning` 警告。一種方法是使用 :" +"option:`-W` ``default`` 命令列選項。" + +#: ../../library/asyncio-dev.rst:47 +msgid "When the debug mode is enabled:" +msgstr "啟用除錯模式時：" + +#: ../../library/asyncio-dev.rst:49 +msgid "" +"asyncio checks for :ref:`coroutines that were not awaited ` and logs them; this mitigates the \"forgotten await\" " +"pitfall." +msgstr "" +"asyncio 會檢查\\ :ref:`未被等待的協程 `\\ 並" +"記錄他們；這會減輕\"被遺忘的等待 (forgotten await)\" 問題。" + +#: ../../library/asyncio-dev.rst:53 +msgid "" +"Many non-threadsafe asyncio APIs (such as :meth:`loop.call_soon` and :meth:" +"`loop.call_at` methods) raise an exception if they are called from a wrong " +"thread." +msgstr "" +"許多非執行緒安全 (non-threadsafe) 的 asyncio APIs（例如 :meth:`loop." +"call_soon` 和 :meth:`loop.call_at` 方法），如果從錯誤的執行緒呼叫就會引發例" +"外。" + +#: ../../library/asyncio-dev.rst:57 +msgid "" +"The execution time of the I/O selector is logged if it takes too long to " +"perform an I/O operation." +msgstr "" +"如果執行一個 I/O 操作花費的時間太長，則將 I/O 選擇器 (selector) 的執行時間記" +"錄到日誌中。" + +#: ../../library/asyncio-dev.rst:60 +msgid "" +"Callbacks taking longer than 100 milliseconds are logged. The :attr:`loop." +"slow_callback_duration` attribute can be used to set the minimum execution " +"duration in seconds that is considered \"slow\"." +msgstr "" +"執行時間超過 100 毫秒的回呼 (callback) 將會被記錄於日誌。屬性 :attr:`loop." +"slow_callback_duration` 可用於設定以秒為單位的最小執行持續時間，超過這個值執" +"行時間就會被視為\"緩慢\"。" + +#: ../../library/asyncio-dev.rst:68 +msgid "Concurrency and Multithreading" +msgstr "並行性和多執行緒 (Concurrency and Multithreading)" + +#: ../../library/asyncio-dev.rst:70 +msgid "" +"An event loop runs in a thread (typically the main thread) and executes all " +"callbacks and Tasks in its thread. While a Task is running in the event " +"loop, no other Tasks can run in the same thread. When a Task executes an " +"``await`` expression, the running Task gets suspended, and the event loop " +"executes the next Task." +msgstr "" +"事件迴圈在執行緒中運行（通常是主執行緒），並在其執行緒中執行所有回呼和 Tasks" +"（任務）。當一個 Task 在事件迴圈中運行時，沒有其他 Task 可以在同一個執行緒中" +"運行。當一個 Task 執行一個 ``await`` 運算式時，正在執行的 Task 會被暫停，而事" +"件迴圈會執行下一個 Task。" + +#: ../../library/asyncio-dev.rst:76 +msgid "" +"To schedule a :term:`callback` from another OS thread, the :meth:`loop." +"call_soon_threadsafe` method should be used. Example::" +msgstr "" +"要從不同的 OS 執行緒為一個 :term:`callback` 排程，應該使用 :meth:`loop." +"call_soon_threadsafe` 方法。例如：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:81 +msgid "" +"Almost all asyncio objects are not thread safe, which is typically not a " +"problem unless there is code that works with them from outside of a Task or " +"a callback. If there's a need for such code to call a low-level asyncio " +"API, the :meth:`loop.call_soon_threadsafe` method should be used, e.g.::" +msgstr "" +"幾乎所有 asyncio 物件都不支援執行緒安全 (thread safe)，這通常不是問題，除非" +"在 Task 或回呼函式之外有程式需要和它們一起運作。如果需要這樣的程式來呼叫低階 " +"asyncio API，應該使用 :meth:`loop.call_soon_threadsafe` 方法，例如：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:89 +msgid "" +"To schedule a coroutine object from a different OS thread, the :func:" +"`run_coroutine_threadsafe` function should be used. It returns a :class:" +"`concurrent.futures.Future` to access the result::" +msgstr "" +"要從不同的 OS 執行緒為一個協程物件排程，應該使用 :func:" +"`run_coroutine_threadsafe` 函式。它會回傳一個 :class:`concurrent.futures." +"Future` 以存取結果：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:102 +msgid "" +"To handle signals and to execute subprocesses, the event loop must be run in " +"the main thread." +msgstr "為了能夠處理訊號和執行子行程，事件迴圈必須於主執行緒中運行。" + +#: ../../library/asyncio-dev.rst:105 +msgid "" +"The :meth:`loop.run_in_executor` method can be used with a :class:" +"`concurrent.futures.ThreadPoolExecutor` to execute blocking code in a " +"different OS thread without blocking the OS thread that the event loop runs " +"in." +msgstr "" +":meth:`loop.run_in_executor` 方法可以和 :class:`concurrent.futures." +"ThreadPoolExecutor` 一起使用，這能夠在作業系統上另一個不同的執行緒中執行阻塞" +"程式，且避免阻塞執行事件迴圈的執行緒。" + +#: ../../library/asyncio-dev.rst:110 +msgid "" +"There is currently no way to schedule coroutines or callbacks directly from " +"a different process (such as one started with :mod:`multiprocessing`). The :" +"ref:`asyncio-event-loop-methods` section lists APIs that can read from pipes " +"and watch file descriptors without blocking the event loop. In addition, " +"asyncio's :ref:`Subprocess ` APIs provide a way to start " +"a process and communicate with it from the event loop. Lastly, the " +"aforementioned :meth:`loop.run_in_executor` method can also be used with a :" +"class:`concurrent.futures.ProcessPoolExecutor` to execute code in a " +"different process." +msgstr "" +"目前沒有什麼辦法能直接從另一個行程（例如透過 :mod:`multiprocessing` 啟動的程" +"序）來為協程或回呼排程。\\ :ref:`asyncio-event-loop-methods`\\ 小節列出了可以" +"從 pipes（管道）讀取並監視 file descriptor（檔案描述器）而不會阻塞事件迴圈的 " +"API。此外，asyncio 的\\ :ref:`子行程 ` API 提供了一種啟動" +"行程並從事件迴圈與其通訊的辦法。最後，之前提到的 :meth:`loop." +"run_in_executor` 方法也可和 :class:`concurrent.futures.ProcessPoolExecutor` " +"搭配使用，以在另一個行程中執行程式。" + +#: ../../library/asyncio-dev.rst:124 +msgid "Running Blocking Code" +msgstr "執行阻塞的程式" + +#: ../../library/asyncio-dev.rst:126 +msgid "" +"Blocking (CPU-bound) code should not be called directly. For example, if a " +"function performs a CPU-intensive calculation for 1 second, all concurrent " +"asyncio Tasks and IO operations would be delayed by 1 second." +msgstr "" +"不應該直接呼叫阻塞（CPU 密集型）程式。例如一個執行 1 秒 CPU 密集型計算的函" +"式，那麼所有並行非同步 Tasks 和 IO 操作都會被延遲 1 秒。" + +#: ../../library/asyncio-dev.rst:131 +msgid "" +"An executor can be used to run a task in a different thread or even in a " +"different process to avoid blocking the OS thread with the event loop. See " +"the :meth:`loop.run_in_executor` method for more details." +msgstr "" +"一個 executor（執行器）可以被用來在不同的執行緒、或甚至不同的行程中執行任務，" +"以避免使用事件迴圈阻塞 OS 執行緒。詳情請見 :meth:`loop.run_in_executor` 方" +"法。" + +#: ../../library/asyncio-dev.rst:140 +msgid "Logging" +msgstr "日誌記錄" + +#: ../../library/asyncio-dev.rst:142 +msgid "" +"asyncio uses the :mod:`logging` module and all logging is performed via the " +"``\"asyncio\"`` logger." +msgstr "" +"asyncio 使用 :mod:`logging` 模組，所有日誌記錄都是透過 ``\"asyncio\"`` " +"logger 執行的。" + +#: ../../library/asyncio-dev.rst:145 +msgid "" +"The default log level is :py:data:`logging.INFO`, which can be easily " +"adjusted::" +msgstr "" +"日誌級別被預設為 :py:data:`logging.INFO`，它可以很容易地被調整：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:151 +#, fuzzy +msgid "" +"Network logging can block the event loop. It is recommended to use a " +"separate thread for handling logs or use non-blocking IO. For example, see :" +"ref:`blocking-handlers`." +msgstr "" +"網路日誌記錄可以阻止事件迴圈。建議使用單獨的執行緒來處理日誌或使用非阻塞 IO。" +"例如，參見 :ref:`blocking-handlers`。" + +#: ../../library/asyncio-dev.rst:159 +msgid "Detect never-awaited coroutines" +msgstr "偵測從未被等待的 (never-awaited) 協程" + +#: ../../library/asyncio-dev.rst:161 +msgid "" +"When a coroutine function is called, but not awaited (e.g. ``coro()`` " +"instead of ``await coro()``) or the coroutine is not scheduled with :meth:" +"`asyncio.create_task`, asyncio will emit a :exc:`RuntimeWarning`::" +msgstr "" +"當協程函式被呼叫而不是被等待時（即執行 ``coro()`` 而不是 ``await coro()``）或" +"者協程沒有透過 :meth:`asyncio.create_task` 被排程，asyncio 將會發出 :exc:" +"`RuntimeWarning`：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:176 ../../library/asyncio-dev.rst:221 +msgid "Output::" +msgstr "" +"輸出：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:181 ../../library/asyncio-dev.rst:237 +msgid "Output in debug mode::" +msgstr "" +"除錯模式中的輸出：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:194 +msgid "" +"The usual fix is to either await the coroutine or call the :meth:`asyncio." +"create_task` function::" +msgstr "" +"常用的修復方法是去等待協程或者呼叫 :meth:`asyncio.create_task` 函式：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:202 +msgid "Detect never-retrieved exceptions" +msgstr "偵測從未被獲取的 (never-retrieved) 例外" + +#: ../../library/asyncio-dev.rst:204 +msgid "" +"If a :meth:`Future.set_exception` is called but the Future object is never " +"awaited on, the exception would never be propagated to the user code. In " +"this case, asyncio would emit a log message when the Future object is " +"garbage collected." +msgstr "" +"如果呼叫 :meth:`Future.set_exception`，但 Future 物件從未被等待，例外將無法被" +"傳播 (propagate) 到使用者程式。在這種情況下，當 Future 物件被垃圾回收 " +"(garbage collected) 時，asyncio 將發出一則日誌訊息。" + +#: ../../library/asyncio-dev.rst:209 +msgid "Example of an unhandled exception::" +msgstr "" +"未處理例外的例子：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:232 +msgid "" +":ref:`Enable the debug mode ` to get the traceback where " +"the task was created::" +msgstr "" +":ref:`啟用除錯模式 `\\ 以取得任務建立處的追蹤資訊 " +"(traceback)：\n" +"\n" +"::" From 19863596ad3dcca7410a633ae0d41ffb9c38c1f2 Mon Sep 17 00:00:00 2001 From: "Wei-Hsiang (Matt) Wang" Date: Sat, 18 Feb 2023 14:14:48 +0800 Subject: [PATCH 2/2] Update library/asyncio-dev.po --- library/asyncio-dev.po | 697 ++++++++++++++++++++--------------------- 1 file changed, 348 insertions(+), 349 deletions(-) diff --git a/library/asyncio-dev.po b/library/asyncio-dev.po index bb8388268e..59ec6569f7 100644 --- a/library/asyncio-dev.po +++ b/library/asyncio-dev.po @@ -1,349 +1,348 @@ -# Copyright (C) 2001-2022, Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.11\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2022-10-15 20:43+0000\n" -"PO-Revision-Date: 2023-01-29 23:26+0800\n" -"Last-Translator: Matt Wang \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Plural-Forms: nplurals=1; plural=0;\n" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/asyncio-dev.rst:7 -msgid "Developing with asyncio" -msgstr "使用 asyncio 開發" - -#: ../../library/asyncio-dev.rst:9 -msgid "" -"Asynchronous programming is different from classic \"sequential\" " -"programming." -msgstr "" -"非同步程式設計 (asynchronous programming) 與傳統的\"順序\"程式設計 " -"(sequential programming) 不同。" - -#: ../../library/asyncio-dev.rst:12 -msgid "" -"This page lists common mistakes and traps and explains how to avoid them." -msgstr "本頁列出常見的錯誤和陷阱，並解釋如何避免它們。" - -#: ../../library/asyncio-dev.rst:19 -msgid "Debug Mode" -msgstr "除錯模式" - -#: ../../library/asyncio-dev.rst:21 -msgid "" -"By default asyncio runs in production mode. In order to ease the " -"development asyncio has a *debug mode*." -msgstr "" -"在預設情況下 asyncio 以正式生產模式 (production mode) 執行。為了讓開發更輕" -"鬆，asyncio 還有一種\\ *除錯模式 (debug mode)*\\ 。" - -#: ../../library/asyncio-dev.rst:24 -msgid "There are several ways to enable asyncio debug mode:" -msgstr "有幾種方法可以啟用 asyncio 除錯模式：" - -#: ../../library/asyncio-dev.rst:26 -msgid "Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``." -msgstr "將 :envvar:`PYTHONASYNCIODEBUG` 環境變數設定為 ``1``。" - -#: ../../library/asyncio-dev.rst:28 -msgid "Using the :ref:`Python Development Mode `." -msgstr "使用 :ref:`Python 開發模式 (Development Mode) `。" - -#: ../../library/asyncio-dev.rst:30 -msgid "Passing ``debug=True`` to :func:`asyncio.run`." -msgstr "將 ``debug=True`` 傳遞給 :func:`asyncio.run`。" - -#: ../../library/asyncio-dev.rst:32 -msgid "Calling :meth:`loop.set_debug`." -msgstr "呼叫 :meth:`loop.set_debug`。" - -#: ../../library/asyncio-dev.rst:34 -msgid "In addition to enabling the debug mode, consider also:" -msgstr "除了啟用除錯模式外，還要考慮：" - -#: ../../library/asyncio-dev.rst:36 -msgid "" -"setting the log level of the :ref:`asyncio logger ` to :py:" -"data:`logging.DEBUG`, for example the following snippet of code can be run " -"at startup of the application::" -msgstr "" -"將 :ref:`asyncio logger（日誌記錄器） `\\ 的日誌級别設置為 :" -"py:data:`logging.DEBUG`，例如下面的程式片段可以在應用程式啟動時運行：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:42 -msgid "" -"configuring the :mod:`warnings` module to display :exc:`ResourceWarning` " -"warnings. One way of doing that is by using the :option:`-W` ``default`` " -"command line option." -msgstr "" -"配置 :mod:`warnings` 模組以顯示 :exc:`ResourceWarning` 警告。一種方法是使用 :" -"option:`-W` ``default`` 命令列選項。" - -#: ../../library/asyncio-dev.rst:47 -msgid "When the debug mode is enabled:" -msgstr "啟用除錯模式時：" - -#: ../../library/asyncio-dev.rst:49 -msgid "" -"asyncio checks for :ref:`coroutines that were not awaited ` and logs them; this mitigates the \"forgotten await\" " -"pitfall." -msgstr "" -"asyncio 會檢查\\ :ref:`未被等待的協程 `\\ 並" -"記錄他們；這會減輕\"被遺忘的等待 (forgotten await)\" 問題。" - -#: ../../library/asyncio-dev.rst:53 -msgid "" -"Many non-threadsafe asyncio APIs (such as :meth:`loop.call_soon` and :meth:" -"`loop.call_at` methods) raise an exception if they are called from a wrong " -"thread." -msgstr "" -"許多非執行緒安全 (non-threadsafe) 的 asyncio APIs（例如 :meth:`loop." -"call_soon` 和 :meth:`loop.call_at` 方法），如果從錯誤的執行緒呼叫就會引發例" -"外。" - -#: ../../library/asyncio-dev.rst:57 -msgid "" -"The execution time of the I/O selector is logged if it takes too long to " -"perform an I/O operation." -msgstr "" -"如果執行一個 I/O 操作花費的時間太長，則將 I/O 選擇器 (selector) 的執行時間記" -"錄到日誌中。" - -#: ../../library/asyncio-dev.rst:60 -msgid "" -"Callbacks taking longer than 100 milliseconds are logged. The :attr:`loop." -"slow_callback_duration` attribute can be used to set the minimum execution " -"duration in seconds that is considered \"slow\"." -msgstr "" -"執行時間超過 100 毫秒的回呼 (callback) 將會被記錄於日誌。屬性 :attr:`loop." -"slow_callback_duration` 可用於設定以秒為單位的最小執行持續時間，超過這個值執" -"行時間就會被視為\"緩慢\"。" - -#: ../../library/asyncio-dev.rst:68 -msgid "Concurrency and Multithreading" -msgstr "並行性和多執行緒 (Concurrency and Multithreading)" - -#: ../../library/asyncio-dev.rst:70 -msgid "" -"An event loop runs in a thread (typically the main thread) and executes all " -"callbacks and Tasks in its thread. While a Task is running in the event " -"loop, no other Tasks can run in the same thread. When a Task executes an " -"``await`` expression, the running Task gets suspended, and the event loop " -"executes the next Task." -msgstr "" -"事件迴圈在執行緒中運行（通常是主執行緒），並在其執行緒中執行所有回呼和 Tasks" -"（任務）。當一個 Task 在事件迴圈中運行時，沒有其他 Task 可以在同一個執行緒中" -"運行。當一個 Task 執行一個 ``await`` 運算式時，正在執行的 Task 會被暫停，而事" -"件迴圈會執行下一個 Task。" - -#: ../../library/asyncio-dev.rst:76 -msgid "" -"To schedule a :term:`callback` from another OS thread, the :meth:`loop." -"call_soon_threadsafe` method should be used. Example::" -msgstr "" -"要從不同的 OS 執行緒為一個 :term:`callback` 排程，應該使用 :meth:`loop." -"call_soon_threadsafe` 方法。例如：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:81 -msgid "" -"Almost all asyncio objects are not thread safe, which is typically not a " -"problem unless there is code that works with them from outside of a Task or " -"a callback. If there's a need for such code to call a low-level asyncio " -"API, the :meth:`loop.call_soon_threadsafe` method should be used, e.g.::" -msgstr "" -"幾乎所有 asyncio 物件都不支援執行緒安全 (thread safe)，這通常不是問題，除非" -"在 Task 或回呼函式之外有程式需要和它們一起運作。如果需要這樣的程式來呼叫低階 " -"asyncio API，應該使用 :meth:`loop.call_soon_threadsafe` 方法，例如：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:89 -msgid "" -"To schedule a coroutine object from a different OS thread, the :func:" -"`run_coroutine_threadsafe` function should be used. It returns a :class:" -"`concurrent.futures.Future` to access the result::" -msgstr "" -"要從不同的 OS 執行緒為一個協程物件排程，應該使用 :func:" -"`run_coroutine_threadsafe` 函式。它會回傳一個 :class:`concurrent.futures." -"Future` 以存取結果：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:102 -msgid "" -"To handle signals and to execute subprocesses, the event loop must be run in " -"the main thread." -msgstr "為了能夠處理訊號和執行子行程，事件迴圈必須於主執行緒中運行。" - -#: ../../library/asyncio-dev.rst:105 -msgid "" -"The :meth:`loop.run_in_executor` method can be used with a :class:" -"`concurrent.futures.ThreadPoolExecutor` to execute blocking code in a " -"different OS thread without blocking the OS thread that the event loop runs " -"in." -msgstr "" -":meth:`loop.run_in_executor` 方法可以和 :class:`concurrent.futures." -"ThreadPoolExecutor` 一起使用，這能夠在作業系統上另一個不同的執行緒中執行阻塞" -"程式，且避免阻塞執行事件迴圈的執行緒。" - -#: ../../library/asyncio-dev.rst:110 -msgid "" -"There is currently no way to schedule coroutines or callbacks directly from " -"a different process (such as one started with :mod:`multiprocessing`). The :" -"ref:`asyncio-event-loop-methods` section lists APIs that can read from pipes " -"and watch file descriptors without blocking the event loop. In addition, " -"asyncio's :ref:`Subprocess ` APIs provide a way to start " -"a process and communicate with it from the event loop. Lastly, the " -"aforementioned :meth:`loop.run_in_executor` method can also be used with a :" -"class:`concurrent.futures.ProcessPoolExecutor` to execute code in a " -"different process." -msgstr "" -"目前沒有什麼辦法能直接從另一個行程（例如透過 :mod:`multiprocessing` 啟動的程" -"序）來為協程或回呼排程。\\ :ref:`asyncio-event-loop-methods`\\ 小節列出了可以" -"從 pipes（管道）讀取並監視 file descriptor（檔案描述器）而不會阻塞事件迴圈的 " -"API。此外，asyncio 的\\ :ref:`子行程 ` API 提供了一種啟動" -"行程並從事件迴圈與其通訊的辦法。最後，之前提到的 :meth:`loop." -"run_in_executor` 方法也可和 :class:`concurrent.futures.ProcessPoolExecutor` " -"搭配使用，以在另一個行程中執行程式。" - -#: ../../library/asyncio-dev.rst:124 -msgid "Running Blocking Code" -msgstr "執行阻塞的程式" - -#: ../../library/asyncio-dev.rst:126 -msgid "" -"Blocking (CPU-bound) code should not be called directly. For example, if a " -"function performs a CPU-intensive calculation for 1 second, all concurrent " -"asyncio Tasks and IO operations would be delayed by 1 second." -msgstr "" -"不應該直接呼叫阻塞（CPU 密集型）程式。例如一個執行 1 秒 CPU 密集型計算的函" -"式，那麼所有並行非同步 Tasks 和 IO 操作都會被延遲 1 秒。" - -#: ../../library/asyncio-dev.rst:131 -msgid "" -"An executor can be used to run a task in a different thread or even in a " -"different process to avoid blocking the OS thread with the event loop. See " -"the :meth:`loop.run_in_executor` method for more details." -msgstr "" -"一個 executor（執行器）可以被用來在不同的執行緒、或甚至不同的行程中執行任務，" -"以避免使用事件迴圈阻塞 OS 執行緒。詳情請見 :meth:`loop.run_in_executor` 方" -"法。" - -#: ../../library/asyncio-dev.rst:140 -msgid "Logging" -msgstr "日誌記錄" - -#: ../../library/asyncio-dev.rst:142 -msgid "" -"asyncio uses the :mod:`logging` module and all logging is performed via the " -"``\"asyncio\"`` logger." -msgstr "" -"asyncio 使用 :mod:`logging` 模組，所有日誌記錄都是透過 ``\"asyncio\"`` " -"logger 執行的。" - -#: ../../library/asyncio-dev.rst:145 -msgid "" -"The default log level is :py:data:`logging.INFO`, which can be easily " -"adjusted::" -msgstr "" -"日誌級別被預設為 :py:data:`logging.INFO`，它可以很容易地被調整：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:151 -#, fuzzy -msgid "" -"Network logging can block the event loop. It is recommended to use a " -"separate thread for handling logs or use non-blocking IO. For example, see :" -"ref:`blocking-handlers`." -msgstr "" -"網路日誌記錄可以阻止事件迴圈。建議使用單獨的執行緒來處理日誌或使用非阻塞 IO。" -"例如，參見 :ref:`blocking-handlers`。" - -#: ../../library/asyncio-dev.rst:159 -msgid "Detect never-awaited coroutines" -msgstr "偵測從未被等待的 (never-awaited) 協程" - -#: ../../library/asyncio-dev.rst:161 -msgid "" -"When a coroutine function is called, but not awaited (e.g. ``coro()`` " -"instead of ``await coro()``) or the coroutine is not scheduled with :meth:" -"`asyncio.create_task`, asyncio will emit a :exc:`RuntimeWarning`::" -msgstr "" -"當協程函式被呼叫而不是被等待時（即執行 ``coro()`` 而不是 ``await coro()``）或" -"者協程沒有透過 :meth:`asyncio.create_task` 被排程，asyncio 將會發出 :exc:" -"`RuntimeWarning`：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:176 ../../library/asyncio-dev.rst:221 -msgid "Output::" -msgstr "" -"輸出：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:181 ../../library/asyncio-dev.rst:237 -msgid "Output in debug mode::" -msgstr "" -"除錯模式中的輸出：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:194 -msgid "" -"The usual fix is to either await the coroutine or call the :meth:`asyncio." -"create_task` function::" -msgstr "" -"常用的修復方法是去等待協程或者呼叫 :meth:`asyncio.create_task` 函式：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:202 -msgid "Detect never-retrieved exceptions" -msgstr "偵測從未被獲取的 (never-retrieved) 例外" - -#: ../../library/asyncio-dev.rst:204 -msgid "" -"If a :meth:`Future.set_exception` is called but the Future object is never " -"awaited on, the exception would never be propagated to the user code. In " -"this case, asyncio would emit a log message when the Future object is " -"garbage collected." -msgstr "" -"如果呼叫 :meth:`Future.set_exception`，但 Future 物件從未被等待，例外將無法被" -"傳播 (propagate) 到使用者程式。在這種情況下，當 Future 物件被垃圾回收 " -"(garbage collected) 時，asyncio 將發出一則日誌訊息。" - -#: ../../library/asyncio-dev.rst:209 -msgid "Example of an unhandled exception::" -msgstr "" -"未處理例外的例子：\n" -"\n" -"::" - -#: ../../library/asyncio-dev.rst:232 -msgid "" -":ref:`Enable the debug mode ` to get the traceback where " -"the task was created::" -msgstr "" -":ref:`啟用除錯模式 `\\ 以取得任務建立處的追蹤資訊 " -"(traceback)：\n" -"\n" -"::" +# Copyright (C) 2001-2022, Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.11\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2022-10-15 20:43+0000\n" +"PO-Revision-Date: 2023-02-18 14:17+0800\n" +"Last-Translator: Matt Wang \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/asyncio-dev.rst:7 +msgid "Developing with asyncio" +msgstr "使用 asyncio 開發" + +#: ../../library/asyncio-dev.rst:9 +msgid "" +"Asynchronous programming is different from classic \"sequential\" " +"programming." +msgstr "" +"非同步程式設計 (asynchronous programming) 與傳統的\"順序\"程式設計 " +"(sequential programming) 不同。" + +#: ../../library/asyncio-dev.rst:12 +msgid "" +"This page lists common mistakes and traps and explains how to avoid them." +msgstr "本頁列出常見的錯誤和陷阱，並解釋如何避免它們。" + +#: ../../library/asyncio-dev.rst:19 +msgid "Debug Mode" +msgstr "除錯模式" + +#: ../../library/asyncio-dev.rst:21 +msgid "" +"By default asyncio runs in production mode. In order to ease the " +"development asyncio has a *debug mode*." +msgstr "" +"在預設情況下 asyncio 以正式生產模式 (production mode) 執行。為了讓開發更輕" +"鬆，asyncio 還有一種\\ *除錯模式 (debug mode)*\\ 。" + +#: ../../library/asyncio-dev.rst:24 +msgid "There are several ways to enable asyncio debug mode:" +msgstr "有幾種方法可以啟用 asyncio 除錯模式：" + +#: ../../library/asyncio-dev.rst:26 +msgid "Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``." +msgstr "將 :envvar:`PYTHONASYNCIODEBUG` 環境變數設定為 ``1``。" + +#: ../../library/asyncio-dev.rst:28 +msgid "Using the :ref:`Python Development Mode `." +msgstr "使用 :ref:`Python 開發模式 (Development Mode) `。" + +#: ../../library/asyncio-dev.rst:30 +msgid "Passing ``debug=True`` to :func:`asyncio.run`." +msgstr "將 ``debug=True`` 傳遞給 :func:`asyncio.run`。" + +#: ../../library/asyncio-dev.rst:32 +msgid "Calling :meth:`loop.set_debug`." +msgstr "呼叫 :meth:`loop.set_debug`。" + +#: ../../library/asyncio-dev.rst:34 +msgid "In addition to enabling the debug mode, consider also:" +msgstr "除了啟用除錯模式外，還要考慮：" + +#: ../../library/asyncio-dev.rst:36 +msgid "" +"setting the log level of the :ref:`asyncio logger ` to :py:" +"data:`logging.DEBUG`, for example the following snippet of code can be run " +"at startup of the application::" +msgstr "" +"將 :ref:`asyncio logger（日誌記錄器） `\\ 的日誌級别設置為 :" +"py:data:`logging.DEBUG`，例如下面的程式片段可以在應用程式啟動時運行：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:42 +msgid "" +"configuring the :mod:`warnings` module to display :exc:`ResourceWarning` " +"warnings. One way of doing that is by using the :option:`-W` ``default`` " +"command line option." +msgstr "" +"配置 :mod:`warnings` 模組以顯示 :exc:`ResourceWarning` 警告。一種方法是使用 :" +"option:`-W` ``default`` 命令列選項。" + +#: ../../library/asyncio-dev.rst:47 +msgid "When the debug mode is enabled:" +msgstr "啟用除錯模式時：" + +#: ../../library/asyncio-dev.rst:49 +msgid "" +"asyncio checks for :ref:`coroutines that were not awaited ` and logs them; this mitigates the \"forgotten await\" " +"pitfall." +msgstr "" +"asyncio 會檢查\\ :ref:`未被等待的協程 `\\ 並" +"記錄他們；這會減輕\"被遺忘的等待 (forgotten await)\" 問題。" + +#: ../../library/asyncio-dev.rst:53 +msgid "" +"Many non-threadsafe asyncio APIs (such as :meth:`loop.call_soon` and :meth:" +"`loop.call_at` methods) raise an exception if they are called from a wrong " +"thread." +msgstr "" +"許多非執行緒安全 (non-threadsafe) 的 asyncio APIs（例如 :meth:`loop." +"call_soon` 和 :meth:`loop.call_at` 方法），如果從錯誤的執行緒呼叫就會引發例" +"外。" + +#: ../../library/asyncio-dev.rst:57 +msgid "" +"The execution time of the I/O selector is logged if it takes too long to " +"perform an I/O operation." +msgstr "" +"如果執行一個 I/O 操作花費的時間太長，則將 I/O 選擇器 (selector) 的執行時間記" +"錄到日誌中。" + +#: ../../library/asyncio-dev.rst:60 +msgid "" +"Callbacks taking longer than 100 milliseconds are logged. The :attr:`loop." +"slow_callback_duration` attribute can be used to set the minimum execution " +"duration in seconds that is considered \"slow\"." +msgstr "" +"執行時間超過 100 毫秒的回呼 (callback) 將會被記錄於日誌。屬性 :attr:`loop." +"slow_callback_duration` 可用於設定以秒為單位的最小執行持續時間，超過這個值執" +"行時間就會被視為\"緩慢\"。" + +#: ../../library/asyncio-dev.rst:68 +msgid "Concurrency and Multithreading" +msgstr "並行性和多執行緒 (Concurrency and Multithreading)" + +#: ../../library/asyncio-dev.rst:70 +msgid "" +"An event loop runs in a thread (typically the main thread) and executes all " +"callbacks and Tasks in its thread. While a Task is running in the event " +"loop, no other Tasks can run in the same thread. When a Task executes an " +"``await`` expression, the running Task gets suspended, and the event loop " +"executes the next Task." +msgstr "" +"事件迴圈在執行緒中運行（通常是主執行緒），並在其執行緒中執行所有回呼和 Tasks" +"（任務）。當一個 Task 在事件迴圈中運行時，沒有其他 Task 可以在同一個執行緒中" +"運行。當一個 Task 執行一個 ``await`` 運算式時，正在執行的 Task 會被暫停，而事" +"件迴圈會執行下一個 Task。" + +#: ../../library/asyncio-dev.rst:76 +msgid "" +"To schedule a :term:`callback` from another OS thread, the :meth:`loop." +"call_soon_threadsafe` method should be used. Example::" +msgstr "" +"要從不同的 OS 執行緒為一個 :term:`callback` 排程，應該使用 :meth:`loop." +"call_soon_threadsafe` 方法。例如：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:81 +msgid "" +"Almost all asyncio objects are not thread safe, which is typically not a " +"problem unless there is code that works with them from outside of a Task or " +"a callback. If there's a need for such code to call a low-level asyncio " +"API, the :meth:`loop.call_soon_threadsafe` method should be used, e.g.::" +msgstr "" +"幾乎所有 asyncio 物件都不支援執行緒安全 (thread safe)，這通常不是問題，除非" +"在 Task 或回呼函式之外有程式需要和它們一起運作。如果需要這樣的程式來呼叫低階 " +"asyncio API，應該使用 :meth:`loop.call_soon_threadsafe` 方法，例如：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:89 +msgid "" +"To schedule a coroutine object from a different OS thread, the :func:" +"`run_coroutine_threadsafe` function should be used. It returns a :class:" +"`concurrent.futures.Future` to access the result::" +msgstr "" +"要從不同的 OS 執行緒為一個協程物件排程，應該使用 :func:" +"`run_coroutine_threadsafe` 函式。它會回傳一個 :class:`concurrent.futures." +"Future` 以存取結果：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:102 +msgid "" +"To handle signals and to execute subprocesses, the event loop must be run in " +"the main thread." +msgstr "為了能夠處理訊號和執行子行程，事件迴圈必須於主執行緒中運行。" + +#: ../../library/asyncio-dev.rst:105 +msgid "" +"The :meth:`loop.run_in_executor` method can be used with a :class:" +"`concurrent.futures.ThreadPoolExecutor` to execute blocking code in a " +"different OS thread without blocking the OS thread that the event loop runs " +"in." +msgstr "" +":meth:`loop.run_in_executor` 方法可以和 :class:`concurrent.futures." +"ThreadPoolExecutor` 一起使用，這能夠在作業系統上另一個不同的執行緒中執行阻塞" +"程式，且避免阻塞執行事件迴圈的執行緒。" + +#: ../../library/asyncio-dev.rst:110 +msgid "" +"There is currently no way to schedule coroutines or callbacks directly from " +"a different process (such as one started with :mod:`multiprocessing`). The :" +"ref:`asyncio-event-loop-methods` section lists APIs that can read from pipes " +"and watch file descriptors without blocking the event loop. In addition, " +"asyncio's :ref:`Subprocess ` APIs provide a way to start " +"a process and communicate with it from the event loop. Lastly, the " +"aforementioned :meth:`loop.run_in_executor` method can also be used with a :" +"class:`concurrent.futures.ProcessPoolExecutor` to execute code in a " +"different process." +msgstr "" +"目前沒有什麼辦法能直接從另一個行程（例如透過 :mod:`multiprocessing` 啟動的程" +"序）來為協程或回呼排程。\\ :ref:`asyncio-event-loop-methods`\\ 小節列出了可以" +"從 pipes（管道）讀取並監視 file descriptor（檔案描述器）而不會阻塞事件迴圈的 " +"API。此外，asyncio 的\\ :ref:`子行程 ` API 提供了一種啟動" +"行程並從事件迴圈與其通訊的辦法。最後，之前提到的 :meth:`loop." +"run_in_executor` 方法也可和 :class:`concurrent.futures.ProcessPoolExecutor` " +"搭配使用，以在另一個行程中執行程式。" + +#: ../../library/asyncio-dev.rst:124 +msgid "Running Blocking Code" +msgstr "執行阻塞的程式" + +#: ../../library/asyncio-dev.rst:126 +msgid "" +"Blocking (CPU-bound) code should not be called directly. For example, if a " +"function performs a CPU-intensive calculation for 1 second, all concurrent " +"asyncio Tasks and IO operations would be delayed by 1 second." +msgstr "" +"不應該直接呼叫阻塞（CPU 密集型）程式。例如一個執行 1 秒 CPU 密集型計算的函" +"式，那麼所有並行非同步 Tasks 和 IO 操作都會被延遲 1 秒。" + +#: ../../library/asyncio-dev.rst:131 +msgid "" +"An executor can be used to run a task in a different thread or even in a " +"different process to avoid blocking the OS thread with the event loop. See " +"the :meth:`loop.run_in_executor` method for more details." +msgstr "" +"一個 executor（執行器）可以被用來在不同的執行緒、或甚至不同的行程中執行任務，" +"以避免使用事件迴圈阻塞 OS 執行緒。詳情請見 :meth:`loop.run_in_executor` 方" +"法。" + +#: ../../library/asyncio-dev.rst:140 +msgid "Logging" +msgstr "日誌記錄" + +#: ../../library/asyncio-dev.rst:142 +msgid "" +"asyncio uses the :mod:`logging` module and all logging is performed via the " +"``\"asyncio\"`` logger." +msgstr "" +"asyncio 使用 :mod:`logging` 模組，所有日誌記錄都是透過 ``\"asyncio\"`` " +"logger 執行的。" + +#: ../../library/asyncio-dev.rst:145 +msgid "" +"The default log level is :py:data:`logging.INFO`, which can be easily " +"adjusted::" +msgstr "" +"日誌級別被預設為 :py:data:`logging.INFO`，它可以很容易地被調整：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:151 +msgid "" +"Network logging can block the event loop. It is recommended to use a " +"separate thread for handling logs or use non-blocking IO. For example, see :" +"ref:`blocking-handlers`." +msgstr "" +"網路日誌記錄可能會阻塞事件迴圈。建議使用獨立的執行緒來處理日誌或使用非阻塞 " +"IO，範例請參見 :ref:`blocking-handlers`。" + +#: ../../library/asyncio-dev.rst:159 +msgid "Detect never-awaited coroutines" +msgstr "偵測從未被等待的 (never-awaited) 協程" + +#: ../../library/asyncio-dev.rst:161 +msgid "" +"When a coroutine function is called, but not awaited (e.g. ``coro()`` " +"instead of ``await coro()``) or the coroutine is not scheduled with :meth:" +"`asyncio.create_task`, asyncio will emit a :exc:`RuntimeWarning`::" +msgstr "" +"當協程函式被呼叫而不是被等待時（即執行 ``coro()`` 而不是 ``await coro()``）或" +"者協程沒有透過 :meth:`asyncio.create_task` 被排程，asyncio 將會發出 :exc:" +"`RuntimeWarning`：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:176 ../../library/asyncio-dev.rst:221 +msgid "Output::" +msgstr "" +"輸出：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:181 ../../library/asyncio-dev.rst:237 +msgid "Output in debug mode::" +msgstr "" +"除錯模式中的輸出：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:194 +msgid "" +"The usual fix is to either await the coroutine or call the :meth:`asyncio." +"create_task` function::" +msgstr "" +"常用的修復方法是去等待協程或者呼叫 :meth:`asyncio.create_task` 函式：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:202 +msgid "Detect never-retrieved exceptions" +msgstr "偵測從未被獲取的 (never-retrieved) 例外" + +#: ../../library/asyncio-dev.rst:204 +msgid "" +"If a :meth:`Future.set_exception` is called but the Future object is never " +"awaited on, the exception would never be propagated to the user code. In " +"this case, asyncio would emit a log message when the Future object is " +"garbage collected." +msgstr "" +"如果呼叫 :meth:`Future.set_exception`，但 Future 物件從未被等待，例外將無法被" +"傳播 (propagate) 到使用者程式。在這種情況下，當 Future 物件被垃圾回收 " +"(garbage collected) 時，asyncio 將發出一則日誌訊息。" + +#: ../../library/asyncio-dev.rst:209 +msgid "Example of an unhandled exception::" +msgstr "" +"未處理例外的例子：\n" +"\n" +"::" + +#: ../../library/asyncio-dev.rst:232 +msgid "" +":ref:`Enable the debug mode ` to get the traceback where " +"the task was created::" +msgstr "" +":ref:`啟用除錯模式 `\\ 以取得任務建立處的追蹤資訊 " +"(traceback)：\n" +"\n" +"::"