Deploy preview for PR 1214 🛫

Author: pydoc-zh-tw[bot]

pr-preview/pr-1214/_sources/howto/enum.rst.txt

@@ -105,8 +105,8 @@ The complete :class:`!Weekday` enum now looks like this::
 
 Now we can find out what today is!  Observe::
 
-    >>> from datetime import date
-    >>> Weekday.from_date(date.today())     # doctest: +SKIP
+    >>> import datetime as dt
+    >>> Weekday.from_date(dt.date.today())     # doctest: +SKIP
     <Weekday.TUESDAY: 2>
 
 Of course, if you're reading this on some other day, you'll see that day instead.
@@ -1538,8 +1538,8 @@ TimePeriod
 
 An example to show the :attr:`~Enum._ignore_` attribute in use::
 
-    >>> from datetime import timedelta
-    >>> class Period(timedelta, Enum):
+    >>> import datetime as dt
+    >>> class Period(dt.timedelta, Enum):
     ...     "different lengths of time"
     ...     _ignore_ = 'Period i'
     ...     Period = vars()

pr-preview/pr-1214/_sources/howto/logging-cookbook.rst.txt

@@ -1549,10 +1549,10 @@ to this (remembering to first import :mod:`concurrent.futures`)::
         for i in range(10):
             executor.submit(worker_process, queue, worker_configurer)
 
-Deploying Web applications using Gunicorn and uWSGI
+Deploying web applications using Gunicorn and uWSGI
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-When deploying Web applications using `Gunicorn <https://gunicorn.org/>`_ or `uWSGI
+When deploying web applications using `Gunicorn <https://gunicorn.org/>`_ or `uWSGI
 <https://uwsgi-docs.readthedocs.io/en/latest/>`_ (or similar), multiple worker
 processes are created to handle client requests. In such environments, avoid creating
 file-based handlers directly in your web application. Instead, use a
@@ -3619,7 +3619,6 @@ detailed information.
 
 .. code-block:: python3
 
-    import datetime
     import logging
     import random
     import sys
@@ -3854,15 +3853,15 @@ Logging to syslog with RFC5424 support
 Although :rfc:`5424` dates from 2009, most syslog servers are configured by default to
 use the older :rfc:`3164`, which hails from 2001. When ``logging`` was added to Python
 in 2003, it supported the earlier (and only existing) protocol at the time. Since
-RFC5424 came out, as there has not been widespread deployment of it in syslog
+RFC 5424 came out, as there has not been widespread deployment of it in syslog
 servers, the :class:`~logging.handlers.SysLogHandler` functionality has not been
 updated.
 
 RFC 5424 contains some useful features such as support for structured data, and if you
 need to be able to log to a syslog server with support for it, you can do so with a
 subclassed handler which looks something like this::
 
-    import datetime
+    import datetime as dt
     import logging.handlers
     import re
     import socket
@@ -3880,7 +3879,7 @@ subclassed handler which looks something like this::
 
         def format(self, record):
             version = 1
-            asctime = datetime.datetime.fromtimestamp(record.created).isoformat()
+            asctime = dt.datetime.fromtimestamp(record.created).isoformat()
             m = self.tz_offset.match(time.strftime('%z'))
             has_offset = False
             if m and time.timezone:

pr-preview/pr-1214/_sources/library/asyncio-dev.rst.txt

@@ -248,3 +248,225 @@ Output in debug mode::
       File "../t.py", line 4, in bug
         raise Exception("not consumed")
     Exception: not consumed
+
+
+Asynchronous generators best practices
+======================================
+
+Writing correct and efficient asyncio code requires awareness of certain pitfalls.
+This section outlines essential best practices that can save you hours of debugging.
+
+
+Close asynchronous generators explicitly
+----------------------------------------
+
+It is recommended to manually close the
+:term:`asynchronous generator <asynchronous generator iterator>`. If a generator
+exits early - for example, due to an exception raised in the body of
+an ``async for`` loop - its asynchronous cleanup code may run in an
+unexpected context. This can occur after the tasks it depends on have completed,
+or during the event loop shutdown when the async-generator's garbage collection
+hook is called.
+
+To avoid this, explicitly close the generator by calling its
+:meth:`~agen.aclose` method, or use the :func:`contextlib.aclosing`
+context manager::
+
+  import asyncio
+  import contextlib
+
+  async def gen():
+    yield 1
+    yield 2
+
+  async def func():
+    async with contextlib.aclosing(gen()) as g:
+      async for x in g:
+        break  # Don't iterate until the end
+
+  asyncio.run(func())
+
+As noted above, the cleanup code for these asynchronous generators is deferred.
+The following example demonstrates that the finalization of an asynchronous
+generator can occur in an unexpected order::
+
+  import asyncio
+  work_done = False
+
+  async def cursor():
+      try:
+          yield 1
+      finally:
+          assert work_done
+
+  async def rows():
+      global work_done
+      try:
+          yield 2
+      finally:
+          await asyncio.sleep(0.1) # immitate some async work
+          work_done = True
+
+
+  async def main():
+      async for c in cursor():
+          async for r in rows():
+              break
+          break
+
+  asyncio.run(main())
+
+For this example, we get the following output::
+
+  unhandled exception during asyncio.run() shutdown
+  task: <Task finished name='Task-3' coro=<<async_generator_athrow without __name__>()> exception=AssertionError()>
+  Traceback (most recent call last):
+    File "example.py", line 6, in cursor
+      yield 1
+  asyncio.exceptions.CancelledError
+
+  During handling of the above exception, another exception occurred:
+
+  Traceback (most recent call last):
+    File "example.py", line 8, in cursor
+      assert work_done
+             ^^^^^^^^^
+  AssertionError
+
+The ``cursor()`` asynchronous generator was finalized before the ``rows``
+generator - an unexpected behavior.
+
+The example can be fixed by explicitly closing the
+``cursor`` and ``rows`` async-generators::
+
+  async def main():
+      async with contextlib.aclosing(cursor()) as cursor_gen:
+          async for c in cursor_gen:
+              async with contextlib.aclosing(rows()) as rows_gen:
+                  async for r in rows_gen:
+                      break
+              break
+
+
+Create asynchronous generators only when the event loop is running
+------------------------------------------------------------------
+
+It is recommended to create
+:term:`asynchronous generators <asynchronous generator iterator>` only after
+the event loop has been created.
+
+To ensure that asynchronous generators close reliably, the event loop uses the
+:func:`sys.set_asyncgen_hooks` function to register callback functions. These
+callbacks update the list of running asynchronous generators to keep it in a
+consistent state.
+
+When the :meth:`loop.shutdown_asyncgens() <asyncio.loop.shutdown_asyncgens>`
+function is called, the running generators are stopped gracefully and the
+list is cleared.
+
+The asynchronous generator invokes the corresponding system hook during its
+first iteration. At the same time, the generator records that the hook has
+been called and does not call it again.
+
+Therefore, if iteration begins before the event loop is created,
+the event loop will not be able to add the generator to its list of active
+generators because the hooks are set after the generator attempts to call them.
+Consequently, the event loop will not be able to terminate the generator
+if necessary.
+
+Consider the following example::
+
+  import asyncio
+
+  async def agenfn():
+      try:
+          yield 10
+      finally:
+          await asyncio.sleep(0)
+
+
+  with asyncio.Runner() as runner:
+      agen = agenfn()
+      print(runner.run(anext(agen)))
+      del agen
+
+Output::
+
+  10
+  Exception ignored while closing generator <async_generator object agenfn at 0x000002F71CD10D70>:
+  Traceback (most recent call last):
+    File "example.py", line 13, in <module>
+      del agen
+          ^^^^
+  RuntimeError: async generator ignored GeneratorExit
+
+This example can be fixed as follows::
+
+  import asyncio
+
+  async def agenfn():
+      try:
+          yield 10
+      finally:
+          await asyncio.sleep(0)
+
+  async def main():
+      agen = agenfn()
+      print(await anext(agen))
+      del agen
+
+  asyncio.run(main())
+
+
+Avoid concurrent iteration and closure of the same generator
+------------------------------------------------------------
+
+Async generators may be reentered while another
+:meth:`~agen.__anext__` / :meth:`~agen.athrow` / :meth:`~agen.aclose` call is in
+progress. This may lead to an inconsistent state of the async generator and can
+cause errors.
+
+Let's consider the following example::
+
+  import asyncio
+
+  async def consumer():
+      for idx in range(100):
+          await asyncio.sleep(0)
+          message = yield idx
+          print('received', message)
+
+  async def amain():
+      agenerator = consumer()
+      await agenerator.asend(None)
+
+      fa = asyncio.create_task(agenerator.asend('A'))
+      fb = asyncio.create_task(agenerator.asend('B'))
+      await fa
+      await fb
+
+  asyncio.run(amain())
+
+Output::
+
+  received A
+  Traceback (most recent call last):
+    File "test.py", line 38, in <module>
+      asyncio.run(amain())
+      ~~~~~~~~~~~^^^^^^^^^
+    File "Lib/asyncio/runners.py", line 204, in run
+      return runner.run(main)
+             ~~~~~~~~~~^^^^^^
+    File "Lib/asyncio/runners.py", line 127, in run
+      return self._loop.run_until_complete(task)
+             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
+    File "Lib/asyncio/base_events.py", line 719, in run_until_complete
+      return future.result()
+             ~~~~~~~~~~~~~^^
+    File "test.py", line 36, in amain
+      await fb
+  RuntimeError: anext(): asynchronous generator is already running
+
+
+Therefore, it is recommended to avoid using asynchronous generators in parallel
+tasks or across multiple event loops.

pr-preview/pr-1214/_sources/library/asyncio-eventloop.rst.txt

@@ -4,7 +4,7 @@
 .. _asyncio-event-loop:
 
 ==========
-Event Loop
+Event loop
 ==========
 
 **Source code:** :source:`Lib/asyncio/events.py`,
@@ -105,7 +105,7 @@ This documentation page contains the following sections:
 
 .. _asyncio-event-loop-methods:
 
-Event Loop Methods
+Event loop methods
 ==================
 
 Event loops have **low-level** APIs for the following:
@@ -361,7 +361,7 @@ clocks to track time.
    The :func:`asyncio.sleep` function.
 
 
-Creating Futures and Tasks
+Creating futures and tasks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. method:: loop.create_future()
@@ -962,7 +962,7 @@ Transferring files
    .. versionadded:: 3.7
 
 
-TLS Upgrade
+TLS upgrade
 ^^^^^^^^^^^
 
 .. method:: loop.start_tls(transport, protocol, \
@@ -1431,7 +1431,7 @@ Executing code in thread or process pools
       :class:`~concurrent.futures.ThreadPoolExecutor`.
 
 
-Error Handling API
+Error handling API
 ^^^^^^^^^^^^^^^^^^
 
 Allows customizing how exceptions are handled in the event loop.
@@ -1534,7 +1534,7 @@ Enabling debug mode
    The :ref:`debug mode of asyncio <asyncio-debug-mode>`.
 
 
-Running Subprocesses
+Running subprocesses
 ^^^^^^^^^^^^^^^^^^^^
 
 Methods described in this subsections are low-level.  In regular
@@ -1672,7 +1672,7 @@ async/await code consider using the high-level
    are going to be used to construct shell commands.
 
 
-Callback Handles
+Callback handles
 ================
 
 .. class:: Handle
@@ -1715,7 +1715,7 @@ Callback Handles
       .. versionadded:: 3.7
 
 
-Server Objects
+Server objects
 ==============
 
 Server objects are created by :meth:`loop.create_server`,
@@ -1858,7 +1858,7 @@ Do not instantiate the :class:`Server` class directly.
 .. _asyncio-event-loops:
 .. _asyncio-event-loop-implementations:
 
-Event Loop Implementations
+Event loop implementations
 ==========================
 
 asyncio ships with two different event loop implementations:
@@ -1971,10 +1971,10 @@ callback uses the :meth:`loop.call_later` method to reschedule itself
 after 5 seconds, and then stops the event loop::
 
     import asyncio
-    import datetime
+    import datetime as dt
 
     def display_date(end_time, loop):
-        print(datetime.datetime.now())
+        print(dt.datetime.now())
         if (loop.time() + 1.0) < end_time:
             loop.call_later(1, display_date, end_time, loop)
         else:

pr-preview/pr-1214/_sources/library/asyncio-protocol.rst.txt

@@ -1037,7 +1037,7 @@ The subprocess is created by the :meth:`loop.subprocess_exec` method::
         # low-level APIs.
         loop = asyncio.get_running_loop()
 
-        code = 'import datetime; print(datetime.datetime.now())'
+        code = 'import datetime as dt; print(dt.datetime.now())'
         exit_future = asyncio.Future(loop=loop)
 
         # Create the subprocess controlled by DateProtocol;