Various small fixes (#445)

Zac-HD · claude · web-flow · commit 963d4df4cedc · 2026-04-22T09:40:20.000+10:00
* Fix CI running extra tox envs, and ASYNC300 on return In tox 4, `tox -e ""` is treated as "no env specified" and falls back to the default envlist, so the "Run tests without flake8" step was running every `py3xx-flake8` env whose interpreter tox could discover on the runner (including the system Python 3.12), instead of a single no-flake8 test run. Replace the trailing-comma empty env with a proper `[testenv:no_flake8]` section and point CI at it. Also allow `return asyncio.create_task(...)`: treat `Return` like `Assign` in Visitor300, since the caller preserves the task. Fixes #422 Fixes #398 * Address issue #310 points 1 and 4 1. Document using ruff's `lint.external` setting so that `# noqa: ASYNC...` comments survive when both ruff and flake8-async are in use. 4. Apply the `self.novisit = True` fix proposed in #307 at the end of `Visitor102.visit_Try`. The previous code happened to work because the internal `visit_nodes` calls left `self.novisit` True on exit, but relying on that is fragile; making it explicit matches the pattern used elsewhere and documents the intent. * Run compile() against tests/eval_files to catch syntax mistakes ast.parse() accepts some code the bytecode compiler rejects (e.g. `x = lambda: await foo()`, `return` outside a function), so a bad test fixture could silently slip past the plugin's ast-based checks. Add a new parametrized test that runs compile() on every tests/eval_files/*.py. A handful of existing fixtures intentionally contain such constructs to exercise edge cases; mark those with a new `# NOCOMPILE` magic marker so the new test skips them while still leaving the rest of the suite guarding against accidents. Fixes #268 * Drop docs/test-only entries from changelog Docs and test changes aren't user-visible, so they don't need a changelog entry. The ASYNC300 behaviour change stays. * Mark async911.py as # NOCOMPILE for Python 3.10 Python 3.10's compile() rejects nested async comprehensions inside an async function with "asynchronous comprehension outside of an asynchronous function"; 3.11 became permissive here. The file parses fine with ast.parse on every supported version, which is all the plugin needs, so tag it with the existing # NOCOMPILE marker (also in the matching autofix fixture to keep the diff clean). --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -44,7 +44,7 @@ jobs:
             - name: Run tests with flake8
               run: python -m tox -e flake8
             - name: Run tests without flake8
-              run: python -m tox -e "" -- --no-cov
+              run: python -m tox -e no_flake8 -- --no-cov
 
     slow_tests:
         runs-on: ubuntu-latest
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -8,6 +8,7 @@ Unreleased
 ==========
 - Autofix for :ref:`ASYNC910 <async910>` / :ref:`ASYNC911 <async911>` no longer inserts checkpoints inside ``except`` clauses (which would trigger :ref:`ASYNC120 <async120>`); instead the checkpoint is added at the top of the function or of the enclosing loop. `(issue #403) <https://github.com/python-trio/flake8-async/issues/403>`_
 - :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>`_
 
 25.7.1
 ======
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -91,6 +91,19 @@ Run through ruff
 
 They currently only support a small subset of the ``flake8-async`` rules though, see https://github.com/astral-sh/ruff/issues/8451 for current status and https://docs.astral.sh/ruff/rules/#flake8-async-async for documentation.
 
+Using both ruff and flake8-async
+--------------------------------
+
+Ruff will by default strip any ``# noqa`` comments for codes it does not know about, which breaks suppressions for ``ASYNC`` codes that ruff hasn't reimplemented. You can tell ruff to preserve them by listing ``ASYNC`` under `lint.external <https://docs.astral.sh/ruff/settings/#lint_external>`_ in your ruff config:
+
+.. code-block:: toml
+
+   # pyproject.toml
+   [tool.ruff.lint]
+   external = ["ASYNC"]
+
+With that in place you can continue to run ``flake8-async`` (either via ``flake8``, pre-commit, or as a standalone) alongside ``ruff`` without losing ``# noqa: ASYNC...`` comments.
+
 *************
 Configuration
 *************
diff --git a/flake8_async/visitors/visitor102_120.py b/flake8_async/visitors/visitor102_120.py
@@ -153,6 +153,10 @@ def visit_Try(self, node: ast.Try | ast.TryStar):  # type: ignore[name-defined]
         self._critical_scope = Statement("try/finally", node.lineno, node.col_offset)
         self.visit_nodes(node.finalbody)
 
+        # we've manually visited the Try fields above; stop the runner from doing
+        # it a second time via generic_visit.
+        self.novisit = True
+
     visit_TryStar = visit_Try
 
     def visit_ExceptHandler(self, node: ast.ExceptHandler):
diff --git a/flake8_async/visitors/visitors.py b/flake8_async/visitors/visitors.py
@@ -560,6 +560,7 @@ def visit_Call(self, node: cst.Call):
 
     visit_NamedExpr = visit_Assign
     visit_AugAssign = visit_Assign
+    visit_Return = visit_Assign
     visit_IfExp_test = visit_CompIf
 
     # because this is a Flake8AsyncVisitor_cst, we need to manually call restore_state
@@ -573,6 +574,7 @@ def leave_Assign(
     leave_CompIf = leave_Assign
     leave_NamedExpr = leave_Assign
     leave_AugAssign = leave_Assign
+    leave_Return = leave_Assign
 
     def leave_IfExp_test(self, node: cst.IfExp):
         self.restore_state(node)
diff --git a/tests/autofix_files/async124.py b/tests/autofix_files/async124.py
@@ -3,6 +3,9 @@
 
 # ARG --enable=ASYNC124,ASYNC910,ASYNC911
 # ARG --no-checkpoint-warning-decorator=custom_disabled_decorator
+# NOCOMPILE: foo_nested_sync contains `await` in a sync nested function, which is
+# a SyntaxError the bytecode compiler catches but ast.parse accepts. It's only here
+# to make sure the plugin doesn't crash on such code.
 
 # 910/911 will also autofix async124, in the sense of adding a checkpoint. This is perhaps
 # not what the user wants though, so this would be a case in favor of making 910/911 not
diff --git a/tests/autofix_files/async911.py b/tests/autofix_files/async911.py
@@ -1,5 +1,8 @@
 # AUTOFIX
 # ASYNCIO_NO_AUTOFIX
+# NOCOMPILE: contains a nested async comprehension inside an async function,
+# which is a SyntaxError under Python 3.10 (compile() got more permissive in 3.11).
+# ast.parse accepts it on all supported versions, which is all the plugin needs.
 from typing import Any
 
 import pytest
diff --git a/tests/eval_files/async103_104_py311.py b/tests/eval_files/async103_104_py311.py
@@ -4,6 +4,9 @@
 ASYNC104: cancelled-not-raised
 """
 
+# NOCOMPILE: `return` inside `except*` is a SyntaxError in 3.11+ but we still want
+# to exercise the plugin against it via ast.parse.
+
 # ARG --enable=ASYNC103,ASYNC104
 
 try:
diff --git a/tests/eval_files/async104.py b/tests/eval_files/async104.py
@@ -1,4 +1,6 @@
 # ARG --enable=ASYNC103,ASYNC104
+# NOCOMPILE: contains `return` outside a function so the bytecode compiler rejects
+# the file, but ast.parse accepts it and the plugin flags it as ASYNC104.
 try:
     ...
 # raise different exception
diff --git a/tests/eval_files/async124.py b/tests/eval_files/async124.py
@@ -3,6 +3,9 @@
 
 # ARG --enable=ASYNC124,ASYNC910,ASYNC911
 # ARG --no-checkpoint-warning-decorator=custom_disabled_decorator
+# NOCOMPILE: foo_nested_sync contains `await` in a sync nested function, which is
+# a SyntaxError the bytecode compiler catches but ast.parse accepts. It's only here
+# to make sure the plugin doesn't crash on such code.
 
 # 910/911 will also autofix async124, in the sense of adding a checkpoint. This is perhaps
 # not what the user wants though, so this would be a case in favor of making 910/911 not
diff --git a/tests/eval_files/async300.py b/tests/eval_files/async300.py
@@ -42,6 +42,13 @@ async def foo():
 
     mylist = [asyncio.create_task(*args) for i in range(10)]
 
+    # returning the task is fine, the caller will save it
+    def returner():
+        return asyncio.create_task(*args)
+
+    def returner_list():
+        return [asyncio.create_task(*args)]
+
     # non-call usage is fine
     asyncio.create_task
     asyncio.create_task = args
diff --git a/tests/eval_files/async911.py b/tests/eval_files/async911.py
@@ -1,5 +1,8 @@
 # AUTOFIX
 # ASYNCIO_NO_AUTOFIX
+# NOCOMPILE: contains a nested async comprehension inside an async function,
+# which is a SyntaxError under Python 3.10 (compile() got more permissive in 3.11).
+# ast.parse accepts it on all supported versions, which is all the plugin needs.
 from typing import Any
 
 import pytest
diff --git a/tests/test_flake8_async.py b/tests/test_flake8_async.py
@@ -244,6 +244,12 @@ class MagicMarkers:
     # eval file is written using this library, so no substitution is required
     BASE_LIBRARY: str = "trio"
 
+    # File intentionally contains constructs that are syntactically valid for
+    # `ast.parse` but rejected by the bytecode compiler (e.g. `return` outside a
+    # function, `await` in a sync nested function). Used to skip the compile()
+    # sanity check in test_eval_files_compile.
+    NOCOMPILE: bool = False
+
     def library_no_error(self, library: str) -> bool:
         return {
             "anyio": self.ANYIO_NO_ERROR,
@@ -545,6 +551,19 @@ def visit_AsyncFor(self, node: ast.AsyncFor):
         return self.replace_async(node, ast.For, node.target, node.iter)
 
 
+# ast.parse() is lenient and accepts some code that the bytecode compiler will
+# reject (e.g. `x = lambda: await foo()` or `return` outside a function). Running
+# compile() on each eval file catches accidental syntax errors in test fixtures
+# that would otherwise silently slip past the plugin's ast-based checks.
+@pytest.mark.parametrize(("test", "path"), test_files, ids=[f[0] for f in test_files])
+def test_eval_files_compile(test: str, path: Path):
+    check_version(test)
+    content = path.read_text()
+    if find_magic_markers(content).NOCOMPILE:
+        pytest.skip("file intentionally does not compile (has # NOCOMPILE marker)")
+    compile(content, str(path), "exec")
+
+
 @pytest.mark.parametrize(("test", "path"), test_files, ids=[f[0] for f in test_files])
 def test_noerror_on_sync_code(test: str, path: Path):
     if any(e in test for e in error_codes_ignored_when_checking_transformed_sync_code):
diff --git a/tox.ini b/tox.ini
@@ -1,8 +1,7 @@
 # The test environment and commands
 [tox]
 # default environments to run without `-e`
-# trailing comma gives the empty environ - i.e. no flake8 default python
-envlist = py{310,311,312,313,314}-{flake8},
+envlist = py{310,311,312,313,314}-flake8, no_flake8
 
 # create a default testenv, whose behaviour will depend on the name it's called with.
 # for CI you can call with `-e flake8_6,flake8_7` and let the CI handle python version
@@ -22,6 +21,10 @@ deps =
 commands =
     coverage run -m pytest {posargs:-n auto}
 
+# runs the default testenv without flake8 installed, to ensure flake8-async
+# works when used purely as a pre-commit hook / standalone tool.
+[testenv:no_flake8]
+
 [testenv:docs]
 description = Generate docs locally
 deps =
