PEP 806: codeowners and minor clarification

Author: Zac-HD

.github/CODEOWNERS

@@ -678,6 +678,7 @@ peps/pep-0799.rst  @pablogsal
 peps/pep-0800.rst  @JelleZijlstra
 peps/pep-0801.rst  @warsaw
 peps/pep-0802.rst  @AA-Turner
+peps/pep-0806.rst  @JelleZijlstra
 # ...
 peps/pep-2026.rst  @hugovk
 # ...

peps/pep-806.rst

@@ -126,6 +126,14 @@ except that those prefixed by the ``async`` keyword use the ``__aenter__`` /
 Only the ``with`` statement is modified; ``async with async ctx():`` is a
 syntax error.
 
+The :class:`ast.withitem` node gains a new ``is_async`` integer attribute,
+following the existing ``is_async`` attribute on :class:`ast.comprehension`.
+For ``async with`` statement items, this attribute is always ``1``. For items
+in a regular ``with`` statement, the attribute is ``1`` when the ``async``
+keyword is present and ``0`` otherwise. This allows the AST to precisely
+represent which context managers should use the async protocol while
+maintaining backwards compatibility with existing AST processing tools.
+
 
 Backwards Compatibility
 =======================
@@ -165,7 +173,7 @@ manager in an async context manager.  For example:
     @contextmanager
     async def as_acm(sync_cm):
         with sync_cm as result:
-            await sleep(0)  # make async for structured-concurrency
+            await sleep(0)
             yield result
 
     async with (
@@ -174,12 +182,14 @@ manager in an async context manager.  For example:
     ):
         ...
 
-This is our recommended workaround for most code.
+This is our recommended workaround for almost all code.
 
-However, there are some cases where allowing the scheduler to cancel the task
-(with ``sleep(0)``) is undesirable; conversely breaking the correspondence
-between a syntactic ``await`` / ``async for`` / ``async with`` risks deadlocks
-that cannot be detected by static-analysis tools such as ``flake8-async``.
+However, there are some cases where calling back into the async runtime (i.e.
+executing ``await sleep(0)``) to allow cancellation is undesirable.  On the
+other hand, *omitting* ``await sleep(0)`` would break the transitive property
+that a syntactic ``await`` / ``async for`` / ``async with`` always calls back
+into the async runtime (or raises an exception).  While few codebases enforce
+this property, we have found it indispensible in preventing deadlocks.
 
 
 Workaround: using ``AsyncExitStack``