python: better names

- "Normal" instead of "NonSpecial"
- "NonLibrary" instead of "2"

I could not find a good replacement for "NonLibrary", nor for "Source",
but I added QLDocs in a few places to help the reading.

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

@@ -103,10 +103,10 @@ module ArgumentPassing {
    * Used to limit the size of predicates.
    */
   predicate connects(CallNode call, CallableValue callable) {
-    exists(NonLibraryDataFlowSourceCall c, NonLibraryDataFlowCallable k |
+    exists(NonLibraryNormalCall c, NonLibraryDataFlowCallable k |
       call = c.getNode() and
       callable = k.getCallableValue() and
-      k = c.getCallable2()
+      k = c.getNonLibraryCallable()
     )
   }
 
@@ -438,7 +438,7 @@ newtype TDataFlowCall =
    * Includes function calls, method calls, class calls and library calls.
    * All these will be associated with a `CallNode`.
    */
-  TNonSpecialCall(CallNode call) or
+  TNormalCall(CallNode call) or
   /**
    * Includes calls to special methods.
    * These will be associated with a `SpecialMethodCallNode`.
@@ -449,7 +449,8 @@ newtype TDataFlowCall =
     FlowSummaryImpl::Private::summaryCallbackRange(c, receiver)
   }
 
-class TDataFlowSourceCall = TSpecialCall or TNonSpecialCall;
+/** A call found in the program source (as opposed to a synthesised summary call). */
+class TDataFlowSourceCall = TSpecialCall or TNormalCall;
 
 /** A call that is taken into account by the global data flow computation. */
 abstract class DataFlowCall extends TDataFlowCall {
@@ -500,10 +501,10 @@ abstract class DataFlowSourceCall extends DataFlowCall, TDataFlowSourceCall {
 }
 
 /** A call associated with a `CallNode`. */
-class NonSpecialCall extends DataFlowSourceCall, TNonSpecialCall {
+class NormalCall extends DataFlowSourceCall, TNormalCall {
   CallNode call;
 
-  NonSpecialCall() { this = TNonSpecialCall(call) }
+  NormalCall() { this = TNormalCall(call) }
 
   override string toString() { result = call.toString() }
 
@@ -516,14 +517,15 @@ class NonSpecialCall extends DataFlowSourceCall, TNonSpecialCall {
   override DataFlowCallable getEnclosingCallable() { result.getScope() = call.getNode().getScope() }
 }
 
-abstract class NonLibraryDataFlowSourceCall extends NonSpecialCall {
-  abstract Node getArg2(int n);
+/** A (non-special) call that does not go to a library callable. */
+abstract class NonLibraryNormalCall extends NormalCall {
+  abstract Node getNonLibraryArg(int n);
 
-  final override Node getArg(int n) { result = this.getArg2(n) }
+  final override Node getArg(int n) { result = this.getNonLibraryArg(n) }
 
-  abstract DataFlowCallable getCallable2();
+  abstract DataFlowCallable getNonLibraryCallable();
 
-  final override DataFlowCallable getCallable() { result = this.getCallable2() }
+  final override DataFlowCallable getCallable() { result = this.getNonLibraryCallable() }
 }
 
 /**
@@ -532,7 +534,7 @@ abstract class NonLibraryDataFlowSourceCall extends NonSpecialCall {
  * Bound method calls and class calls insert an argument for the explicit
  * `self` parameter, and special method calls have special argument passing.
  */
-class FunctionCall extends NonLibraryDataFlowSourceCall {
+class FunctionCall extends NonLibraryNormalCall {
   NonLibraryDataFlowCallable callable;
 
   FunctionCall() {
@@ -540,13 +542,15 @@ class FunctionCall extends NonLibraryDataFlowSourceCall {
     call = callable.getACall()
   }
 
-  override Node getArg2(int n) { result = getArg(call, TNoShift(), callable.getCallableValue(), n) }
+  override Node getNonLibraryArg(int n) {
+    result = getArg(call, TNoShift(), callable.getCallableValue(), n)
+  }
 
-  override DataFlowCallable getCallable2() { result = callable }
+  override DataFlowCallable getNonLibraryCallable() { result = callable }
 }
 
 /** A call to a lambda. */
-class LambdaCall extends NonLibraryDataFlowSourceCall {
+class LambdaCall extends NonLibraryNormalCall {
   NonLibraryDataFlowCallable callable;
 
   LambdaCall() {
@@ -554,29 +558,33 @@ class LambdaCall extends NonLibraryDataFlowSourceCall {
     callable = TLambda(any(Function f))
   }
 
-  override Node getArg2(int n) { result = getArg(call, TNoShift(), callable.getCallableValue(), n) }
+  override Node getNonLibraryArg(int n) {
+    result = getArg(call, TNoShift(), callable.getCallableValue(), n)
+  }
 
-  override DataFlowCallable getCallable2() { result = callable }
+  override DataFlowCallable getNonLibraryCallable() { result = callable }
 }
 
 /**
  * Represents a call to a bound method call.
  * The node representing the instance is inserted as argument to the `self` parameter.
  */
-class MethodCall extends NonLibraryDataFlowSourceCall {
+class MethodCall extends NonLibraryNormalCall {
   FunctionValue bm;
 
   MethodCall() { call = bm.getAMethodCall() }
 
   private CallableValue getCallableValue() { result = bm }
 
-  override Node getArg2(int n) {
+  override Node getNonLibraryArg(int n) {
     n > 0 and result = getArg(call, TShiftOneUp(), this.getCallableValue(), n)
     or
     n = 0 and result = TCfgNode(call.getFunction().(AttrNode).getObject())
   }
 
-  override DataFlowCallable getCallable2() { result = TCallableValue(this.getCallableValue()) }
+  override DataFlowCallable getNonLibraryCallable() {
+    result = TCallableValue(this.getCallableValue())
+  }
 }
 
 /**
@@ -585,7 +593,7 @@ class MethodCall extends NonLibraryDataFlowSourceCall {
  * That makes the call node be the post-update node holding the value of the object
  * after the constructor has run.
  */
-class ClassCall extends NonLibraryDataFlowSourceCall {
+class ClassCall extends NonLibraryNormalCall {
   ClassValue c;
 
   ClassCall() {
@@ -595,13 +603,15 @@ class ClassCall extends NonLibraryDataFlowSourceCall {
 
   private CallableValue getCallableValue() { c.getScope().getInitMethod() = result.getScope() }
 
-  override Node getArg2(int n) {
+  override Node getNonLibraryArg(int n) {
     n > 0 and result = getArg(call, TShiftOneUp(), this.getCallableValue(), n)
     or
     n = 0 and result = TSyntheticPreUpdateNode(TCfgNode(call))
   }
 
-  override DataFlowCallable getCallable2() { result = TCallableValue(this.getCallableValue()) }
+  override DataFlowCallable getNonLibraryCallable() {
+    result = TCallableValue(this.getCallableValue())
+  }
 }
 
 /** A call to a special method. */
@@ -626,7 +636,7 @@ class SpecialCall extends DataFlowSourceCall, TSpecialCall {
 }
 
 /** A call to a summarized callable. */
-class LibraryCall extends NonSpecialCall {
+class LibraryCall extends NormalCall {
   LibraryCallable callable;
 
   LibraryCall() { call.getNode() = callable.getACall() }

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

@@ -137,15 +137,15 @@ module SyntheticPostUpdateNode {
    * and should not have an extra node synthesised.
    */
   Node argumentPreUpdateNode() {
-    result = any(FunctionCall c).getArg2(_)
+    result = any(FunctionCall c).getNonLibraryArg(_)
     or
     // Avoid argument 0 of method calls as those have read post-update nodes.
-    exists(MethodCall c, int n | n > 0 | result = c.getArg2(n))
+    exists(MethodCall c, int n | n > 0 | result = c.getNonLibraryArg(n))
     or
     result = any(SpecialCall c).getArg(_)
     or
     // Avoid argument 0 of class calls as those have non-synthetic post-update nodes.
-    exists(ClassCall c, int n | n > 0 | result = c.getArg2(n))
+    exists(ClassCall c, int n | n > 0 | result = c.getNonLibraryArg(n))
     or
     // any argument of any call that we have not been able to resolve
     exists(CallNode call | not resolvedCall(call) |

python/ql/test/experimental/dataflow/TestUtil/UnresolvedCalls.qll

@@ -13,7 +13,7 @@ class UnresolvedCallExpectations extends InlineExpectationsTest {
     exists(location.getFile().getRelativePath()) and
     exists(CallNode call |
       not exists(DataFlowPrivate::DataFlowCall dfc | dfc.getNode() = call |
-        // For every `CallNode`, there is a `DataFlowCall` in the form of a `NonSpecialCall`.
+        // For every `CallNode`, there is a `DataFlowCall` in the form of a `NormalCall`.
         // It does not really count, as it has some abstract overrides. For instance, it does not
         // define `getCallable`, so checking for the existence of this guarantees that we are in a
         // properly resolved call.

python/ql/test/experimental/dataflow/calls/test.py

@@ -31,7 +31,7 @@ try:
     # `mypkg.foo` is a `missing module variable`, but `mypkg.subpkg.bar` is compeltely
     # ignored.
     import mypkg
-    mypkg.foo(42) # $ call=mypkg.foo(..) qlclass=NonSpecialCall
-    mypkg.subpkg.bar(43) # $ call=mypkg.subpkg.bar(..) qlclass=NonSpecialCall
+    mypkg.foo(42) # $ call=mypkg.foo(..) qlclass=NormalCall
+    mypkg.subpkg.bar(43) # $ call=mypkg.subpkg.bar(..) qlclass=NormalCall
 except:
     pass