Python points-to: Improve qldoc and internal API a bit.

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

@@ -1014,7 +1014,7 @@ class BasicBlock extends @py_flow_node {
         result = this.getLastNode().getAFalseSuccessor().getBasicBlock()
     }
 
-    /** Gets an exceptional successor to this basic block */
+    /** Gets an unconditional successor to this basic block */
     BasicBlock getAnUnconditionalSuccessor() {
         result = this.getASuccessor() and
         not result = this.getATrueSuccessor() and

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

@@ -15,8 +15,11 @@ abstract class ClassObjectInternal extends ObjectInternal {
         result = this.getClassDeclaration().getName()
     }
 
+    /** Holds if this is a class whose instances we treat specially, rather than as a generic instance.
+     * For example, `type` or `int`.
+     */
     boolean isSpecial() {
-        result = Types::getMro(this).isSpecial()
+        result = Types::getMro(this).containsSpecial()
     }
 
     /** Looks up the attribute `name` on this class.

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

@@ -57,7 +57,6 @@ class SpecificInstanceInternal extends TSpecificInstance, InstanceObject {
         result = this.getOrigin().getNode().toString()
     }
 
-    /** The boolean value of this object, if it has one */
     override boolean booleanValue() {
         //result = this.getClass().instancesBooleanValue()
         result = maybe()
@@ -261,7 +260,6 @@ class UnknownInstanceInternal extends TUnknownInstance, ObjectInternal {
         result = "instance of " + this.getClass().(ClassObjectInternal).getName()
     }
 
-    /** The boolean value of this object, if it has one */
     override boolean booleanValue() {
         result = maybe()
     }

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

@@ -16,8 +16,6 @@ abstract class SequenceObjectInternal extends ObjectInternal {
     /** Gets the `n`th item of this sequence, if one exists. */
     abstract ObjectInternal getItem(int n);
 
-    /** The boolean value of this object, this may be both
-     * true and false if the "object" represents a set of possible objects. */
     override boolean booleanValue() {
         this.length() = 0 and result = false
         or
@@ -37,13 +35,11 @@ abstract class SequenceObjectInternal extends ObjectInternal {
 abstract class TupleObjectInternal extends SequenceObjectInternal {
 
     override string toString() {
-        this.length() = 0 and result = "()"
-        or
         result = "(" + this.contents(0) + ")"
     }
 
     private string contents(int n) {
-        n = this.length() - 1 and result = this.getItem(n).toString()
+        n = this.length() and result = ""
         or
         result = this.getItem(n).toString() + ", " + this.contents(n+1)
     }
@@ -149,6 +145,9 @@ class PythonTupleObjectInternal extends TPythonTuple, TupleObjectInternal {
 
 }
 
+/** The `sys.version_info` object. We treat this specially to prevent premature pruning and
+ * false positives when we are unsure of the actual version of Python that the code is expecting.
+ */
 class SysVersionInfoObjectInternal extends TSysVersionInfo, SequenceObjectInternal {
 
     override string toString() {

python/ql/src/semmle/python/pointsto/MRO.qll

@@ -231,7 +231,10 @@ class ClassList extends TClassList {
         reverse_step(this, Empty(), result)
     }
 
-    boolean isSpecial() {
+    /** Holds if this MRO contains a class whose instances we treat specially, rather than as a generic instance.
+     * For example, `type` or `int`.
+     */
+    boolean containsSpecial() {
         this = Empty() and result = false
         or
         exists(ClassDecl decl |
@@ -239,7 +242,7 @@ class ClassList extends TClassList {
             if decl.isSpecial() then
                 result = true
             else
-                result = this.getTail().isSpecial()
+                result = this.getTail().containsSpecial()
         )
     }
 

python/ql/src/semmle/python/pointsto/PointsTo.qll

@@ -205,7 +205,10 @@ cached module PointsToInternal {
         f.(PointsToExtension).pointsTo(context, value, origin)
     }
 
-    /** Holds if the attribute `name` is required for `obj` */
+    /** Holds if the attribute `name` is required for `obj` 
+     * For object `x` and attribute `name` it means that there exists somewhere in the code
+     * `x.name` or `getattr(x, "name")`.
+     */
     cached predicate attributeRequired(ObjectInternal obj, string name) {
         pointsTo(any(AttrNode a).getObject(name), _, obj, _)
         or
@@ -689,16 +692,6 @@ module InterModulePointsTo {
         )
     }
 
-    private predicate importsByImportStar(ModuleObjectInternal mod, ModuleObjectInternal imported) {
-        exists(ImportStarNode isn |
-            PointsToInternal::pointsTo(isn.getModule(), _, imported, _) and
-            isn.getScope() = mod.getSourceModule()
-        )
-        or exists(ModuleObjectInternal mid |
-            importsByImportStar(mod, mid) and importsByImportStar(mid, imported)
-        )
-    }
-
     predicate ofInterestInExports(ModuleObjectInternal mod, string name) {
         exists(ImportStarNode imp, ImportStarRefinement def |
             imp = def.getDefiningNode() and