# SOME DESCRIPTIVE TITLE.

# Copyright (C) 2001-2025, Python Software Foundation

# This file is distributed under the same license as the Python package.

# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

#

# Translators:

# Rafael Fontenelle <[email protected]>, 2025

# python-doc bot, 2025

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.12\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2025-09-22 19:59+0000\n"

"PO-Revision-Date: 2025-07-18 19:57+0000\n"

"Last-Translator: python-doc bot, 2025\n"

"Language-Team: Chinese (China) (https://app.transifex.com/python-doc/teams/5390/zh_CN/)\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Language: zh_CN\n"

"Plural-Forms: nplurals=1; plural=0;\n"

#: ../../library/asyncio-task.rst:6

msgid "Coroutines and Tasks"

msgstr "协程与任务"

#: ../../library/asyncio-task.rst:8

msgid ""

"This section outlines high-level asyncio APIs to work with coroutines and "

"Tasks."

msgstr "本节将简述用于协程与任务的高层级 API。"

#: ../../library/asyncio-task.rst:19 ../../library/asyncio-task.rst:148

msgid "Coroutines"

msgstr "协程"

#: ../../library/asyncio-task.rst:21

msgid "**Source code:** :source:`Lib/asyncio/coroutines.py`"

msgstr "*源码：* :source:`Lib/asyncio/coroutines.py`"

#: ../../library/asyncio-task.rst:25

msgid ""

":term:`Coroutines <coroutine>` declared with the async/await syntax is the "

"preferred way of writing asyncio applications. For example, the following "

"snippet of code prints \"hello\", waits 1 second, and then prints "

"\"world\"::"

msgstr ""

"通过 async/await 语法来声明 :term:`协程 <coroutine>` 是编写 asyncio 应用的推荐方式。 例如，以下代码段会打印"

" \"hello\"，等待 1 秒，再打印 \"world\"::"

#: ../../library/asyncio-task.rst:30

msgid ""

">>> import asyncio\n"

"\n"

">>> async def main():\n"

"... print('hello')\n"

"... await asyncio.sleep(1)\n"

"... print('world')\n"

"\n"

">>> asyncio.run(main())\n"

"hello\n"

"world"

msgstr ""

">>> import asyncio\n"

"\n"

">>> async def main():\n"

"... print('hello')\n"

"... await asyncio.sleep(1)\n"

"... print('world')\n"

"\n"

">>> asyncio.run(main())\n"

"hello\n"

"world"

#: ../../library/asyncio-task.rst:41

msgid ""

"Note that simply calling a coroutine will not schedule it to be executed::"

msgstr "注意：简单地调用一个协程并不会使其被调度执行"

#: ../../library/asyncio-task.rst:44

msgid ""

">>> main()\n"

"<coroutine object main at 0x1053bb7c8>"

msgstr ""

">>> main()\n"

"<coroutine object main at 0x1053bb7c8>"

#: ../../library/asyncio-task.rst:47

msgid ""

"To actually run a coroutine, asyncio provides the following mechanisms:"

msgstr "要实际运行一个协程，asyncio 提供了以下几种机制:"

#: ../../library/asyncio-task.rst:49

msgid ""

"The :func:`asyncio.run` function to run the top-level entry point \"main()\""

" function (see the above example.)"

msgstr ":func:`asyncio.run` 函数用来运行最高层级的入口点 \"main()\" 函数 (参见上面的示例。)"

#: ../../library/asyncio-task.rst:52

msgid ""

"Awaiting on a coroutine. The following snippet of code will print \"hello\""

" after waiting for 1 second, and then print \"world\" after waiting for "

"*another* 2 seconds::"

msgstr "对协程执行 await。以下代码段会在等待 1 秒后打印 \"hello\"，然后 *再次* 等待 2 秒后打印 \"world\"::"

#: ../../library/asyncio-task.rst:56

msgid ""

"import asyncio\n"

"import time\n"

"\n"

"async def say_after(delay, what):\n"

" await asyncio.sleep(delay)\n"

" print(what)\n"

"\n"

"async def main():\n"

" print(f\"started at {time.strftime('%X')}\")\n"

"\n"

" await say_after(1, 'hello')\n"

" await say_after(2, 'world')\n"

"\n"

" print(f\"finished at {time.strftime('%X')}\")\n"

"\n"

"asyncio.run(main())"

msgstr ""

"import asyncio\n"

"import time\n"

"\n"

"async def say_after(delay, what):\n"

" await asyncio.sleep(delay)\n"

" print(what)\n"

"\n"

"async def main():\n"

" print(f\"started at {time.strftime('%X')}\")\n"

"\n"

" await say_after(1, 'hello')\n"

" await say_after(2, 'world')\n"

"\n"

" print(f\"finished at {time.strftime('%X')}\")\n"

"\n"

"asyncio.run(main())"

#: ../../library/asyncio-task.rst:73

msgid "Expected output::"

msgstr "预期的输出::"

#: ../../library/asyncio-task.rst:75

msgid ""

"started at 17:13:52\n"

"hello\n"

"world\n"

"finished at 17:13:55"

msgstr ""

"started at 17:13:52\n"

"hello\n"

"world\n"

"finished at 17:13:55"

#: ../../library/asyncio-task.rst:80

msgid ""

"The :func:`asyncio.create_task` function to run coroutines concurrently as "

"asyncio :class:`Tasks <Task>`."

msgstr ""

":func:`asyncio.create_task` 函数用来并发运行作为 asyncio :class:`任务 <Task>` 的多个协程。"

#: ../../library/asyncio-task.rst:83

msgid ""

"Let's modify the above example and run two ``say_after`` coroutines "

"*concurrently*::"

msgstr "让我们修改以上示例，*并发* 运行两个 ``say_after`` 协程::"

#: ../../library/asyncio-task.rst:86

msgid ""

"async def main():\n"

" task1 = asyncio.create_task(\n"

" say_after(1, 'hello'))\n"

"\n"

" task2 = asyncio.create_task(\n"

" say_after(2, 'world'))\n"

"\n"

" print(f\"started at {time.strftime('%X')}\")\n"

"\n"

" # Wait until both tasks are completed (should take\n"

" # around 2 seconds.)\n"

" await task1\n"

" await task2\n"

"\n"

" print(f\"finished at {time.strftime('%X')}\")"

msgstr ""

"async def main():\n"

" task1 = asyncio.create_task(\n"

" say_after(1, 'hello'))\n"

"\n"

" task2 = asyncio.create_task(\n"

" say_after(2, 'world'))\n"

"\n"

" print(f\"started at {time.strftime('%X')}\")\n"

"\n"

" # 等待直到两个任务都完成\n"

" # （会花费约 2 秒钟。）\n"

" await task1\n"

" await task2\n"

"\n"

" print(f\"finished at {time.strftime('%X')}\")"

#: ../../library/asyncio-task.rst:102

msgid ""

"Note that expected output now shows that the snippet runs 1 second faster "

"than before::"

msgstr "注意，预期的输出显示代码段的运行时间比之前快了 1 秒::"

#: ../../library/asyncio-task.rst:105

msgid ""

"started at 17:14:32\n"

"hello\n"

"world\n"

"finished at 17:14:34"

msgstr ""

"started at 17:14:32\n"

"hello\n"

"world\n"

"finished at 17:14:34"

#: ../../library/asyncio-task.rst:110

msgid ""

"The :class:`asyncio.TaskGroup` class provides a more modern alternative to "

":func:`create_task`. Using this API, the last example becomes::"

msgstr ""

":class:`asyncio.TaskGroup` 类提供了 :func:`create_task` 的更现代化的替代。 使用此 "

"API，之前的例子将变为::"

#: ../../library/asyncio-task.rst:114

msgid ""

"async def main():\n"

" async with asyncio.TaskGroup() as tg:\n"

" task1 = tg.create_task(\n"

" say_after(1, 'hello'))\n"

"\n"

" task2 = tg.create_task(\n"

" say_after(2, 'world'))\n"

"\n"

" print(f\"started at {time.strftime('%X')}\")\n"

"\n"

" # The await is implicit when the context manager exits.\n"

"\n"

" print(f\"finished at {time.strftime('%X')}\")"

msgstr ""

"async def main():\n"

" async with asyncio.TaskGroup() as tg:\n"

" task1 = tg.create_task(\n"

" say_after(1, 'hello'))\n"

"\n"

" task2 = tg.create_task(\n"

" say_after(2, 'world'))\n"

"\n"

" print(f\"started at {time.strftime('%X')}\")\n"

"\n"

" # 当存在上下文管理器时 await 是隐式执行的。\n"

"\n"

" print(f\"finished at {time.strftime('%X')}\")"

#: ../../library/asyncio-task.rst:128

msgid "The timing and output should be the same as for the previous version."

msgstr "用时和输出结果应当与之前的版本相同。"

#: ../../library/asyncio-task.rst:130

msgid ":class:`asyncio.TaskGroup`."

msgstr ":class:`asyncio.TaskGroup`。"

#: ../../library/asyncio-task.rst:137

msgid "Awaitables"

msgstr "可等待对象"

#: ../../library/asyncio-task.rst:139

msgid ""

"We say that an object is an **awaitable** object if it can be used in an "

":keyword:`await` expression. Many asyncio APIs are designed to accept "

"awaitables."

msgstr ""

"如果一个对象可以在 :keyword:`await` 语句中使用，那么它就是 **可等待** 对象。许多 asyncio API "

"都被设计为接受可等待对象。"

#: ../../library/asyncio-task.rst:143

msgid ""

"There are three main types of *awaitable* objects: **coroutines**, "

"**Tasks**, and **Futures**."

msgstr "*可等待* 对象有三种主要类型: **协程**, **任务** 和 **Future**."

#: ../../library/asyncio-task.rst:149

msgid ""

"Python coroutines are *awaitables* and therefore can be awaited from other "

"coroutines::"

msgstr "Python 协程属于 *可等待* 对象，因此可以在其他协程中被等待::"

#: ../../library/asyncio-task.rst:152

msgid ""

"import asyncio\n"

"\n"

"async def nested():\n"

" return 42\n"

"\n"

"async def main():\n"

" # Nothing happens if we just call \"nested()\".\n"

" # A coroutine object is created but not awaited,\n"

" # so it *won't run at all*.\n"

" nested() # will raise a \"RuntimeWarning\".\n"

"\n"

" # Let's do it differently now and await it:\n"

" print(await nested()) # will print \"42\".\n"

"\n"

"asyncio.run(main())"

msgstr ""

"import asyncio\n"

"\n"

"async def nested():\n"

" return 42\n"

"\n"

"async def main():\n"

" # 如果我们只调用 \"nested()\" 则无事发生。\n"

" # 一个协程对象会被创建但是不会被等待，\n"

" # 因此它 *根本不会运行*。\n"

" nested() # 将引发 \"RuntimeWarning\"。\n"

"\n"

" # 现在让我们改为等待它：\n"

" print(await nested()) # 将打印 \"42\"。\n"

"\n"

"asyncio.run(main())"

#: ../../library/asyncio-task.rst:170

msgid ""

"In this documentation the term \"coroutine\" can be used for two closely "

"related concepts:"

msgstr "在本文档中 \"协程\" 可用来表示两个紧密关联的概念:"

#: ../../library/asyncio-task.rst:173

msgid "a *coroutine function*: an :keyword:`async def` function;"

msgstr "*协程函数*: 定义形式为 :keyword:`async def` 的函数;"

#: ../../library/asyncio-task.rst:175

msgid ""

"a *coroutine object*: an object returned by calling a *coroutine function*."

msgstr "*协程对象*: 调用 *协程函数* 所返回的对象。"

#: ../../library/asyncio-task.rst:180

msgid "Tasks"

msgstr "任务"

#: ../../library/asyncio-task.rst:181

msgid "*Tasks* are used to schedule coroutines *concurrently*."

msgstr "*任务* 被用来“并行的”调度协程"

#: ../../library/asyncio-task.rst:183

msgid ""

"When a coroutine is wrapped into a *Task* with functions like "

":func:`asyncio.create_task` the coroutine is automatically scheduled to run "

"soon::"

msgstr "当一个协程通过 :func:`asyncio.create_task` 等函数被封装为一个 *任务*，该协程会被自动调度执行::"

#: ../../library/asyncio-task.rst:187

msgid ""

"import asyncio\n"

"\n"

"async def nested():\n"

" return 42\n"

"\n"

"async def main():\n"

" # Schedule nested() to run soon concurrently\n"

" # with \"main()\".\n"

" task = asyncio.create_task(nested())\n"

"\n"

" # \"task\" can now be used to cancel \"nested()\", or\n"

" # can simply be awaited to wait until it is complete:\n"

" await task\n"

"\n"

"asyncio.run(main())"

msgstr ""

"import asyncio\n"

"\n"

"async def nested():\n"

" return 42\n"

"\n"

"async def main():\n"

" # 将 nested() 加入计划任务\n"

" # 立即与 \"main()\" 并发运行。\n"

" task = asyncio.create_task(nested())\n"

"\n"

" # 现在可以使用 \"task\" 来取消 \"nested()\"，or\n"

" # 或简单地等待它直到它被完成：\n"

" await task\n"

"\n"

"asyncio.run(main())"

#: ../../library/asyncio-task.rst:205

msgid "Futures"

msgstr "Futures"

#: ../../library/asyncio-task.rst:206

msgid ""

"A :class:`Future` is a special **low-level** awaitable object that "

"represents an **eventual result** of an asynchronous operation."

msgstr ":class:`Future` 是一种特殊的 **低层级** 可等待对象，表示一个异步操作的 **最终结果**。"

#: ../../library/asyncio-task.rst:209

msgid ""

"When a Future object is *awaited* it means that the coroutine will wait "

"until the Future is resolved in some other place."

msgstr "当一个 Future 对象 *被等待*，这意味着协程将保持等待直到该 Future 对象在其他地方操作完毕。"

#: ../../library/asyncio-task.rst:212

msgid ""

"Future objects in asyncio are needed to allow callback-based code to be used"

" with async/await."

msgstr "在 asyncio 中需要 Future 对象以便允许通过 async/await 使用基于回调的代码。"

#: ../../library/asyncio-task.rst:215

msgid ""

"Normally **there is no need** to create Future objects at the application "

"level code."

msgstr "通常情况下 **没有必要** 在应用层级的代码中创建 Future 对象。"

#: ../../library/asyncio-task.rst:218

msgid ""

"Future objects, sometimes exposed by libraries and some asyncio APIs, can be"

" awaited::"

msgstr "Future 对象有时会由库和某些 asyncio API 暴露给用户，用作可等待对象::"

#: ../../library/asyncio-task.rst:221

msgid ""

"async def main():\n"

" await function_that_returns_a_future_object()\n"

"\n"

" # this is also valid:\n"

" await asyncio.gather(\n"

" function_that_returns_a_future_object(),\n"

" some_python_coroutine()\n"

" )"

msgstr ""

"async def main():\n"

" await function_that_returns_a_future_object()\n"

"\n"

" # 这样也可以：\n"

" await asyncio.gather(\n"

" function_that_returns_a_future_object(),\n"

" some_python_coroutine()\n"

" )"

#: ../../library/asyncio-task.rst:230

msgid ""

"A good example of a low-level function that returns a Future object is "

":meth:`loop.run_in_executor`."

msgstr "一个很好的返回对象的低层级函数的示例是 :meth:`loop.run_in_executor`。"

#: ../../library/asyncio-task.rst:235

msgid "Creating Tasks"

msgstr "创建任务"

#: ../../library/asyncio-task.rst:237

msgid "**Source code:** :source:`Lib/asyncio/tasks.py`"

msgstr "**源码：** :source:`Lib/asyncio/tasks.py`"

#: ../../library/asyncio-task.rst:243

msgid ""

"Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task` and "

"schedule its execution. Return the Task object."

msgstr "将 *coro* :ref:`协程 <coroutine>` 封装为一个 :class:`Task` 并调度其执行。返回 Task 对象。"

#: ../../library/asyncio-task.rst:246

msgid ""

"If *name* is not ``None``, it is set as the name of the task using "

":meth:`Task.set_name`."

msgstr "*name* 不为 ``None``，它将使用 :meth:`Task.set_name` 来设为任务的名称。"

#: ../../library/asyncio-task.rst:249

msgid ""

"An optional keyword-only *context* argument allows specifying a custom "

":class:`contextvars.Context` for the *coro* to run in. The current context "

"copy is created when no *context* is provided."

msgstr ""

"可选的 *context* 参数允许指定自定义的 :class:`contextvars.Context` 供 *coro* 运行。 当未提供 "

"*context* 时将创建当前上下文的副本。"

#: ../../library/asyncio-task.rst:253

msgid ""

"The task is executed in the loop returned by :func:`get_running_loop`, "

":exc:`RuntimeError` is raised if there is no running loop in current thread."

msgstr ""

"该任务会在 :func:`get_running_loop` 返回的循环中执行，如果当前线程没有在运行的循环则会引发 "

":exc:`RuntimeError`。"

#: ../../library/asyncio-task.rst:259

msgid ""

":meth:`asyncio.TaskGroup.create_task` is a new alternative leveraging "

"structural concurrency; it allows for waiting for a group of related tasks "

"with strong safety guarantees."

msgstr ""

":meth:`asyncio.TaskGroup.create_task` 是一个平衡了结构化并发的新选择；它允许等待一组相关任务并具有极强的安全保证。"

#: ../../library/asyncio-task.rst:265

msgid ""

"Save a reference to the result of this function, to avoid a task "

"disappearing mid-execution. The event loop only keeps weak references to "

"tasks. A task that isn't referenced elsewhere may get garbage collected at "

"any time, even before it's done. For reliable \"fire-and-forget\" background"

" tasks, gather them in a collection::"

msgstr ""

"保存一个指向此函数的结果的引用，以避免任务在执行过程中消失。 事件循环将只保留对任务的弱引用。 "

"未在其他地方被引用的任务可能在任何时候被作为垃圾回收，即使是在它被完成之前。 如果需要可靠的“发射后不用管”后台任务，请将它们放到一个多项集中::"

#: ../../library/asyncio-task.rst:272

msgid ""

"background_tasks = set()\n"

"\n"

"for i in range(10):\n"

" task = asyncio.create_task(some_coro(param=i))\n"

"\n"

" # Add task to the set. This creates a strong reference.\n"

" background_tasks.add(task)\n"

"\n"

" # To prevent keeping references to finished tasks forever,\n"

" # make each task remove its own reference from the set after\n"

" # completion:\n"

" task.add_done_callback(background_tasks.discard)"

msgstr ""

"background_tasks = set()\n"

"\n"

"for i in range(10):\n"

" task = asyncio.create_task(some_coro(param=i))\n"

"\n"

" # 将任务加入集合。 这将创建一个强引用。\n"

" background_tasks.add(task)\n"

"\n"

" # 为避免永远保留对已结束任务的引用，\n"

" # 让每个任务在完成后将对自己的引用\n"

" # 移出集合：\n"

" task.add_done_callback(background_tasks.discard)"

#: ../../library/asyncio-task.rst:287 ../../library/asyncio-task.rst:1126

msgid "Added the *name* parameter."

msgstr "增加了 *name* 形参。"

#: ../../library/asyncio-task.rst:290 ../../library/asyncio-task.rst:1133

msgid "Added the *context* parameter."

msgstr "增加了 *context* 形参。"

#: ../../library/asyncio-task.rst:295

msgid "Task Cancellation"

msgstr "任务取消"

#: ../../library/asyncio-task.rst:297

msgid ""

"Tasks can easily and safely be cancelled. When a task is cancelled, "

":exc:`asyncio.CancelledError` will be raised in the task at the next "

"opportunity."

msgstr "任务可以便捷和安全地取消。 当任务被取消时，:exc:`asyncio.CancelledError` 将在遇到机会时在任务中被引发。"

#: ../../library/asyncio-task.rst:301

msgid ""

"It is recommended that coroutines use ``try/finally`` blocks to robustly "

"perform clean-up logic. In case :exc:`asyncio.CancelledError` is explicitly "

"caught, it should generally be propagated when clean-up is complete. "

":exc:`asyncio.CancelledError` directly subclasses :exc:`BaseException` so "

"most code will not need to be aware of it."

msgstr ""

"推荐协程使用 ``try/finally`` 代码块来可靠地执行清理逻辑。 对于 :exc:`asyncio.CancelledError` "

"被显式捕获的情况，它通常应当在清理完成时被传播。 :exc:`asyncio.CancelledError` 会直接子类化 "

":exc:`BaseException` 因此大多数代码都不需要关心这一点。"

#: ../../library/asyncio-task.rst:307

msgid ""

"The asyncio components that enable structured concurrency, like "

":class:`asyncio.TaskGroup` and :func:`asyncio.timeout`, are implemented "

"using cancellation internally and might misbehave if a coroutine swallows "

":exc:`asyncio.CancelledError`. Similarly, user code should not generally "

"call :meth:`uncancel <asyncio.Task.uncancel>`. However, in cases when "

"suppressing :exc:`asyncio.CancelledError` is truly desired, it is necessary "

"to also call ``uncancel()`` to completely remove the cancellation state."

msgstr ""

"启用结构化并发的 asyncio 组件，如 :class:`asyncio.TaskGroup` 和 "

":func:`asyncio.timeout`，在内部是使用撤销操作来实现的因而在协程屏蔽了 :exc:`asyncio.CancelledError`"

" 时可能无法正常工作。 类似地，用户代码通常也不应调用 :meth:`uncancel <asyncio.Task.uncancel>`。 "

"但是，在确实想要屏蔽 :exc:`asyncio.CancelledError` 的情况下，则还有必要调用 ``uncancel()`` "

"来完全移除撤销状态。"

#: ../../library/asyncio-task.rst:319

msgid "Task Groups"

msgstr "任务组"

#: ../../library/asyncio-task.rst:321

msgid ""

"Task groups combine a task creation API with a convenient and reliable way "

"to wait for all tasks in the group to finish."

msgstr "任务组合并了一套用于等待分组中所有任务完成的方便可靠方式的任务创建 API。"

#: ../../library/asyncio-task.rst:326

msgid ""

"An :ref:`asynchronous context manager <async-context-managers>` holding a "

"group of tasks. Tasks can be added to the group using :meth:`create_task`. "

"All tasks are awaited when the context manager exits."

msgstr ""

"持有一个任务分组的 :ref:`异步上下文管理器 <async-context-managers>`。 可以使用 :meth:`create_task`"

" 将任务添加到分组中。 当该上下文管理器退出时所有任务都将被等待。"

#: ../../library/asyncio-task.rst:335

msgid ""

"Create a task in this task group. The signature matches that of "

":func:`asyncio.create_task`."

msgstr "在该任务组中创建一个任务。 其签名与 :func:`asyncio.create_task` 的相匹配。"

#: ../../library/asyncio-task.rst:338 ../../library/asyncio-task.rst:520

#: ../../library/asyncio-task.rst:693 ../../library/asyncio-task.rst:751

#: ../../library/asyncio-task.rst:777 ../../library/asyncio-task.rst:818

#: ../../library/asyncio-task.rst:918

msgid "Example::"

msgstr "示例::"

#: ../../library/asyncio-task.rst:340

msgid ""

"async def main():\n"

" async with asyncio.TaskGroup() as tg:\n"

" task1 = tg.create_task(some_coro(...))\n"

" task2 = tg.create_task(another_coro(...))\n"

" print(f\"Both tasks have completed now: {task1.result()}, {task2.result()}\")"

msgstr ""

"async def main():\n"

" async with asyncio.TaskGroup() as tg:\n"

" task1 = tg.create_task(some_coro(...))\n"

" task2 = tg.create_task(another_coro(...))\n"

" print(f\"Both tasks have completed now: {task1.result()}, {task2.result()}\")"

#: ../../library/asyncio-task.rst:346

msgid ""

"The ``async with`` statement will wait for all tasks in the group to finish."

" While waiting, new tasks may still be added to the group (for example, by "

"passing ``tg`` into one of the coroutines and calling ``tg.create_task()`` "

"in that coroutine). Once the last task has finished and the ``async with`` "

"block is exited, no new tasks may be added to the group."

msgstr ""

"``async with`` 语句将等待分组中的所有任务结束。 在等待期间，仍可将新任务添加到分组中 (例如，通过将 ``tg`` "

"传入某个协程并在该协程中调用 ``tg.create_task()``)。 一旦最后的任务完成并退出 ``async with`` "

"代码块，将无法再向分组添加新任务。"

#: ../../library/asyncio-task.rst:353

msgid ""

"The first time any of the tasks belonging to the group fails with an "

"exception other than :exc:`asyncio.CancelledError`, the remaining tasks in "

"the group are cancelled. No further tasks can then be added to the group. At"

" this point, if the body of the ``async with`` statement is still active "

"(i.e., :meth:`~object.__aexit__` hasn't been called yet), the task directly "

"containing the ``async with`` statement is also cancelled. The resulting "

":exc:`asyncio.CancelledError` will interrupt an ``await``, but it will not "

"bubble out of the containing ``async with`` statement."

msgstr ""

"当首次有任何属于分组的任务因 :exc:`asyncio.CancelledError` 以外的异常而失败时，分组中的剩余任务将被取消。 "

"在此之后将无法添加更多任务到该分组中。 在这种情况下，如果 ``async with`` 语句体仍然为激活状态（即 "

":meth:`~object.__aexit__` 尚未被调用），则直接包含 ``async with`` 语句的任务也会被取消。 结果 "

":exc:`asyncio.CancelledError` 将中断一个 ``await``，但它将不会跳出包含的 ``async with`` 语句。"

#: ../../library/asyncio-task.rst:363

msgid ""

"Once all tasks have finished, if any tasks have failed with an exception "

"other than :exc:`asyncio.CancelledError`, those exceptions are combined in "

"an :exc:`ExceptionGroup` or :exc:`BaseExceptionGroup` (as appropriate; see "

"their documentation) which is then raised."

msgstr ""

"一旦所有任务被完成，如果有任何任务因 :exc:`asyncio.CancelledError` 以外的异常而失败，这些异常会被组合在 "

":exc:`ExceptionGroup` 或 :exc:`BaseExceptionGroup` 中（选择其中较适合的一个；参见其文档）并将随后引发。"

#: ../../library/asyncio-task.rst:370

msgid ""

"Two base exceptions are treated specially: If any task fails with "

":exc:`KeyboardInterrupt` or :exc:`SystemExit`, the task group still cancels "

"the remaining tasks and waits for them, but then the initial "

":exc:`KeyboardInterrupt` or :exc:`SystemExit` is re-raised instead of "

":exc:`ExceptionGroup` or :exc:`BaseExceptionGroup`."

msgstr ""

"两个基础异常会被特别对待：如果有任何任务因 :exc:`KeyboardInterrupt` 或 :exc:`SystemExit` "

"而失败，任务分组仍然会取消剩余的任务并等待它们，但随后初始 :exc:`KeyboardInterrupt` 或 :exc:`SystemExit` "

"而不是 :exc:`ExceptionGroup` 或 :exc:`BaseExceptionGroup` 会被重新引发。"

#: ../../library/asyncio-task.rst:376

msgid ""

"If the body of the ``async with`` statement exits with an exception (so "

":meth:`~object.__aexit__` is called with an exception set), this is treated "

"the same as if one of the tasks failed: the remaining tasks are cancelled "

"and then waited for, and non-cancellation exceptions are grouped into an "

"exception group and raised. The exception passed into "

":meth:`~object.__aexit__`, unless it is :exc:`asyncio.CancelledError`, is "

"also included in the exception group. The same special case is made for "

":exc:`KeyboardInterrupt` and :exc:`SystemExit` as in the previous paragraph."

msgstr ""

"如果 ``async with`` 语句体因异常而退出（这样将调用 :meth:`~object.__aexit__` "

"并附带一个异常），此种情况会与有任务失败时一样对待：剩余任务将被取消然后被等待，而非取消类异常会被加入到一个异常分组并被引发。 传入到 "

":meth:`~object.__aexit__` 的异常，除了 :exc:`asyncio.CancelledError` "

"以外，也都会被包括在该异常分组中。 同样的特殊对待也适用于上一段所说的 :exc:`KeyboardInterrupt` 和 "

":exc:`SystemExit`。"

#: ../../library/asyncio-task.rst:390

msgid "Terminating a Task Group"

msgstr "终结一个任务组"

#: ../../library/asyncio-task.rst:392

msgid ""

"While terminating a task group is not natively supported by the standard "

"library, termination can be achieved by adding an exception-raising task to "

"the task group and ignoring the raised exception:"

msgstr "虽然标准库没有对终结任务组的原生支持，但可通过向任务组添加一个引发异常的任务并无视被引发的异常来达成终结效果："

#: ../../library/asyncio-task.rst:396

msgid ""

"import asyncio\n"

"from asyncio import TaskGroup\n"

"\n"

"class TerminateTaskGroup(Exception):\n"

" \"\"\"Exception raised to terminate a task group.\"\"\"\n"

"\n"

"async def force_terminate_task_group():\n"

" \"\"\"Used to force termination of a task group.\"\"\"\n"

" raise TerminateTaskGroup()\n"

"\n"

"async def job(task_id, sleep_time):\n"

" print(f'Task {task_id}: start')\n"

" await asyncio.sleep(sleep_time)\n"

" print(f'Task {task_id}: done')\n"

"\n"

"async def main():\n"

" try:\n"

" async with TaskGroup() as group:\n"

" # spawn some tasks\n"

" group.create_task(job(1, 0.5))\n"

" group.create_task(job(2, 1.5))\n"

" # sleep for 1 second\n"

" await asyncio.sleep(1)\n"

" # add an exception-raising task to force the group to terminate\n"

" group.create_task(force_terminate_task_group())\n"

" except* TerminateTaskGroup:\n"

" pass\n"

"\n"

"asyncio.run(main())"

msgstr ""

"import asyncio\n"

"from asyncio import TaskGroup\n"

"\n"

"class TerminateTaskGroup(Exception):\n"

" \"\"\"Exception raised to terminate a task group.\"\"\"\n"

"\n"

"async def force_terminate_task_group():\n"

" \"\"\"Used to force termination of a task group.\"\"\"\n"

" raise TerminateTaskGroup()\n"

"\n"

"async def job(task_id, sleep_time):\n"

" print(f'Task {task_id}: start')\n"

" await asyncio.sleep(sleep_time)\n"

" print(f'Task {task_id}: done')\n"

"\n"

"async def main():\n"

" try:\n"

" async with TaskGroup() as group:\n"

" # 创建一些任务\n"

" group.create_task(job(1, 0.5))\n"

" group.create_task(job(2, 1.5))\n"

" # 休眠 1 秒\n"

" await asyncio.sleep(1)\n"

" # 添加一个引发异常的任务以强制终结分组\n"

" group.create_task(force_terminate_task_group())\n"

" except* TerminateTaskGroup:\n"

" pass\n"

"\n"

"asyncio.run(main())"

#: ../../library/asyncio-task.rst:428

msgid "Expected output:"

msgstr "期待的输出:"

#: ../../library/asyncio-task.rst:430

msgid ""

"Task 1: start\n"

"Task 2: start\n"

"Task 1: done"

msgstr ""

"Task 1: start\n"

"Task 2: start\n"

"Task 1: done"

#: ../../library/asyncio-task.rst:437

msgid "Sleeping"

msgstr "休眠"

#: ../../library/asyncio-task.rst:442

msgid "Block for *delay* seconds."

msgstr "阻塞 *delay* 指定的秒数。"

#: ../../library/asyncio-task.rst:444

msgid ""

"If *result* is provided, it is returned to the caller when the coroutine "

"completes."

msgstr "如果指定了 *result*，则当协程完成时将其返回给调用者。"

#: ../../library/asyncio-task.rst:447

msgid ""

"``sleep()`` always suspends the current task, allowing other tasks to run."

msgstr "``sleep()`` 总是会挂起当前任务，以允许其他任务运行。"

#: ../../library/asyncio-task.rst:450

msgid ""

"Setting the delay to 0 provides an optimized path to allow other tasks to "

"run. This can be used by long-running functions to avoid blocking the event "

"loop for the full duration of the function call."

msgstr "将 delay 设为 0 将提供一个经优化的路径以允许其他任务运行。 这可供长期间运行的函数使用以避免在函数调用的全过程中阻塞事件循环。"

#: ../../library/asyncio-task.rst:456

msgid ""

"Example of coroutine displaying the current date every second for 5 "

"seconds::"

msgstr "以下协程示例运行 5 秒，每秒显示一次当前日期::"

#: ../../library/asyncio-task.rst:459

msgid ""

"import asyncio\n"

"import datetime\n"

"\n"

"async def display_date():\n"

" loop = asyncio.get_running_loop()\n"

" end_time = loop.time() + 5.0\n"

" while True:\n"

" print(datetime.datetime.now())\n"

" if (loop.time() + 1.0) >= end_time:\n"

" break\n"

" await asyncio.sleep(1)\n"

"\n"

"asyncio.run(display_date())"

msgstr ""

"import asyncio\n"

"import datetime\n"

"\n"

"async def display_date():\n"

" loop = asyncio.get_running_loop()\n"

" end_time = loop.time() + 5.0\n"

" while True:\n"

" print(datetime.datetime.now())\n"

" if (loop.time() + 1.0) >= end_time:\n"

" break\n"

" await asyncio.sleep(1)\n"

"\n"

"asyncio.run(display_date())"

#: ../../library/asyncio-task.rst:474 ../../library/asyncio-task.rst:569

#: ../../library/asyncio-task.rst:668 ../../library/asyncio-task.rst:843

#: ../../library/asyncio-task.rst:898 ../../library/asyncio-task.rst:924

msgid "Removed the *loop* parameter."

msgstr "移除了 *loop* 形参。"

#: ../../library/asyncio-task.rst:479

msgid "Running Tasks Concurrently"

msgstr "并发运行任务"

#: ../../library/asyncio-task.rst:483

msgid ""

"Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws* sequence "

"*concurrently*."

msgstr "*并发* 运行 *aws* 序列中的 :ref:`可等待对象 <asyncio-awaitables>`。"

#: ../../library/asyncio-task.rst:486

msgid ""

"If any awaitable in *aws* is a coroutine, it is automatically scheduled as a"

" Task."

msgstr "如果 *aws* 中的某个可等待对象为协程，它将自动被作为一个任务调度。"

#: ../../library/asyncio-task.rst:489

msgid ""

"If all awaitables are completed successfully, the result is an aggregate "

"list of returned values. The order of result values corresponds to the "

"order of awaitables in *aws*."

msgstr "如果所有可等待对象都成功完成，结果将是一个由所有返回值聚合而成的列表。结果值的顺序与 *aws* 中可等待对象的顺序一致。"

#: ../../library/asyncio-task.rst:493

msgid ""

"If *return_exceptions* is ``False`` (default), the first raised exception is"

" immediately propagated to the task that awaits on ``gather()``. Other "

"awaitables in the *aws* sequence **won't be cancelled** and will continue to"

" run."

msgstr ""

"如果 *return_exceptions* 为 ``False`` (默认)，所引发的首个异常会立即传播给等待 ``gather()`` "

"的任务。*aws* 序列中的其他可等待对象 **不会被取消** 并将继续运行。"

#: ../../library/asyncio-task.rst:498

msgid ""

"If *return_exceptions* is ``True``, exceptions are treated the same as "

"successful results, and aggregated in the result list."

msgstr "如果 *return_exceptions* 为 ``True``，异常会和成功的结果一样处理，并聚合至结果列表。"

#: ../../library/asyncio-task.rst:501

msgid ""

"If ``gather()`` is *cancelled*, all submitted awaitables (that have not "

"completed yet) are also *cancelled*."

msgstr "如果 ``gather()`` *被取消*，所有被提交 (尚未完成) 的可等待对象也会 *被取消*。"

#: ../../library/asyncio-task.rst:504

msgid ""

"If any Task or Future from the *aws* sequence is *cancelled*, it is treated "

"as if it raised :exc:`CancelledError` -- the ``gather()`` call is **not** "

"cancelled in this case. This is to prevent the cancellation of one "

"submitted Task/Future to cause other Tasks/Futures to be cancelled."

msgstr ""

"如果 *aws* 序列中的任一 Task 或 Future 对象 *被取消*，它将被当作引发了 :exc:`CancelledError` 一样处理 "

"-- 在此情况下 ``gather()`` 调用 **不会** 被取消。这是为了防止一个已提交的 Task/Future 被取消导致其他 "

"Tasks/Future 也被取消。"

#: ../../library/asyncio-task.rst:511

msgid ""

"A new alternative to create and run tasks concurrently and wait for their "

"completion is :class:`asyncio.TaskGroup`. *TaskGroup* provides stronger "

"safety guarantees than *gather* for scheduling a nesting of subtasks: if a "

"task (or a subtask, a task scheduled by a task) raises an exception, "

"*TaskGroup* will, while *gather* will not, cancel the remaining scheduled "

"tasks)."

msgstr ""

"一个创建然后并发地运行任务等待它们完成的新选择是 :class:`asyncio.TaskGroup`。 *TaskGroup* "

"提供了针对调度嵌套子任务的比 *gather* 更强的安全保证：如果一个任务（或子任务，即由一个任务调度的任务）引发了异常，*TaskGroup* "

"将取消剩余的已排期任务）。"

#: ../../library/asyncio-task.rst:522

msgid ""

"import asyncio\n"

"\n"

"async def factorial(name, number):\n"

" f = 1\n"

" for i in range(2, number + 1):\n"

" print(f\"Task {name}: Compute factorial({number}), currently i={i}...\")\n"

" await asyncio.sleep(1)\n"

" f *= i\n"

" print(f\"Task {name}: factorial({number}) = {f}\")\n"

" return f\n"

"\n"

"async def main():\n"

" # Schedule three calls *concurrently*:\n"

" L = await asyncio.gather(\n"

" factorial(\"A\", 2),\n"

" factorial(\"B\", 3),\n"

" factorial(\"C\", 4),\n"

" )\n"

" print(L)\n"

"\n"

"asyncio.run(main())\n"

"\n"

"# Expected output:\n"

"#\n"

"# Task A: Compute factorial(2), currently i=2...\n"

"# Task B: Compute factorial(3), currently i=2...\n"

"# Task C: Compute factorial(4), currently i=2...\n"

"# Task A: factorial(2) = 2\n"

"# Task B: Compute factorial(3), currently i=3...\n"

"# Task C: Compute factorial(4), currently i=3...\n"

"# Task B: factorial(3) = 6\n"

"# Task C: Compute factorial(4), currently i=4...\n"

"# Task C: factorial(4) = 24\n"

"# [2, 6, 24]"

msgstr ""

"import asyncio\n"

"\n"

"async def factorial(name, number):\n"

" f = 1\n"

" for i in range(2, number + 1):\n"

" print(f\"Task {name}: Compute factorial({number}), currently i={i}...\")\n"

" await asyncio.sleep(1)\n"

" f *= i\n"

" print(f\"Task {name}: factorial({number}) = {f}\")\n"

" return f\n"

"\n"

"async def main():\n"

" # 将三个调用 *并发地* 加入计划任务：\n"

" L = await asyncio.gather(\n"

" factorial(\"A\", 2),\n"

" factorial(\"B\", 3),\n"

" factorial(\"C\", 4),\n"

" )\n"

" print(L)\n"

"\n"

"asyncio.run(main())\n"

"\n"

"# 预期的输出：\n"

"#\n"

"# Task A: Compute factorial(2), currently i=2...\n"

"# Task B: Compute factorial(3), currently i=2...\n"

"# Task C: Compute factorial(4), currently i=2...\n"

"# Task A: factorial(2) = 2\n"

"# Task B: Compute factorial(3), currently i=3...\n"

"# Task C: Compute factorial(4), currently i=3...\n"

"# Task B: factorial(3) = 6\n"

"# Task C: Compute factorial(4), currently i=4...\n"

"# Task C: factorial(4) = 24\n"

"# [2, 6, 24]"

#: ../../library/asyncio-task.rst:558

msgid ""

"If *return_exceptions* is false, cancelling gather() after it has been "

"marked done won't cancel any submitted awaitables. For instance, gather can "

"be marked done after propagating an exception to the caller, therefore, "

"calling ``gather.cancel()`` after catching an exception (raised by one of "

"the awaitables) from gather won't cancel any other awaitables."