Track iterator protocol methods for for/async for/comprehensions (D8)

- Add _add_iterator_protocol_edges(): __iter__/__next__ for sync,
  __aiter__/__anext__ for async iteration
- visit_For: resolve iterable, add sync protocol edges
- visit_AsyncFor: no longer a trivial alias; adds async protocol edges
- analyze_comprehension: protocol edges for outermost and inner
  generators, using each generator's is_async flag
- Document double-visit pattern consistently across visit_For,
  visit_AsyncFor, analyze_comprehension, and _visit_with
- Three new tests: for_iter_protocol, async_for_iter_protocol,
  comprehension_iter_protocol
- Update CHANGELOG, TODO_DEFERRED, REMAINING-ITEMS

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Technologicat

CHANGELOG.md

@@ -9,6 +9,10 @@
 - **`del` statement protocol tracking** — `del obj.attr` now generates a uses
   edge to `__delattr__`, and `del obj[key]` to `__delitem__`.  Complements the
   existing `__enter__`/`__exit__` tracking for `with`.
+- **Iterator protocol tracking** — `for` loops, `async for` loops, and
+  comprehensions now generate uses edges to `__iter__`/`__next__` (or
+  `__aiter__`/`__anext__` for async).  Comprehension generators respect
+  the `is_async` flag.
 
 ### Bug fixes
 

REMAINING-ITEMS.md

@@ -15,7 +15,6 @@ v2.0.0 released 2026-02-19.
 
 | Item | Description |
 |------|-------------|
-| D8 | Iterator protocol tracking + `is_async` |
 | D10 | `visit_Name` local variable noise |
 
 ### Large
@@ -30,7 +29,7 @@ v2.0.0 released 2026-02-19.
 
 ## Completed
 
-All M, S, and N1–N7 items. D1–D7, D9, D11, D16. CI, badges, flake8.
+All M, S, and N1–N8, D9, D11, D16. CI, badges, flake8.
 See `CHANGELOG.md` for the 2.0.0 manifest.
 
 ## Canonical detail

TODO_DEFERRED.md

@@ -13,7 +13,7 @@
 
 - **D6: README: document `--module-level` mode**: ✓ Done (`831f31c`). Also added --svg/--html to modvis CLI.
 - **D7: `Del` context tracking**: ✓ Done. `visit_Delete` tracks `__delattr__` for `del obj.attr` and `__delitem__` for `del obj[key]`. Bare `del name` is a no-op (just unbinds). Three tests added.
-- **D8: Iterator protocol tracking + `is_async`**: We already track the context manager protocol (`__enter__`/`__exit__` for `with`). Tracking the iterator protocol (`__iter__`/`__next__`) would be a natural addition — and would make `analyze_comprehension`'s ignored `ast.comprehension.is_async` field relevant too (`__aiter__`/`__anext__` vs `__iter__`/`__next__`).
+- **D8: Iterator protocol tracking + `is_async`**: ✓ Done. `_add_iterator_protocol_edges()` adds `__iter__`/`__next__` (or `__aiter__`/`__anext__` when async) for `for`, `async for`, and comprehension generators. The `is_async` field on `ast.comprehension` is now used. Three tests added.
 - **D9: modvis `filename_to_module_name` cwd fragility**: ✓ Done (`c9cc075`+`a310477`). Added `root` parameter to `filename_to_module_name`, `ImportVisitor`, `create_modulegraph`, and CLI `--root`. Root is inferred by default (walk up past `__init__.py` dirs).
 - **D10: `visit_Name` local variable noise**: When a local has no known value, a wildcard `UNKNOWN`-flavored node is created (analyzer.py:721–725). The existing TODO suggests skipping node creation for locals in the innermost scope — would reduce graph noise and postprocessor cleanup work.
 - **D11: Plain-text output**: ✓ Done (`d2a5b6a`). `TextWriter` added to `writers.py`; `--text` CLI flag and `"text"` format for both call-graph and module-level modes. Old commented-out plaintext code removed from modvis.

pyan/analyzer.py

@@ -845,9 +845,33 @@ def visit_AugAssign(self, node):
     #  consequences in the expand_unknowns() step, if the same name is
     #  in use elsewhere.)
     #
+    def _add_iterator_protocol_edges(self, iter_node, is_async=False):
+        """Add uses edges for the iterator protocol on `iter_node`.
+
+        Sync iteration:  ``__iter__`` + ``__next__``
+        Async iteration: ``__aiter__`` + ``__anext__``
+        """
+        if isinstance(iter_node, Node):
+            from_node = self.get_node_of_current_namespace()
+            if is_async:
+                methods = ("__aiter__", "__anext__")
+            else:
+                methods = ("__iter__", "__next__")
+            for methodname in methods:
+                to_node = self.get_node(iter_node.get_name(), methodname, None, flavor=Flavor.METHOD)
+                self.logger.debug("Use from %s to %s (iteration)" % (from_node, to_node))
+                if self.add_uses_edge(from_node, to_node):
+                    self.logger.info("New edge added for Use from %s to %s (iteration)" % (from_node, to_node))
+
     def visit_For(self, node):
         self.logger.debug("For-loop, %s:%s" % (self.filename, node.lineno))
 
+        # Visit the iterable to resolve the object node, then add protocol edges.
+        # NOTE: node.iter is visited again inside analyze_binding(); the double
+        # visit is harmless (resolves to the same node, edges deduplicate).
+        iter_node = self.visit(node.iter)
+        self._add_iterator_protocol_edges(iter_node)
+
         targets = canonize_exprs(node.target)
         values = canonize_exprs(node.iter)
         self.analyze_binding(targets, values)
@@ -858,7 +882,21 @@ def visit_For(self, node):
             self.visit(stmt)
 
     def visit_AsyncFor(self, node):
-        self.visit_For(node)  # TODO: alias for now; tag async for in output in a future version?
+        self.logger.debug("AsyncFor-loop, %s:%s" % (self.filename, node.lineno))
+
+        # NOTE: node.iter is visited again inside analyze_binding(); the double
+        # visit is harmless (resolves to the same node, edges deduplicate).
+        iter_node = self.visit(node.iter)
+        self._add_iterator_protocol_edges(iter_node, is_async=True)
+
+        targets = canonize_exprs(node.target)
+        values = canonize_exprs(node.iter)
+        self.analyze_binding(targets, values)
+
+        for stmt in node.body:
+            self.visit(stmt)
+        for stmt in node.orelse:
+            self.visit(stmt)
 
     def visit_ListComp(self, node):
         self.logger.debug("ListComp, %s:%s" % (self.filename, node.lineno))
@@ -904,6 +942,7 @@ def analyze_comprehension(self, node, label, field1="elt", field2=None):
         iter_node = None
         for expr in outermost_iters:
             iter_node = self.visit(expr)
+        self._add_iterator_protocol_edges(iter_node, is_async=outermost.is_async)
 
         # Ensure comprehension scope exists. On Python 3.12+ (PEP 709),
         # symtable no longer reports listcomp/setcomp/dictcomp as child scopes.
@@ -924,11 +963,15 @@ def analyze_comprehension(self, node, label, field1="elt", field2=None):
             for expr in outermost.ifs:
                 self.visit(expr)
 
-            # TODO: there's also an is_async field we might want to use in a future version of Pyan.
             for gen in moregens:
                 targets = canonize_exprs(gen.target)
                 values = canonize_exprs(gen.iter)
                 self.analyze_binding(targets, values)
+                # Add iterator protocol edges for inner generators.
+                # NOTE: gen.iter is visited again (already visited inside
+                # analyze_binding); harmless — same node, edges deduplicate.
+                inner_iter_node = self.visit(gen.iter)
+                self._add_iterator_protocol_edges(inner_iter_node, is_async=gen.is_async)
                 for expr in gen.ifs:
                     self.visit(expr)
 
@@ -996,7 +1039,8 @@ def add_uses_enter_exit_of(graph_node):
             expr = withitem.context_expr
             vars = withitem.optional_vars
 
-            # XXX: we currently visit expr twice (again in analyze_binding()) if vars is not None
+            # NOTE: expr is visited again inside analyze_binding() when vars is not None;
+            # the double visit is harmless (resolves to the same node, edges deduplicate).
             cm_node = self.visit(expr)
             add_uses_enter_exit_of(cm_node)
 

tests/test_code/features.py

@@ -233,3 +233,38 @@ def remove_item(registry):
 def unbind_local():
     tmp = 1
     del tmp
+
+
+# --- Iterator protocol ---
+
+class Sequence:
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        raise StopIteration
+
+
+def iterate_sequence():
+    seq = Sequence()
+    for item in seq:  # noqa: F841  # test fixture
+        pass
+
+
+class AsyncStream:
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        raise StopAsyncIteration
+
+
+async def iterate_async_stream():
+    stream = AsyncStream()
+    async for chunk in stream:  # noqa: F841  # test fixture
+        pass
+
+
+def comprehend_sequence():
+    seq = Sequence()
+    return [x for x in seq]

tests/test_features.py

@@ -218,6 +218,29 @@ def test_del_name_no_protocol_edge(v):
     assert f"{PREFIX}.unbind_local" not in names
 
 
+# --- Iterator protocol ---
+
+def test_for_iter_protocol(v):
+    """for item in seq: creates uses edges to Sequence.__iter__ and __next__."""
+    uses = get_in_dict(v.uses_edges, f"{PREFIX}.iterate_sequence")
+    get_node(uses, f"{PREFIX}.Sequence.__iter__")
+    get_node(uses, f"{PREFIX}.Sequence.__next__")
+
+
+def test_async_for_iter_protocol(v):
+    """async for chunk in stream: creates uses edges to AsyncStream.__aiter__ and __anext__."""
+    uses = get_in_dict(v.uses_edges, f"{PREFIX}.iterate_async_stream")
+    get_node(uses, f"{PREFIX}.AsyncStream.__aiter__")
+    get_node(uses, f"{PREFIX}.AsyncStream.__anext__")
+
+
+def test_comprehension_iter_protocol(v):
+    """[x for x in seq] creates uses edges to Sequence.__iter__ and __next__."""
+    uses = get_in_dict(v.uses_edges, f"{PREFIX}.comprehend_sequence")
+    get_node(uses, f"{PREFIX}.Sequence.__iter__")
+    get_node(uses, f"{PREFIX}.Sequence.__next__")
+
+
 # --- Type aliases (PEP 695, Python 3.12+) ---
 
 PREFIX_312 = "test_code_312.type_aliases"