Merge pull request #1636 from markshannon/python-api-odds-and-ends

Python: Assorted improvements to API.

Author: psygnisfive

python/ql/src/semmle/python/Exprs.qll

@@ -1,5 +1,6 @@
 import python
 private import semmle.python.pointsto.PointsTo
+private import semmle.python.objects.ObjectInternal
 
 /** An expression */
 class Expr extends Expr_, AstNode {
@@ -71,7 +72,8 @@ class Expr extends Expr_, AstNode {
         result = this.getASubExpression()
     }
 
-    /** Gets what this expression might "refer-to". Performs a combination of localized (intra-procedural) points-to
+    /** NOTE: `refersTo` will be deprecated in 2019. Use `pointsTo` instead.
+     * Gets what this expression might "refer-to". Performs a combination of localized (intra-procedural) points-to
      *  analysis and global module-level analysis. This points-to analysis favours precision over recall. It is highly
      *  precise, but may not provide information for a significant number of flow-nodes. 
      *  If the class is unimportant then use `refersTo(value)` or `refersTo(value, origin)` instead.
@@ -82,13 +84,15 @@ class Expr extends Expr_, AstNode {
         this.refersTo(_, obj, cls, origin)
     }
 
-    /** Gets what this expression might "refer-to" in the given `context`.
+    /** NOTE: `refersTo` will be deprecated in 2019. Use `pointsTo` instead.
+     * Gets what this expression might "refer-to" in the given `context`.
      */
     predicate refersTo(Context context, Object obj, ClassObject cls, AstNode origin) {
         this.getAFlowNode().refersTo(context, obj, cls, origin.getAFlowNode())
     }
 
-    /** Whether this expression might "refer-to" to `value` which is from `origin` 
+    /** NOTE: `refersTo` will be deprecated in 2019. Use `pointsTo` instead.
+     * Holds if this expression might "refer-to" to `value` which is from `origin` 
      * Unlike `this.refersTo(value, _, origin)`, this predicate includes results 
      * where the class cannot be inferred.
      */
@@ -97,11 +101,31 @@ class Expr extends Expr_, AstNode {
         this.getAFlowNode().refersTo(obj, origin.getAFlowNode())
     }
 
-    /** Equivalent to `this.refersTo(value, _)` */
+    /** NOTE: `refersTo` will be deprecated in 2019. Use `pointsTo` instead.
+     * Equivalent to `this.refersTo(value, _)` */
     predicate refersTo(Object obj) {
         this.refersTo(obj, _)
     }
 
+    /** Holds if this expression might "point-to" to `value` which is from `origin`
+     * in the given `context`.
+     */
+    predicate pointsTo(Context context, Value value, AstNode origin) {
+        this.getAFlowNode().pointsTo(context, value, origin.getAFlowNode())
+    }
+
+    /** Holds if this expression might "point-to" to `value` which is from `origin`.
+     */
+    predicate pointsTo(Value value, AstNode origin) {
+        this.getAFlowNode().pointsTo(value, origin.getAFlowNode())
+    }
+
+    /** Holds if this expression might "point-to" to `value`.
+     */
+    predicate pointsTo(Value value) {
+        this.pointsTo(value, _)
+    }
+
 }
 
 /** An attribute expression, such as `value.attr` */
@@ -346,6 +370,11 @@ abstract class ImmutableLiteral extends Expr {
     abstract Object getLiteralObject();
 
     abstract boolean booleanValue();
+
+    final Value getLiteralValue() {
+        result.(ConstantObjectInternal).getLiteral() = this
+    }
+
 }
 
 /** A numerical constant expression, such as `7` or `4.2` */
@@ -472,8 +501,10 @@ class NegativeIntegerLiteral extends ImmutableLiteral, UnaryExpr {
         py_cobjectnames(result, "-" + this.getOperand().(IntegerLiteral).getN())
     }
 
+    /** Gets the (integer) value of this constant. Will not return a result if the value does not fit into
+        a 32 bit signed value */
     int getValue() {
-        result = -this.getOperand().(IntegerLiteral).getValue()
+        result = -(this.getOperand().(IntegerLiteral).getValue())
     }
 
 }

python/ql/src/semmle/python/Flow.qll

@@ -222,6 +222,11 @@ class ControlFlowNode extends @py_flow_node {
         this.pointsTo(_, value, _)
     }
 
+    /** Gets the value that this ControlFlowNode points-to. */
+    Value pointsTo() {
+        this.pointsTo(_, result, _)
+    }
+
     /** Gets a value that this ControlFlowNode may points-to. */
     Value inferredValue() {
         this.pointsTo(_, result, _)

python/ql/src/semmle/python/objects/Constants.qll

@@ -73,12 +73,15 @@ abstract class ConstantObjectInternal extends ObjectInternal {
 
     override predicate useOriginAsLegacyObject() { none() }
 
+    /** Gets an AST literal with the same value as this object */
+    abstract ImmutableLiteral getLiteral();
+
 }
 
 private abstract class BooleanObjectInternal extends ConstantObjectInternal {
 
     override ObjectInternal getClass() {
-        result = TBuiltinClassObject(Builtin::special("bool"))
+        result = ClassValue::bool()
     }
 
     override int length() { none() }
@@ -90,6 +93,10 @@ private abstract class BooleanObjectInternal extends ConstantObjectInternal {
     /* Booleans aren't iterable */
     override ObjectInternal getIterNext() { none() }
 
+    override ImmutableLiteral getLiteral() {
+        result.(BooleanLiteral).booleanValue() = this.booleanValue()
+    }
+
 }
 
 private class TrueObjectInternal extends BooleanObjectInternal, TTrue {
@@ -175,10 +182,14 @@ private class NoneObjectInternal extends ConstantObjectInternal, TNone {
     /* None isn't iterable */
     override ObjectInternal getIterNext() { none() }
 
+    override ImmutableLiteral getLiteral() {
+        result instanceof None
+    }
+
 }
 
 
-private class IntObjectInternal extends ConstantObjectInternal, TInt {
+class IntObjectInternal extends ConstantObjectInternal, TInt {
 
     override string toString() {
         result = "int " + this.intValue().toString()
@@ -216,9 +227,15 @@ private class IntObjectInternal extends ConstantObjectInternal, TInt {
     /* ints aren't iterable */
     override ObjectInternal getIterNext() { none() }
 
+    override ImmutableLiteral getLiteral() {
+        result.(IntegerLiteral).getValue() = this.intValue()
+        or
+        result.(NegativeIntegerLiteral).getOperand().(IntegerLiteral).getValue() = -this.intValue()
+    }
+
 }
 
-private class FloatObjectInternal extends ConstantObjectInternal, TFloat {
+class FloatObjectInternal extends ConstantObjectInternal, TFloat {
 
     override string toString() {
         if this.floatValue() = this.floatValue().floor() then (
@@ -241,7 +258,7 @@ private class FloatObjectInternal extends ConstantObjectInternal, TFloat {
         result.floatValue() = this.floatValue()
     }
 
-    private float floatValue() {
+    float floatValue() {
         this = TFloat(result)
     }
 
@@ -264,10 +281,14 @@ private class FloatObjectInternal extends ConstantObjectInternal, TFloat {
     /* floats aren't iterable */
     override ObjectInternal getIterNext() { none() }
 
+    override ImmutableLiteral getLiteral() {
+        result.(FloatLiteral).getValue() = this.floatValue()
+    }
+
 }
 
 
-private class UnicodeObjectInternal extends ConstantObjectInternal, TUnicode {
+class UnicodeObjectInternal extends ConstantObjectInternal, TUnicode {
 
     override string toString() {
         result =  "'" + this.strValue() + "'"
@@ -310,9 +331,13 @@ private class UnicodeObjectInternal extends ConstantObjectInternal, TUnicode {
         result = TUnknownInstance(this.getClass())
     }
 
+    override ImmutableLiteral getLiteral() {
+        result.(Unicode).getText() = this.strValue()
+    }
+
 }
 
-private class BytesObjectInternal extends ConstantObjectInternal, TBytes {
+class BytesObjectInternal extends ConstantObjectInternal, TBytes {
 
     override string toString() {
         result =  "'" + this.strValue() + "'"
@@ -355,6 +380,10 @@ private class BytesObjectInternal extends ConstantObjectInternal, TBytes {
         result = TUnknownInstance(this.getClass())
     }
 
+    override ImmutableLiteral getLiteral() {
+        result.(Bytes).getText() = this.strValue()
+    }
+
 }