asyncio-dev.po

# Copyright (C) 2001-2024, Python Software Foundation
# This file is distributed under the same license as the Python package.
#
# Translators:
# Adrian Liaw <adrianliaw2000@gmail.com>, 2018
# Matt Wang <mattwang44gmail.com>, 2022
msgid ""
msgstr ""
"Project-Id-Version: Python 3.13\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-09-03 11:11+0800\n"
"PO-Revision-Date: 2023-02-18 14:17+0800\n"
"Last-Translator: Matt Wang <mattwang44gmail.com>\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 <devmode>`."
msgstr "使用 :ref:`Python 開發模式 (Development Mode) <devmode>`。"

#: ../../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 <asyncio-logger>` to :py:"
"const:`logging.DEBUG`, for example the following snippet of code can be run "
"at startup of the application::"
msgstr ""
"將 :ref:`asyncio logger（日誌記錄器） <asyncio-logger>`\\ 的日誌級别設置為 :"
"py:const:`logging.DEBUG`，例如下面的程式片段可以在應用程式啟動時運行： ::"

#: ../../library/asyncio-dev.rst:40
msgid "logging.basicConfig(level=logging.DEBUG)"
msgstr "logging.basicConfig(level=logging.DEBUG)"

#: ../../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 <asyncio-coroutine-"
"not-scheduled>` and logs them; this mitigates the \"forgotten await\" "
"pitfall."
msgstr ""
"asyncio 會檢查\\ :ref:`未被等待的協程 <asyncio-coroutine-not-scheduled>`\\ 並"
"記錄他們；這會減輕\"被遺忘的等待 (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` 方法。例如： ::"

#: ../../library/asyncio-dev.rst:79
msgid "loop.call_soon_threadsafe(callback, *args)"
msgstr "loop.call_soon_threadsafe(callback, *args)"

#: ../../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` 方法，例如： ::"

#: ../../library/asyncio-dev.rst:87
msgid "loop.call_soon_threadsafe(fut.cancel)"
msgstr "loop.call_soon_threadsafe(fut.cancel)"

#: ../../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` 以存取結果： ::"

#: ../../library/asyncio-dev.rst:93
msgid ""
"async def coro_func():\n"
"     return await asyncio.sleep(1, 42)\n"
"\n"
"# Later in another OS thread:\n"
"\n"
"future = asyncio.run_coroutine_threadsafe(coro_func(), loop)\n"
"# Wait for the result:\n"
"result = future.result()"
msgstr ""

#: ../../library/asyncio-dev.rst:102
msgid "To handle signals 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 <asyncio-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:`子行程 <asyncio-subprocess>` 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:const:`logging.INFO`, which can be easily "
"adjusted::"
msgstr "日誌級別被預設為 :py:const:`logging.INFO`，它可以很容易地被調整： ::"

#: ../../library/asyncio-dev.rst:148
msgid "logging.getLogger(\"asyncio\").setLevel(logging.WARNING)"
msgstr "logging.getLogger(\"asyncio\").setLevel(logging.WARNING)"

#: ../../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`： ::"

#: ../../library/asyncio-dev.rst:166
msgid ""
"import asyncio\n"
"\n"
"async def test():\n"
"    print(\"never scheduled\")\n"
"\n"
"async def main():\n"
"    test()\n"
"\n"
"asyncio.run(main())"
msgstr ""

#: ../../library/asyncio-dev.rst:176 ../../library/asyncio-dev.rst:221
msgid "Output::"
msgstr "輸出： ::"

#: ../../library/asyncio-dev.rst:178
msgid ""
"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n"
"  test()"
msgstr ""
"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n"
"  test()"

#: ../../library/asyncio-dev.rst:181 ../../library/asyncio-dev.rst:237
msgid "Output in debug mode::"
msgstr "除錯模式中的輸出： ::"

#: ../../library/asyncio-dev.rst:183
msgid ""
"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n"
"Coroutine created at (most recent call last)\n"
"  File \"../t.py\", line 9, in <module>\n"
"    asyncio.run(main(), debug=True)\n"
"\n"
"  < .. >\n"
"\n"
"  File \"../t.py\", line 7, in main\n"
"    test()\n"
"  test()"
msgstr ""
"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n"
"Coroutine created at (most recent call last)\n"
"  File \"../t.py\", line 9, in <module>\n"
"    asyncio.run(main(), debug=True)\n"
"\n"
"  < .. >\n"
"\n"
"  File \"../t.py\", line 7, in main\n"
"    test()\n"
"  test()"

#: ../../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` 函式： ::"

#: ../../library/asyncio-dev.rst:197
msgid ""
"async def main():\n"
"    await test()"
msgstr ""
"async def main():\n"
"    await test()"

#: ../../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 "未處理例外的例子： ::"

#: ../../library/asyncio-dev.rst:211
msgid ""
"import asyncio\n"
"\n"
"async def bug():\n"
"    raise Exception(\"not consumed\")\n"
"\n"
"async def main():\n"
"    asyncio.create_task(bug())\n"
"\n"
"asyncio.run(main())"
msgstr ""
"import asyncio\n"
"\n"
"async def bug():\n"
"    raise Exception(\"not consumed\")\n"
"\n"
"async def main():\n"
"    asyncio.create_task(bug())\n"
"\n"
"asyncio.run(main())"

#: ../../library/asyncio-dev.rst:223
msgid ""
"Task exception was never retrieved\n"
"future: <Task finished coro=<bug() done, defined at test.py:3>\n"
"  exception=Exception('not consumed')>\n"
"\n"
"Traceback (most recent call last):\n"
"  File \"test.py\", line 4, in bug\n"
"    raise Exception(\"not consumed\")\n"
"Exception: not consumed"
msgstr ""
"Task exception was never retrieved\n"
"future: <Task finished coro=<bug() done, defined at test.py:3>\n"
"  exception=Exception('not consumed')>\n"
"\n"
"Traceback (most recent call last):\n"
"  File \"test.py\", line 4, in bug\n"
"    raise Exception(\"not consumed\")\n"
"Exception: not consumed"

#: ../../library/asyncio-dev.rst:232
msgid ""
":ref:`Enable the debug mode <asyncio-debug-mode>` to get the traceback where "
"the task was created::"
msgstr ""
":ref:`啟用除錯模式 <asyncio-debug-mode>`\\ 以取得任務建立處的追蹤資訊 "
"(traceback)： ::"

#: ../../library/asyncio-dev.rst:235
msgid "asyncio.run(main(), debug=True)"
msgstr "asyncio.run(main(), debug=True)"

#: ../../library/asyncio-dev.rst:239
msgid ""
"Task exception was never retrieved\n"
"future: <Task finished coro=<bug() done, defined at test.py:3>\n"
"    exception=Exception('not consumed') created at asyncio/tasks.py:321>\n"
"\n"
"source_traceback: Object created at (most recent call last):\n"
"  File \"../t.py\", line 9, in <module>\n"
"    asyncio.run(main(), debug=True)\n"
"\n"
"< .. >\n"
"\n"
"Traceback (most recent call last):\n"
"  File \"../t.py\", line 4, in bug\n"
"    raise Exception(\"not consumed\")\n"
"Exception: not consumed"
msgstr ""
"Task exception was never retrieved\n"
"future: <Task finished coro=<bug() done, defined at test.py:3>\n"
"    exception=Exception('not consumed') created at asyncio/tasks.py:321>\n"
"\n"
"source_traceback: Object created at (most recent call last):\n"
"  File \"../t.py\", line 9, in <module>\n"
"    asyncio.run(main(), debug=True)\n"
"\n"
"< .. >\n"
"\n"
"Traceback (most recent call last):\n"
"  File \"../t.py\", line 4, in bug\n"
"    raise Exception(\"not consumed\")\n"
"Exception: not consumed"