Python: Apply suggestions from code review

tausbn · yoff · web-flow · commit 063a8bbc4352 · 2022-03-08T15:20:35.000+01:00
Co-authored-by: yoff &lt;lerchedahl@gmail.com&gt;
diff --git a/cpp/ql/test/TestUtilities/InlineExpectationsTest.qll b/cpp/ql/test/TestUtilities/InlineExpectationsTest.qll
@@ -124,7 +124,9 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds if there is an optional result on the specified location.
+   *
+   * This is similar to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */
diff --git a/csharp/ql/test/TestUtilities/InlineExpectationsTest.qll b/csharp/ql/test/TestUtilities/InlineExpectationsTest.qll
@@ -124,7 +124,9 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds if there is an optional result on the specified location.
+   *
+   * This is similar to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */
diff --git a/java/ql/test/TestUtilities/InlineExpectationsTest.qll b/java/ql/test/TestUtilities/InlineExpectationsTest.qll
@@ -124,7 +124,9 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds if there is an optional result on the specified location.
+   *
+   * This is similar to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */
diff --git a/python/ql/lib/semmle/python/dataflow/new/internal/DataFlowPrivate.qll b/python/ql/lib/semmle/python/dataflow/new/internal/DataFlowPrivate.qll
@@ -1619,7 +1619,7 @@ import IterableUnpacking
  */
 module MatchUnpacking {
   /**
-   * Holds when there is flow from the subject `nodeFrom` to the case `nodeTo` of a `match` statement.
+   * Holds when there is flow from the subject `nodeFrom` to the (top-level) pattern `nodeTo` of a `match` statement.
    *
    * The subject of a match flows to each top-level pattern
    * (a pattern directly under a `case` statement).
diff --git a/python/ql/lib/semmle/python/frameworks/Aiomysql.qll b/python/ql/lib/semmle/python/frameworks/Aiomysql.qll
@@ -15,15 +15,15 @@ private module Aiomysql {
   private import semmle.python.internal.Awaited
 
   /**
-   * Gets the `ConnectionPool` that is created when the result of `aiomysql.create_pool()` is awaited.
+   * Gets a `ConnectionPool` that is created when the result of `aiomysql.create_pool()` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/pool.html
    */
   API::Node connectionPool() {
     result = API::moduleImport("aiomysql").getMember("create_pool").getReturn().getAwaited()
   }
 
   /**
-   * Gets the `Connection` that is created when
+   * Gets a `Connection` that is created when
    * - the result of `aiomysql.connect()` is awaited.
    * - the result of calling `aquire` on a `ConnectionPool` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/connection.html#connection
@@ -35,7 +35,7 @@ private module Aiomysql {
   }
 
   /**
-   * Gets the `Cursor` that is created when
+   * Gets a `Cursor` that is created when
    * - the result of calling `cursor` on a `ConnectionPool` is awaited.
    * - the result of calling `cursor` on a `Connection` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/cursors.html
@@ -85,7 +85,7 @@ private module Aiomysql {
   }
 
   /**
-   * Gets the `Engine` that is created when the result of calling `aiomysql.sa.create_engine` is awaited.
+   * Gets an `Engine` that is created when the result of calling `aiomysql.sa.create_engine` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/sa.html#engine
    */
   API::Node engine() {
@@ -98,7 +98,7 @@ private module Aiomysql {
   }
 
   /**
-   * Gets the `SAConnection` that is created when the result of calling `aquire` on an `Engine` is awaited.
+   * Gets an `SAConnection` that is created when the result of calling `aquire` on an `Engine` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/sa.html#connection
    */
   API::Node saConnection() { result = engine().getMember("acquire").getReturn().getAwaited() }
diff --git a/python/ql/lib/semmle/python/frameworks/Aiopg.qll b/python/ql/lib/semmle/python/frameworks/Aiopg.qll
@@ -15,15 +15,15 @@ private module Aiopg {
   private import semmle.python.internal.Awaited
 
   /**
-   * Gets the `ConnectionPool` that is created when the result of `aiopg.create_pool()` is awaited.
+   * Gets a `ConnectionPool` that is created when the result of `aiopg.create_pool()` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/core.html#pool
    */
   API::Node connectionPool() {
     result = API::moduleImport("aiopg").getMember("create_pool").getReturn().getAwaited()
   }
 
   /**
-   * Gets the `Connection` that is created when
+   * Gets a `Connection` that is created when
    * - the result of `aiopg.connect()` is awaited.
    * - the result of calling `aquire` on a `ConnectionPool` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/core.html#connection
@@ -35,7 +35,7 @@ private module Aiopg {
   }
 
   /**
-   * Gets the `Cursor` that is created when
+   * Gets a `Cursor` that is created when
    * - the result of calling `cursor` on a `ConnectionPool` is awaited.
    * - the result of calling `cursor` on a `Connection` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/core.html#cursor
@@ -85,7 +85,7 @@ private module Aiopg {
   }
 
   /**
-   * Gets the `Engine` that is created when the result of calling `aiopg.sa.create_engine` is awaited.
+   * Gets an `Engine` that is created when the result of calling `aiopg.sa.create_engine` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/sa.html#engine
    */
   API::Node engine() {
@@ -94,7 +94,7 @@ private module Aiopg {
   }
 
   /**
-   * Gets the `SAConnection` that is created when the result of calling `aquire` on an `Engine` is awaited.
+   * Gets an `SAConnection` that is created when the result of calling `aquire` on an `Engine` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/sa.html#connection
    */
   API::Node saConnection() { result = engine().getMember("acquire").getReturn().getAwaited() }
diff --git a/python/ql/lib/semmle/python/frameworks/Asyncpg.qll b/python/ql/lib/semmle/python/frameworks/Asyncpg.qll
@@ -12,13 +12,13 @@ private import semmle.python.ApiGraphs
 private module Asyncpg {
   private import semmle.python.internal.Awaited
 
-  /** Gets the `ConnectionPool` that is created when the result of `asyncpg.create_pool()` is awaited. */
+  /** Gets a `ConnectionPool` that is created when the result of `asyncpg.create_pool()` is awaited. */
   API::Node connectionPool() {
     result = API::moduleImport("asyncpg").getMember("create_pool").getReturn().getAwaited()
   }
 
   /**
-   * Gets the `Connection` that is created when
+   * Gets a `Connection` that is created when
    * - the result of `asyncpg.connect()` is awaited.
    * - the result of calling `aquire` on a `ConnectionPool` is awaited.
    */
diff --git a/python/ql/lib/semmle/python/types/ClassObject.qll b/python/ql/lib/semmle/python/types/ClassObject.qll
@@ -447,7 +447,7 @@ ClassObject theBuiltinFunctionType() {
 /** Gets the class of Python functions */
 ClassObject thePyFunctionType() { result.asBuiltin() = Builtin::special("FunctionType") }
 
-/** Gets thGets the builtin class 'classmethod' */
+/** Gets the builtin class 'classmethod' */
 ClassObject theClassMethodType() { result.asBuiltin() = Builtin::special("ClassMethod") }
 
 /** Gets the builtin class 'staticmethod' */
diff --git a/python/ql/src/Imports/DeprecatedModule.ql b/python/ql/src/Imports/DeprecatedModule.ql
@@ -13,10 +13,7 @@
 import python
 
 /**
- * Gets the name of a deprecated module (for a particular version of Python) and the name of a suggested
- * replacement.
- *
- * The module `name` was deprecated in Python version `major`.`minor`,
+ * Holds if the module `name` was deprecated in Python version `major`.`minor`,
  * and module `instead` should be used instead (or `instead = "no replacement"`)
  */
 predicate deprecated_module(string name, string instead, int major, int minor) {
diff --git a/python/ql/test/TestUtilities/InlineExpectationsTest.qll b/python/ql/test/TestUtilities/InlineExpectationsTest.qll
@@ -124,7 +124,9 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds if there is an optional result on the specified location.
+   *
+   * This is similar to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */
diff --git a/python/tools/recorded-call-graph-metrics/ql/lib/RecordedCalls.qll b/python/tools/recorded-call-graph-metrics/ql/lib/RecordedCalls.qll
@@ -162,7 +162,7 @@ private Builtin traverse_qualname(Builtin parent, string qualname) {
 }
 
 /**
- * Arecorded call where we can identify both the `call` and the `callee` uniquely.
+ * A recorded call where we can identify both the `call` and the `callee` uniquely.
  */
 class IdentifiedRecordedCall extends XMLRecordedCall {
   IdentifiedRecordedCall() {
diff --git a/ruby/ql/test/TestUtilities/InlineExpectationsTest.qll b/ruby/ql/test/TestUtilities/InlineExpectationsTest.qll
@@ -124,7 +124,9 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds if there is an optional result on the specified location.
+   *
+   * This is similar to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */

Original file line number	Diff line number	Diff line change
`@@ -1619,7 +1619,7 @@ import IterableUnpacking`
`1619`	`1619`	`*/`
`1620`	`1620`	`module MatchUnpacking {`
`1621`	`1621`	`/**`
`1622`		- * Holds when there is flow from the subject `nodeFrom` to the case `nodeTo` of a `match` statement.
	`1622`	+ * Holds when there is flow from the subject `nodeFrom` to the (top-level) pattern `nodeTo` of a `match` statement.
`1623`	`1623`	`*`
`1624`	`1624`	`* The subject of a match flows to each top-level pattern`
`1625`	`1625`	* (a pattern directly under a `case` statement).