From 00c742f5ff3563d1d3eeaeff979234257b210bc6 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@github.com>
Date: Thu, 7 May 2026 14:14:16 +0000
Subject: [PATCH] Python: document why Assignment subclasses are empty

Explain that the shared library's Assignment / CompoundAssignment
hierarchy extends BinaryExpr, so it cannot host Python's statement-
level assignment forms (Assign, AugAssign), and that Python has no
short-circuiting compound operators (&&=, ||=, ??=) so all
subclasses remain empty.

No behaviour change; doc comments only.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../controlflow/internal/AstNodeImpl.qll      | 24 ++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/python/ql/lib/semmle/python/controlflow/internal/AstNodeImpl.qll b/python/ql/lib/semmle/python/controlflow/internal/AstNodeImpl.qll
index ccd36356572..3fa8adbe6b2 100644
--- a/python/ql/lib/semmle/python/controlflow/internal/AstNodeImpl.qll
+++ b/python/ql/lib/semmle/python/controlflow/internal/AstNodeImpl.qll
@@ -695,19 +695,41 @@ module Ast implements AstSig<Py::Location> {
   /** A logical `not` expression. */
   class LogicalNotExpr extends UnaryExpr { }
 
-  /** An assignment expression. Python's walrus is modelled separately. */
+  /**
+   * An assignment expression.
+   *
+   * Empty in Python: `x = y` and `x += y` are statements (`AssignStmt` and
+   * `AugAssignStmt`), not expressions, and the walrus `x := y` is modeled
+   * separately as `NamedExpr`. The shared library's `Assignment` extends
+   * `BinaryExpr`, so it cannot share instances with our `Stmt`-based
+   * assignment forms.
+   */
   class Assignment extends BinaryExpr {
     Assignment() { none() }
   }
 
+  /** A simple assignment expression. Empty in Python (see `Assignment`). */
   class AssignExpr extends Assignment { }
 
+  /** A compound assignment expression. Empty in Python (see `Assignment`). */
   class CompoundAssignment extends Assignment { }
 
+  /**
+   * A short-circuiting logical AND compound assignment expression (`&&=`).
+   * Python has no such operator.
+   */
   class AssignLogicalAndExpr extends CompoundAssignment { }
 
+  /**
+   * A short-circuiting logical OR compound assignment expression (`||=`).
+   * Python has no such operator.
+   */
   class AssignLogicalOrExpr extends CompoundAssignment { }
 
+  /**
+   * A short-circuiting null-coalescing compound assignment expression
+   * (`??=`). Python has no such operator.
+   */
   class AssignNullCoalescingExpr extends CompoundAssignment { }
 
   /** A boolean literal expression (`True` or `False`). */