Add ASYNC126 exceptiongroup-subclass-missing-derive

Warn when a class inherits from `ExceptionGroup` / `BaseExceptionGroup`
but doesn't override `derive`. Without that override, `split`/`subgroup`
(as used by nursery and TaskGroup implementations) silently produce
plain `ExceptionGroup` instances instead of the custom subclass.

Fixes #334.

Author: claude

docs/changelog.rst

@@ -9,6 +9,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>`_
+- Add :ref:`ASYNC126 <async126>` exceptiongroup-subclass-missing-derive. `(issue #334) <https://github.com/python-trio/flake8-async/issues/334>`_
 
 25.7.1
 ======

docs/rules.rst

@@ -123,6 +123,14 @@ _`ASYNC125`: constant-absolute-deadline
     :func:`anyio.move_on_after`, or the ``relative_deadline`` parameter to
     :class:`trio.CancelScope`.
 
+_`ASYNC126`: exceptiongroup-subclass-missing-derive
+    A subclass of :class:`ExceptionGroup` or :class:`BaseExceptionGroup` must override
+    :meth:`~BaseExceptionGroup.derive` to return an instance of itself, otherwise
+    :meth:`~BaseExceptionGroup.split` and :meth:`~BaseExceptionGroup.subgroup` - which
+    are used by e.g. :ref:`taskgroup_nursery` implementations - will silently produce
+    plain ``ExceptionGroup`` instances and lose the custom subclass.
+    See `trio#3175 <https://github.com/python-trio/trio/issues/3175>`_ for motivation.
+
 Blocking sync calls in async functions
 ======================================
 

flake8_async/visitors/visitors.py

@@ -532,6 +532,41 @@ def is_constant(value: ast.expr) -> bool:
             )
 
 
+@error_class
+class Visitor126(Flake8AsyncVisitor):
+    error_codes: Mapping[str, str] = {
+        "ASYNC126": (
+            "ExceptionGroup subclass {} should override `derive`, otherwise"
+            " `split`/`subgroup` (used by e.g. nursery/TaskGroup"
+            " implementations) will silently produce plain `ExceptionGroup`"
+            " instances instead of `{}`."
+        )
+    }
+
+    def visit_ClassDef(self, node: ast.ClassDef):
+        def base_name(base: ast.expr) -> str:
+            # strip generic subscripts like `ExceptionGroup[Foo]`
+            if isinstance(base, ast.Subscript):
+                base = base.value
+            unparsed = ast.unparse(base)
+            return unparsed.rsplit(".", 1)[-1]
+
+        if not any(
+            base_name(b) in ("ExceptionGroup", "BaseExceptionGroup")
+            for b in node.bases
+        ):
+            return
+
+        for item in node.body:
+            if (
+                isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef))
+                and item.name == "derive"
+            ):
+                return
+
+        self.error(node, node.name, node.name)
+
+
 @error_class_cst
 class Visitor300(Flake8AsyncVisitor_cst):
     error_codes: Mapping[str, str] = {

tests/eval_files/async126.py

@@ -0,0 +1,67 @@
+import sys
+
+if sys.version_info < (3, 11):
+    from exceptiongroup import BaseExceptionGroup, ExceptionGroup
+
+
+class NoDerive(ExceptionGroup):  # error: 0, "NoDerive", "NoDerive"
+    pass
+
+
+class NoDeriveBase(BaseExceptionGroup):  # error: 0, "NoDeriveBase", "NoDeriveBase"
+    pass
+
+
+class NoDeriveGeneric(ExceptionGroup[Exception]):  # error: 0, "NoDeriveGeneric", "NoDeriveGeneric"
+    pass
+
+
+import exceptiongroup
+
+
+class NoDeriveQualified(exceptiongroup.ExceptionGroup):  # error: 0, "NoDeriveQualified", "NoDeriveQualified"
+    pass
+
+
+class SomeMixin: ...
+
+
+class MultipleBases(SomeMixin, ExceptionGroup):  # error: 0, "MultipleBases", "MultipleBases"
+    pass
+
+
+# safe - overrides derive
+class HasDerive(ExceptionGroup):
+    def derive(self, excs):
+        return HasDerive(self.message, excs)
+
+
+class HasDeriveBase(BaseExceptionGroup):
+    def derive(self, excs):
+        return HasDeriveBase(self.message, excs)
+
+
+class HasDeriveGeneric(ExceptionGroup[Exception]):
+    def derive(self, excs):
+        return HasDeriveGeneric(self.message, excs)
+
+
+# async derive is weird but counts
+class AsyncDerive(ExceptionGroup):
+    async def derive(self, excs):  # type: ignore
+        return AsyncDerive(self.message, excs)
+
+
+# not an ExceptionGroup subclass
+class NotAnEG(Exception):
+    pass
+
+
+# nested class
+class Outer:
+    class InnerNoDerive(ExceptionGroup):  # error: 4, "InnerNoDerive", "InnerNoDerive"
+        pass
+
+    class InnerHasDerive(ExceptionGroup):
+        def derive(self, excs):
+            return Outer.InnerHasDerive(self.message, excs)

tests/test_flake8_async.py

@@ -521,6 +521,7 @@ def _parse_eval_file(
     "ASYNC122",
     "ASYNC123",
     "ASYNC125",
+    "ASYNC126",
     "ASYNC300",
     "ASYNC400",
     "ASYNC912",