Add documentation and refactor code

python/ql/src/experimental/semmle/python/frameworks/SqlAlchemy.qll

@@ -7,9 +7,14 @@ private import python
 private import semmle.python.dataflow.new.DataFlow
 private import semmle.python.dataflow.new.TaintTracking
 private import semmle.python.ApiGraphs
-
+private import semmle.python.Concepts
 
 private module SqlAlchemy {
+  /**
+   * An instantization of a SqlAlchemy Session object.
+   * See https://docs.sqlalchemy.org/en/14/orm/session_api.html#sqlalchemy.orm.Session and
+   * https://docs.sqlalchemy.org/en/14/orm/session_api.html#sqlalchemy.orm.sessionmaker
+   */
   private class SqlAlchemySessionInstance extends API::Node {
     SqlAlchemySessionInstance() {
       this in [
@@ -18,26 +23,40 @@ private module SqlAlchemy {
         ]
     }
 
-    override string toString() { result = "Use of SqlAlchemy Session instance method" }
+    override string toString() { result = "Use of SqlAlchemy Session instantization" }
   }
 
+  /**
+   * An instantization of a SqlAlchemy Engine object.
+   * See https://docs.sqlalchemy.org/en/14/core/engines.html#sqlalchemy.create_engine
+   */
   private class SqlAlchemyEngineInstance extends API::Node {
     SqlAlchemyEngineInstance() {
       this = API::moduleImport("sqlalchemy").getMember("create_engine").getReturn()
     }
 
-    override string toString() { result = "Use of SqlAlchemy Engine instance method" }
+    override string toString() { result = "Use of SqlAlchemy create_engine member" }
   }
 
+  /**
+   * An instantization of a SqlAlchemy Query object.
+   * See https://docs.sqlalchemy.org/en/14/orm/query.html?highlight=query#sqlalchemy.orm.Query
+   */
   private class SqlAlchemyQueryInstance extends API::Node {
     SqlAlchemyQueryInstance() {
-      this instanceof SqlAlchemySessionInstance and
-      this = this.getMember("query").getReturn()
+      this = any(SqlAlchemySessionInstance sessionInstance).getMember("query").getReturn()
     }
 
-    override string toString() { result = "Use of SqlAlchemy Query instance method" }
+    override string toString() { result = "Use of SqlAlchemy Session Query member" }
   }
 
+  /**
+   * A call to `execute` meant to execute an SQL expression
+   * See the following links:
+   *   - https://docs.sqlalchemy.org/en/14/core/connections.html?highlight=execute#sqlalchemy.engine.Connection.execute
+   *   - https://docs.sqlalchemy.org/en/14/core/connections.html?highlight=execute#sqlalchemy.engine.Engine.execute
+   *   - https://docs.sqlalchemy.org/en/14/orm/session_api.html?highlight=execute#sqlalchemy.orm.Session.execute
+   */
   private class SqlAlchemyExecuteCall extends DataFlow::CallCfgNode, SqlExecution::Range {
     SqlAlchemyExecuteCall() {
       exists(SqlAlchemySessionInstance sessionInstance, SqlAlchemyEngineInstance engineInstance |
@@ -50,19 +69,27 @@ private module SqlAlchemy {
     override DataFlow::Node getSql() { result = this.getArg(0) }
   }
 
+  /**
+   * A call to `scalar` meant to execute an SQL expression
+   * See https://docs.sqlalchemy.org/en/14/orm/session_api.html#sqlalchemy.orm.Session.scalar and
+   * https://docs.sqlalchemy.org/en/14/core/connections.html?highlight=scalar#sqlalchemy.engine.Engine.scalar
+   */
   private class SqlAlchemyScalarCall extends DataFlow::CallCfgNode, SqlExecution::Range {
     SqlAlchemyScalarCall() {
-      exists(SqlAlchemySessionInstance sessionInstance |
-        this = sessionInstance.getMember("scalar").getACall()
-      )
+      this = any(SqlAlchemySessionInstance sessionInstance).getMember("scalar").getACall() or
+      this = any(SqlAlchemyEngineInstance engineInstance).getMember("scalar").getACall()
     }
 
     override DataFlow::Node getSql() { result = this.getArg(0) }
   }
 
+  /**
+   * A call on a Query object
+   * See https://docs.sqlalchemy.org/en/14/orm/query.html?highlight=query#sqlalchemy.orm.Query
+   */
   private class SqlAlchemyQueryCall extends DataFlow::CallCfgNode, SqlExecution::Range {
     SqlAlchemyQueryCall() {
-      exists(SqlAlchemyQueryInstance queryInstance | this = queryInstance.getAMember().getACall())
+      this = any(SqlAlchemyQueryInstance queryInstance).getAMember().getACall()
     }
 
     override DataFlow::Node getSql() { result = this.getArg(0) }