Python: Infer expression contexts in QL rather than in the extractor

Adds a simple recursive scheme for inferring expression contexts. This
means we no longer need to do this in the extractor, but the present
commit does not attempt to remove that code.

Overall this is an improvement to the readability of the code. Instead
of writing `py_expr_contexts(_, 2, foo)`, we can write
`foo.isDeleteContext()`.

I validated this by running the newly added `ExprContextParity` query on
`python/cpython`, where it had zero results (meaning all of the inferred
contexts match exactly to the ones generated by the extractor).

Finally, the `UselessClass` query used `ctx instanceof AugAssign`, which
never did anything in the first place since `AugAssign` isn't a valid
context type. I therefore refactored it to (presumably) capture the
original intent of also matching augmented assignments.

Author: tausbn

python/ql/lib/change-notes/2026-10-23-inferred-expression-contexts.md

@@ -0,0 +1,5 @@
+---
+category: feature
+---
+* Added `Expr.isLoadContext()`, `Expr.isStoreContext()`, `Expr.isParameterContext()`, and
+  `Expr.isDeleteContext()` to classify expression contexts from the AST structure.

python/ql/lib/semmle/python/Exprs.qll

@@ -4,6 +4,77 @@ module;
 private import python
 private import semmle.python.internal.CachedStages
 
+private newtype TContext =
+  TDel() or
+  TLoad() or
+  TParam() or
+  TStore()
+
+private predicate hasExpressionContext(Expr e) {
+  e instanceof Attribute or
+  e instanceof List or
+  e instanceof Name or
+  e instanceof PlaceHolder or
+  e instanceof Starred or
+  e instanceof Subscript or
+  e instanceof TemplateDottedNotation_ or
+  e instanceof Tuple
+}
+
+private predicate propagatesExpressionContext(Expr parent, Expr child) {
+  child in [parent.(List).getAnElt(), parent.(Tuple).getAnElt(), parent.(Starred).getValue()]
+}
+
+private predicate hasNonLoadExpressionContextSeed(Expr e, TContext context) {
+  context = TStore() and
+  e in [
+      any(Assign a).getATarget(),
+      any(AnnAssign a).getTarget(),
+      any(AssignExpr a).getTarget(),
+      any(For f).getTarget(),
+      any(Comprehension c).getTarget(),
+      any(With w).getOptionalVars(),
+      any(ExceptStmt ex).getName(),
+      any(ExceptGroupStmt ex).getName(),
+      any(Alias a).getAsname(),
+      any(MatchAsPattern p).getAlias(),
+      any(MatchCapturePattern p).getVariable(),
+      any(TypeAlias t).getName(),
+      any(TypeVar t).getName(),
+      any(TypeVarTuple t).getName(),
+      any(ParamSpec p).getName()
+    ]
+  or
+  context = TParam() and
+  (
+    e = any(Function f).getAnArg()
+    or
+    e in [
+        any(Function f).getVararg(),
+        any(Function f).getAKwonlyarg(),
+        any(Function f).getKwarg()
+      ]
+  )
+  or
+  context = TDel() and
+  e = any(Delete d).getATarget()
+}
+
+private predicate inferredNonLoadExpressionContext(Expr e, TContext context) {
+  exists(Expr root |
+    hasNonLoadExpressionContextSeed(root, context) and
+    propagatesExpressionContext*(root, e)
+  )
+}
+
+private predicate inferredExpressionContext(Expr e, TContext context) {
+  inferredNonLoadExpressionContext(e, context)
+  or
+  context = TLoad() and
+  hasExpressionContext(e) and
+  not inferredNonLoadExpressionContext(e, _)
+}
+
 /** An expression */
 class Expr extends Expr_, AstNode {
   /** Gets the scope of this expression */
@@ -54,6 +125,18 @@ class Expr extends Expr_, AstNode {
   /** Gets an immediate (non-nested) sub-expression of this expression */
   Expr getASubExpression() { none() }
 
+  /** Whether this expression occurs in a load context. */
+  predicate isLoadContext() { inferredExpressionContext(this, TLoad()) }
+
+  /** Whether this expression occurs in a store context. */
+  predicate isStoreContext() { inferredExpressionContext(this, TStore()) }
+
+  /** Whether this expression occurs in a parameter context. */
+  predicate isParameterContext() { inferredExpressionContext(this, TParam()) }
+
+  /** Whether this expression occurs in a deletion context. */
+  predicate isDeleteContext() { inferredExpressionContext(this, TDel()) }
+
   override AstNode getAChildNode() { result = this.getASubExpression() }
 }
 
@@ -432,10 +515,10 @@ class Name extends Name_ {
 
   /** Whether this expression is a definition */
   predicate isDefinition() {
-    py_expr_contexts(_, 5, this)
+    this.isStoreContext()
     or
     /* Treat Param as a definition (which it is) */
-    py_expr_contexts(_, 4, this)
+    this.isParameterContext()
     or
     /* The target in an augmented assignment is also a definition (and a use) */
     exists(AugAssign aa | aa.getTarget() = this)
@@ -451,7 +534,7 @@ class Name extends Name_ {
   }
 
   /** Whether this expression is a deletion */
-  predicate isDeletion() { py_expr_contexts(_, 2, this) }
+  predicate isDeletion() { this.isDeleteContext() }
 
   /**
    * Whether this expression deletes variable `v`.
@@ -463,7 +546,7 @@ class Name extends Name_ {
   }
 
   /** Whether this expression is a use */
-  predicate isUse() { py_expr_contexts(_, 3, this) }
+  predicate isUse() { this.isLoadContext() }
 
   /**
    * Whether this expression is a use of variable `v`

python/ql/lib/semmle/python/Flow.qll

@@ -35,19 +35,19 @@ private Py::AstNode toAst(ControlFlowNode n) { py_flow_bb_node(n, result, _, _)
 class ControlFlowNode extends @py_flow_node {
   /** Whether this control flow node is a load (including those in augmented assignments) */
   predicate isLoad() {
-    exists(Py::Expr e | e = toAst(this) | py_expr_contexts(_, 3, e) and not augstore(_, this))
+    exists(Py::Expr e | e = toAst(this) | e.isLoadContext() and not augstore(_, this))
   }
 
   /** Whether this control flow node is a store (including those in augmented assignments) */
   predicate isStore() {
-    exists(Py::Expr e | e = toAst(this) | py_expr_contexts(_, 5, e) or augstore(_, this))
+    exists(Py::Expr e | e = toAst(this) | e.isStoreContext() or augstore(_, this))
   }
 
   /** Whether this control flow node is a delete */
-  predicate isDelete() { exists(Py::Expr e | e = toAst(this) | py_expr_contexts(_, 2, e)) }
+  predicate isDelete() { exists(Py::Expr e | e = toAst(this) | e.isDeleteContext()) }
 
   /** Whether this control flow node is a parameter */
-  predicate isParameter() { exists(Py::Expr e | e = toAst(this) | py_expr_contexts(_, 4, e)) }
+  predicate isParameter() { exists(Py::Expr e | e = toAst(this) | e.isParameterContext()) }
 
   /** Whether this control flow node is a store in an augmented assignment */
   predicate isAugStore() { augstore(_, this) }
@@ -848,9 +848,7 @@ class NameNode extends ControlFlowNode {
     this.isLoad() and
     exists(Py::Name u | this.getNode() = u and u.uses(v))
     or
-    exists(Py::PlaceHolder u |
-      this.getNode() = u and u.getVariable() = v and u.getCtx() instanceof Py::Load
-    )
+    exists(Py::PlaceHolder u | this.getNode() = u and u.getVariable() = v and u.isLoadContext())
     or
     Scopes::use_of_global_variable(this, v.getScope(), v.getId())
   }

python/ql/lib/semmle/python/SelfAttribute.qll

@@ -35,7 +35,7 @@ private predicate self_attribute(Attribute attr, Class cls) {
 /** A helper class for UndefinedClassAttribute.ql & MaybeUndefinedClassAttribute.ql */
 class SelfAttributeRead extends SelfAttribute {
   SelfAttributeRead() {
-    this.getCtx() instanceof Load and
+    this.isLoadContext() and
     // Be stricter for loads.
     // We want to generous as to what is defined (i.e. stores),
     // but strict as to what needs to be defined (i.e. loads).
@@ -68,7 +68,7 @@ class SelfAttributeRead extends SelfAttribute {
 }
 
 class SelfAttributeStore extends SelfAttribute {
-  SelfAttributeStore() { this.getCtx() instanceof Store }
+  SelfAttributeStore() { this.isStoreContext() }
 
   Expr getAssignedValue() { exists(Assign a | a.getATarget() = this | result = a.getValue()) }
 }

python/ql/lib/semmle/python/controlflow/internal/Cfg.qll

@@ -122,16 +122,16 @@ class ControlFlowNode extends CfgImpl::ControlFlowNode {
    * which holds on the destination of compound and unary assignments
    * even though the destination is also a write.
    */
-  predicate isLoad() { py_expr_contexts(_, 3, this.asPyExpr()) }
+  predicate isLoad() { this.asPyExpr().isLoadContext() }
 
   /** Holds if this flow node is a store (including those in augmented assignments). */
-  predicate isStore() { py_expr_contexts(_, 5, this.asPyExpr()) or augstore(_, this) }
+  predicate isStore() { this.asPyExpr().isStoreContext() or augstore(_, this) }
 
   /** Holds if this flow node is a delete. */
-  predicate isDelete() { py_expr_contexts(_, 2, this.asPyExpr()) }
+  predicate isDelete() { this.asPyExpr().isDeleteContext() }
 
   /** Holds if this flow node is a parameter. */
-  predicate isParameter() { py_expr_contexts(_, 4, this.asPyExpr()) }
+  predicate isParameter() { this.asPyExpr().isParameterContext() }
 
   /** Holds if this flow node is a store in an augmented assignment. */
   predicate isAugStore() { augstore(_, this) }
@@ -379,9 +379,7 @@ class NameNode extends ControlFlowNode {
     this.isLoad() and
     exists(Py::Name u | u = this.getNode() and u.uses(v))
     or
-    exists(Py::PlaceHolder u |
-      u = this.getNode() and u.getVariable() = v and u.getCtx() instanceof Py::Load
-    )
+    exists(Py::PlaceHolder u | u = this.getNode() and u.getVariable() = v and u.isLoadContext())
   }
 
   /** Gets the identifier of this name node. */

python/ql/src/Classes/ClassAttributes.qll

@@ -66,7 +66,7 @@ class CheckClass extends ClassObject {
   private predicate monkeyPatched(string name) {
     exists(Attribute a, ControlFlowNode objCfg |
       objCfg.getNode() = a.getObject() and
-      a.getCtx() instanceof Store and
+      a.isStoreContext() and
       PointsTo::points_to(objCfg, _, this, _, _) and
       a.getName() = name
     )

python/ql/src/Classes/OverwritingAttributeInSuperClass.ql

@@ -43,7 +43,7 @@ predicate self_write_stmt(Stmt s, string attr) {
     self = a.getObject() and
     s.contains(a) and
     self.getId() = "self" and
-    a.getCtx() instanceof Store and
+    a.isStoreContext() and
     a.getName() = attr
   )
 }

python/ql/src/Classes/UselessClass.ql

@@ -34,14 +34,20 @@ predicate no_inheritance(Class c) {
 
 predicate is_decorated(Class c) { exists(c.getADecorator()) }
 
+private predicate is_stateful_store(Expr e) {
+  e.isStoreContext()
+  or
+  e = any(AugAssign a).getTarget()
+}
+
 predicate is_stateful(Class c) {
-  exists(Function method, ExprContext ctx |
+  exists(Function method |
     method.getScope() = c and
-    (ctx instanceof Store or ctx instanceof AugStore)
-  |
-    exists(Subscript s | s.getScope() = method and s.getCtx() = ctx)
-    or
-    exists(Attribute a | a.getScope() = method and a.getCtx() = ctx)
+    (
+      exists(Subscript s | s.getScope() = method and is_stateful_store(s))
+      or
+      exists(Attribute a | a.getScope() = method and is_stateful_store(a))
+    )
   )
   or
   exists(Function method, Call call, Attribute a, string name |

python/ql/src/analysis/RatioOfDefinitions.ql

@@ -10,9 +10,9 @@ predicate want_to_have_definition(ExprWithPointsTo e) {
   /* not builtin object like len, tuple, etc. */
   not exists(Value builtin | e.pointsTo(builtin) and builtin.isBuiltin()) and
   (
-    e instanceof Name and e.(Name).getCtx() instanceof Load
+    e instanceof Name and e.isLoadContext()
     or
-    e instanceof Attribute and e.(Attribute).getCtx() instanceof Load
+    e instanceof Attribute and e.isLoadContext()
     or
     e instanceof ImportMember
     or