Python: deprecate Function.getAReturnValueFlowNode() and rewrite internal callers

Follow-up to the getAFlowNode deprecation in the same PR: same AST→legacy-CFG
bridge pattern. The 11 internal call sites (across objects/, types/,
frameworks/, and TypeTrackingImpl) are rewritten to bind a `Return ret`
explicitly, then constrain via `ret.getScope() = f and n.getNode() = ret.getValue()`.

The predicate itself is preserved with a deprecation note so external
users do not experience churn.

Semantic noop.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: yoff

python/ql/lib/change-notes/2026-06-01-deprecate-getAReturnValueFlowNode.md

@@ -0,0 +1,4 @@
+---
+category: deprecated
+---
+* The `Function.getAReturnValueFlowNode()` predicate has been deprecated. Bind a `Return` node explicitly instead — `exists(Return ret | ret.getScope() = f and n.getNode() = ret.getValue())`. This is a preparatory step towards migrating the dataflow library off the legacy CFG; it has no semantic effect.

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

@@ -70,6 +70,8 @@ class Attribute extends Attribute_ {
   /* syntax: Expr.name */
   override Expr getASubExpression() { result = this.getObject() }
 
+  deprecated override AttrNode getAFlowNode() { result = super.getAFlowNode() }
+
   /** Gets the name of this attribute. That is the `name` in `obj.name` */
   string getName() { result = Attribute_.super.getAttr() }
 
@@ -96,6 +98,8 @@ class Subscript extends Subscript_ {
   }
 
   Expr getObject() { result = Subscript_.super.getValue() }
+
+  deprecated override SubscriptNode getAFlowNode() { result = super.getAFlowNode() }
 }
 
 /** A call expression, such as `func(...)` */
@@ -111,6 +115,8 @@ class Call extends Call_ {
 
   override string toString() { result = this.getFunc().toString() + "()" }
 
+  deprecated override CallNode getAFlowNode() { result = super.getAFlowNode() }
+
   /** Gets a tuple (*) argument of this call. */
   Expr getStarargs() { result = this.getAPositionalArg().(Starred).getValue() }
 
@@ -196,6 +202,8 @@ class IfExp extends IfExp_ {
   override Expr getASubExpression() {
     result = this.getTest() or result = this.getBody() or result = this.getOrelse()
   }
+
+  deprecated override IfExprNode getAFlowNode() { result = super.getAFlowNode() }
 }
 
 /** A starred expression, such as the `*rest` in the assignment `first, *rest = seq` */
@@ -404,6 +412,8 @@ class PlaceHolder extends PlaceHolder_ {
   override Expr getASubExpression() { none() }
 
   override string toString() { result = "$" + this.getId() }
+
+  deprecated override NameNode getAFlowNode() { result = super.getAFlowNode() }
 }
 
 /** A tuple expression such as `( 1, 3, 5, 7, 9 )` */
@@ -470,6 +480,8 @@ class Name extends Name_ {
 
   override string toString() { result = this.getId() }
 
+  deprecated override NameNode getAFlowNode() { result = super.getAFlowNode() }
+
   override predicate isArtificial() {
     /* Artificial variable names in comprehensions all start with "." */
     this.getId().charAt(0) = "."
@@ -575,6 +587,8 @@ abstract class NameConstant extends Name, ImmutableLiteral {
 
   override predicate isConstant() { any() }
 
+  deprecated override NameConstantNode getAFlowNode() { result = Name.super.getAFlowNode() }
+
   override predicate isArtificial() { none() }
 }
 

python/ql/lib/semmle/python/Function.qll

@@ -153,8 +153,16 @@ class Function extends Function_, Scope, AstNode {
 
   override predicate contains(AstNode inner) { Scope.super.contains(inner) }
 
-  /** Gets a control flow node for a return value of this function */
-  ControlFlowNode getAReturnValueFlowNode() {
+  /**
+   * DEPRECATED: bind a `Return` node explicitly instead, e.g.
+   * `exists(Return ret | ret.getScope() = this and n.getNode() = ret.getValue())`.
+   * This API is being phased out together with `AstNode.getAFlowNode()` to
+   * untangle the AST and CFG hierarchies in preparation for migrating the
+   * dataflow library off the legacy CFG.
+   *
+   * Gets a control flow node for a return value of this function.
+   */
+  deprecated ControlFlowNode getAReturnValueFlowNode() {
     exists(Return ret |
       ret.getScope() = this and
       ret.getValue() = result.getNode()

python/ql/lib/semmle/python/Import.qll

@@ -149,6 +149,8 @@ class ImportExpr extends ImportExpr_ {
 class ImportMember extends ImportMember_ {
   override Expr getASubExpression() { result = this.getModule() }
 
+  deprecated override ImportMemberNode getAFlowNode() { result = super.getAFlowNode() }
+
   override predicate hasSideEffects() {
     /* Strictly this only has side-effects if the module is a package */
     any()

python/ql/lib/semmle/python/dataflow/new/internal/TypeTrackingImpl.qll

@@ -94,8 +94,10 @@ private module SummaryTypeTrackerInput implements SummaryTypeTracker::Input {
   Node returnOf(Node callable, SummaryComponent return) {
     return = FlowSummaryImpl::Private::SummaryComponent::return() and
     // `result` should be the return value of a callable expression (lambda or function) referenced by `callable`
-    result.asCfgNode() =
-      callable.getALocalSource().asExpr().(CallableExpr).getInnerScope().getAReturnValueFlowNode()
+    exists(Return ret |
+      ret.getScope() = callable.getALocalSource().asExpr().(CallableExpr).getInnerScope() and
+      result.asCfgNode().getNode() = ret.getValue()
+    )
   }
 
   // Relating callables to nodes

python/ql/lib/semmle/python/frameworks/Bottle.qll

@@ -73,7 +73,10 @@ module Bottle {
       /** A response returned by a view callable. */
       class BottleReturnResponse extends Http::Server::HttpResponse::Range {
         BottleReturnResponse() {
-          this.asCfgNode() = any(View::ViewCallable vc).getAReturnValueFlowNode()
+          exists(Return ret |
+            ret.getScope() = any(View::ViewCallable vc) and
+            this.asCfgNode().getNode() = ret.getValue()
+          )
         }
 
         override DataFlow::Node getBody() { result = this }

python/ql/lib/semmle/python/frameworks/Django.qll

@@ -2872,7 +2872,10 @@ module PrivateDjango {
     DataFlow::CfgNode
   {
     DjangoRedirectViewGetRedirectUrlReturn() {
-      node = any(GetRedirectUrlFunction f).getAReturnValueFlowNode()
+      exists(Return ret |
+        ret.getScope() = any(GetRedirectUrlFunction f) and
+        node.getNode() = ret.getValue()
+      )
     }
 
     override DataFlow::Node getRedirectLocation() { result = this }

python/ql/lib/semmle/python/frameworks/FastApi.qll

@@ -309,7 +309,10 @@ module FastApi {
       FastApiRouteSetup routeSetup;
 
       FastApiRequestHandlerReturn() {
-        node = routeSetup.getARequestHandler().getAReturnValueFlowNode()
+        exists(Return ret |
+          ret.getScope() = routeSetup.getARequestHandler() and
+          node.getNode() = ret.getValue()
+        )
       }
 
       override DataFlow::Node getBody() { result = this }

python/ql/lib/semmle/python/frameworks/Pyramid.qll

@@ -166,7 +166,10 @@ module Pyramid {
     /** A response returned by a view callable. */
     private class PyramidReturnResponse extends Http::Server::HttpResponse::Range {
       PyramidReturnResponse() {
-        this.asCfgNode() = any(View::ViewCallable vc).getAReturnValueFlowNode() and
+        exists(Return ret |
+          ret.getScope() = any(View::ViewCallable vc) and
+          this.asCfgNode().getNode() = ret.getValue()
+        ) and
         not this = instance()
       }
 

python/ql/lib/semmle/python/frameworks/Stdlib.qll

@@ -2254,8 +2254,9 @@ module StdlibPrivate {
       DataFlow::CfgNode
     {
       WsgirefSimpleServerApplicationReturn() {
-        exists(WsgirefSimpleServerApplication requestHandler |
-          node = requestHandler.getAReturnValueFlowNode()
+        exists(WsgirefSimpleServerApplication requestHandler, Return ret |
+          ret.getScope() = requestHandler and
+          node.getNode() = ret.getValue()
         )
       }