Exempt aclose_forcefully from ASYNC102

`trio.aclose_forcefully` (and `anyio.aclose_forcefully`) are designed
specifically for cleanup and cancel immediately by design, so calling
them in a `finally:` / critical `except:` does not introduce the
cancellation-replacing hazard that ASYNC102 targets. Treat them as safe,
same as `.aclose()` with no arguments.

Fixes #446.

Author: claude

docs/changelog.rst

@@ -10,6 +10,7 @@ Unreleased
 - :ref:`ASYNC910 <async910>` and :ref:`ASYNC911 <async911>` now accept ``__aenter__`` / ``__aexit__`` methods when the partner method provides the checkpoint, or when only one of the two is defined on a class that inherits from another class (charitably assuming the partner is inherited and contains a checkpoint). `(issue #441) <https://github.com/python-trio/flake8-async/issues/441>`_
 - :ref:`ASYNC300 <async300>` no longer triggers when the result of ``asyncio.create_task()`` is returned from a function. `(issue #398) <https://github.com/python-trio/flake8-async/issues/398>`_
 - Add :ref:`ASYNC126 <async126>` exceptiongroup-subclass-missing-derive. `(issue #334) <https://github.com/python-trio/flake8-async/issues/334>`_
+- :ref:`ASYNC102 <async102>` no longer warns on ``await trio.aclose_forcefully(...)`` / ``await anyio.aclose_forcefully(...)``, which are designed for cleanup and cancel immediately by design. `(issue #446) <https://github.com/python-trio/flake8-async/issues/446>`_
 
 25.7.1
 ======

docs/rules.rst

@@ -25,6 +25,7 @@ _`ASYNC102` : await-in-finally-or-cancelled
     ``await`` inside ``finally``, :ref:`cancelled-catching <cancelled>` ``except:``, or ``__aexit__`` must have shielded :ref:`cancel scope <cancel_scope>` with timeout.
     If not, the async call will immediately raise a new cancellation, suppressing any cancellation that was caught.
     Not applicable to asyncio due to edge-based cancellation semantics it uses as opposed to level-based used by trio and anyio.
+    Calls to ``.aclose()`` (with no arguments) and to :func:`trio.aclose_forcefully` / :func:`anyio.aclose_forcefully` are exempt, as they are intended for use in cleanup.
     See :ref:`ASYNC120 <async120>` for the general case where other exceptions might get suppressed.
 
 ASYNC103 : no-reraise-cancelled

flake8_async/visitors/visitor102_120.py

@@ -84,17 +84,22 @@ def visit_Raise(self, node: ast.Raise):
         self._potential_120.clear()
 
     def is_safe_aclose_call(self, node: ast.Await) -> bool:
-        return (
-            isinstance(node.value, ast.Call)
-            # only known safe if no arguments
+        if not isinstance(node.value, ast.Call):
+            return False
+        # allow `<x>.aclose()` with no arguments
+        if (
+            isinstance(node.value.func, ast.Attribute)
+            and node.value.func.attr == "aclose"
             and not node.value.args
             and not node.value.keywords
-            and isinstance(node.value.func, ast.Attribute)
-            and node.value.func.attr == "aclose"
-        )
+        ):
+            return True
+        # allow `trio.aclose_forcefully(<x>)` / `anyio.aclose_forcefully(<x>)`,
+        # which are specifically designed for cleanup and cancel immediately by design
+        return get_matching_call(node.value, "aclose_forcefully") is not None
 
     def visit_Await(self, node: ast.Await):
-        # allow calls to `.aclose()`
+        # allow calls to `.aclose()` and `[trio/anyio].aclose_forcefully(...)`
         if not (self.is_safe_aclose_call(node)):
             self.async_call_checker(node)
 

tests/eval_files/async102.py

@@ -345,3 +345,22 @@ async def foo():
         await x.aclose(bar=foo)  # ASYNC102: 8, Statement("try/finally", lineno-9)
         await x.aclose(*foo)  # ASYNC102: 8, Statement("try/finally", lineno-10)
         await x.aclose(None)  # ASYNC102: 8, Statement("try/finally", lineno-11)
+
+
+# aclose_forcefully is designed for cleanup and is safe in finally/except
+# see https://github.com/python-trio/flake8-async/issues/446
+async def foo_aclose_forcefully():
+    x = None
+
+    try:
+        ...
+    except BaseException:
+        await trio.aclose_forcefully(x)
+    finally:
+        await trio.aclose_forcefully(x)
+
+    # unqualified or unknown-base call is still treated as unsafe
+    try:
+        ...
+    finally:
+        await aclose_forcefully(x)  # ASYNC102: 8, Statement("try/finally", lineno-3)