Track del statement protocol methods (D7)

- Add visit_Delete: `del obj.attr` → __delattr__ edge,
  `del obj[key]` → __delitem__ edge.  Bare `del name` is a
  no-op (flow-insensitive analyzer can't safely clear bindings).
- Three new tests: del_attr, del_item, del_name_no_protocol_edge
- Unify Store/Del context comments across visit_Attribute, visit_Name
- Update CHANGELOG, TODO_DEFERRED, REMAINING-ITEMS

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

Author: Technologicat

CHANGELOG.md

@@ -13,6 +13,9 @@
 
 - Plain-text output format (`--text` / `format="text"`) for both call-graph
   and module-level modes.  Sorted adjacency list with `[D]`/`[U]` edge tags.
+- **`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`.
 
 ### Other
 

REMAINING-ITEMS.md

@@ -15,7 +15,6 @@ v2.0.0 released 2026-02-19.
 
 | Item | Description |
 |------|-------------|
-| D7 | `Del` context tracking |
 | D8 | Iterator protocol tracking + `is_async` |
 | D10 | `visit_Name` local variable noise |
 
@@ -27,11 +26,12 @@ v2.0.0 released 2026-02-19.
 | D13 | Per-comprehension scope isolation |
 | D14 | "Node" terminology overload |
 | D15 | modvis multi-project coloring |
+| D17 | README example graph (synthetic showcase) |
 
-## Completed (shipped in 2.0.0)
+## Completed
 
-All M, S, and N1–N7 items. D1–D6, D9, D11, D16. CI, badges, flake8.
-See `CHANGELOG.md` for the full list.
+All M, S, and N1–N7 items. D1–D7, D9, D11, D16. CI, badges, flake8.
+See `CHANGELOG.md` for the 2.0.0 manifest.
 
 ## Canonical detail
 

TODO_DEFERRED.md

@@ -12,7 +12,7 @@
 ## Medium
 
 - **D6: README: document `--module-level` mode**: ✓ Done (`831f31c`). Also added --svg/--html to modvis CLI.
-- **D7: `Del` context tracking**: Currently silently ignored (falls through the `ast.Load` guard) in `visit_Attribute`/`visit_Name`. Could track `__delattr__`/`__del__` protocol calls for completeness, similar to how `__enter__`/`__exit__` are tracked for `with`.
+- **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__`).
 - **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.
@@ -24,3 +24,4 @@
 - **D13: Per-comprehension scope isolation**: All listcomps (or setcomps, etc.) in the same function share one scope key (e.g. `"module.func.listcomp"`). This is the same on both pre-3.12 (last symtable child wins) and 3.12+ (synthetic scope shared). Would need numbered keys to isolate each comprehension's bindings.
 - **D14: "Node" terminology overload**: Three concepts share the name "node": (1) AST node (`ast.AST`), (2) Pyan's analysis graph node (`Node` class), (3) visualization/output node. Check whether all three are still conflated and consider introducing distinct terminology to reduce confusion.
 - **D15: modvis multi-project coloring**: When analyzing files from several projects in one run, hue could be decided by the top-level directory name (after `./` if any), and lightness by depth in each tree. This would match how the call-graph analyzer colors functions/classes. Currently all modules are colored by their immediate package directory.
+- **D17: README example graph**: The current `graph0.svg` (generated from `pyan.modvis`) is realistic but visually cluttered for a front-page showcase. Replace with a synthetic multi-file example designed to demonstrate the features described in the README's "About" section: uses edges (including recursion and mutual recursion), HSL node coloring (hue by file, lightness by nesting depth), translucent fills, and grouping. Recursion should be visible as a self-loop (A→A), and mutual recursion as a pair of arrows (B→C, C→B). Use meaningful names — no `foo`/`bar`. Omit defines edges — they add noise without aiding first impression. Keep the synthetic source files in the repo (e.g. `examples/`) so the graph is reproducible.

pyan/analyzer.py

@@ -639,7 +639,9 @@ def visit_Constant(self, node):
         tn = t.__name__
         return self.get_node(ns, tn, node, flavor=Flavor.ATTRIBUTE)
 
-    # attribute access (node.ctx is ast.Load/Store/Del; Store is handled by _bind_target)
+    # attribute access (node.ctx is ast.Load/Store/Del)
+    # Store context: handled by _bind_target
+    # Del context: handled by visit_Delete (protocol method edges)
     def visit_Attribute(self, node):
         objname = get_ast_node_name(node.value)
         self.logger.debug(
@@ -708,9 +710,12 @@ def visit_Attribute(self, node):
             # pass on
             else:
                 return self.visit(node.value)
-        # Store/Del contexts: no action (Store handled by _bind_target)
+        # Store context: handled by _bind_target
+        # Del context: handled by visit_Delete (protocol method edges)
 
-    # name access (node.ctx is ast.Load/Store/Del; Store is handled by _bind_target)
+    # name access (node.ctx is ast.Load/Store/Del)
+    # Store context: handled by _bind_target
+    # Del context: handled by visit_Delete (protocol method edges)
     def visit_Name(self, node):
         self.logger.debug("Name %s in context %s, %s:%s" % (node.id, type(node.ctx), self.filename, node.lineno))
 
@@ -731,7 +736,8 @@ def visit_Name(self, node):
                     self.logger.info("New edge added for Use from %s to Name %s" % (from_node, to_node))
 
             return to_node
-        # Store/Del contexts: no action (Store handled by _bind_target)
+        # Store context: handled by _bind_target
+        # Del context: handled by visit_Delete (protocol method edges)
 
     def visit_Assign(self, node):
         # - chaining assignments like "a = b = c" produces multiple targets
@@ -1018,6 +1024,41 @@ def visit_With(self, node):
     def visit_AsyncWith(self, node):
         self._visit_with(node, "__aenter__", "__aexit__")
 
+    def visit_Delete(self, node):
+        """Track protocol method calls implied by `del` statements.
+
+        `del obj.attr` invokes `obj.__delattr__("attr")`.
+        `del obj[key]` invokes `obj.__delitem__(key)`.
+        `del name` just unbinds a local — no protocol call.
+
+        NOTE: `del name` also invalidates prior value bindings for `name`,
+        so a subsequent `name.attr` would be a NameError at runtime.  We do
+        not clear the binding here because the analyzer is flow-insensitive —
+        the `del` might sit in a branch that doesn't always execute, or come
+        after the use in source order but not in control flow.  Clearing would
+        be wrong as often as right.  Revisit if flow sensitivity is ever added.
+        """
+        self.logger.debug("Delete, %s:%s" % (self.filename, node.lineno))
+        from_node = self.get_node_of_current_namespace()
+        for target in node.targets:
+            if isinstance(target, ast.Attribute):
+                obj_node = self.visit(target.value)
+                if isinstance(obj_node, Node):
+                    to_node = self.get_node(obj_node.get_name(), "__delattr__", None, flavor=Flavor.METHOD)
+                    self.logger.debug("Use from %s to %s (del attr)" % (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 (del attr)" % (from_node, to_node))
+            elif isinstance(target, ast.Subscript):
+                obj_node = self.visit(target.value)
+                if isinstance(obj_node, Node):
+                    to_node = self.get_node(obj_node.get_name(), "__delitem__", None, flavor=Flavor.METHOD)
+                    self.logger.debug("Use from %s to %s (del item)" % (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 (del item)" % (from_node, to_node))
+                # Also visit the slice — it may contain names/calls.
+                self.visit(target.slice)
+            # ast.Name in ast.Del context: just unbinds, no protocol call.
+
     # --- Match statement (PEP 634, Python 3.10+) ---
 
     def visit_Match(self, node):

tests/test_code/features.py

@@ -210,3 +210,26 @@ def annotated_func(x: MyType) -> ReturnType:
 
 class Holder:
     value: MyType
+
+
+# --- Del statement ---
+
+class Registry:
+    def __delattr__(self, name):
+        pass
+
+    def __delitem__(self, key):
+        pass
+
+
+def clear_entry(registry):
+    registry = Registry()
+    del registry.entry
+
+def remove_item(registry):
+    registry = Registry()
+    del registry["key"]
+
+def unbind_local():
+    tmp = 1
+    del tmp

tests/test_features.py

@@ -197,6 +197,27 @@ def test_class_body_annotation_uses(v):
     get_node(uses, f"{PREFIX}.MyType")
 
 
+# --- Del statement ---
+
+def test_del_attr(v):
+    """del registry.entry creates uses edge to Registry.__delattr__."""
+    uses = get_in_dict(v.uses_edges, f"{PREFIX}.clear_entry")
+    get_node(uses, f"{PREFIX}.Registry.__delattr__")
+
+
+def test_del_item(v):
+    """del registry["key"] creates uses edge to Registry.__delitem__."""
+    uses = get_in_dict(v.uses_edges, f"{PREFIX}.remove_item")
+    get_node(uses, f"{PREFIX}.Registry.__delitem__")
+
+
+def test_del_name_no_protocol_edge(v):
+    """del tmp (bare name) should not create protocol method edges."""
+    # unbind_local has no uses edges at all — it shouldn't even appear as a key.
+    names = [node.get_name() for node in v.uses_edges.keys()]
+    assert f"{PREFIX}.unbind_local" not in names
+
+
 # --- Type aliases (PEP 695, Python 3.12+) ---
 
 PREFIX_312 = "test_code_312.type_aliases"