From 8df186167e765ad54d8eb15c2b1eabcb4360414b Mon Sep 17 00:00:00 2001 From: Rasmus Wriedt Larsen Date: Tue, 15 Dec 2020 15:15:03 +0100 Subject: [PATCH] Python: Reword QLDoc for class modeling with type-tracking As discussed in https://github.com/github/codeql/pull/4797#discussion_r542423387 --- python/.vscode/ql.code-snippets | 8 +- .../src/semmle/python/frameworks/Django.qll | 108 +++++++++--------- .../src/semmle/python/frameworks/Fabric.qll | 8 +- .../ql/src/semmle/python/frameworks/Flask.qll | 16 +-- .../src/semmle/python/frameworks/PEP249.qll | 6 +- .../src/semmle/python/frameworks/Stdlib.qll | 16 +-- .../src/semmle/python/frameworks/Werkzeug.qll | 14 +-- 7 files changed, 88 insertions(+), 88 deletions(-) diff --git a/python/.vscode/ql.code-snippets b/python/.vscode/ql.code-snippets index 76a07df1452b..80c6ef1290df 100644 --- a/python/.vscode/ql.code-snippets +++ b/python/.vscode/ql.code-snippets @@ -321,13 +321,13 @@ " DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }", "", " /**", - " * A source of an instance of `$1.$2`.", + " * A source of instances of `$1.$2`, extend this class to model new instances.", " *", - " * This can include instantiation of the class, return value from function", - " * calls, or a special parameter that will be set when functions are call by external", + " * This can include instantiations of the class, return values from function", + " * calls, or a special parameter that will be set when functions are called by an external", " * library.", " *", - " * Use `$2::instance()` predicate to get references to instances of `$1.$2`.", + " * Use the predicate `$2::instance()` to get references to instances of `$1.$2`.", " */", " abstract class InstanceSource extends DataFlow::Node { }", "", diff --git a/python/ql/src/semmle/python/frameworks/Django.qll b/python/ql/src/semmle/python/frameworks/Django.qll index db8f31f990dc..9e402ec047d4 100644 --- a/python/ql/src/semmle/python/frameworks/Django.qll +++ b/python/ql/src/semmle/python/frameworks/Django.qll @@ -540,9 +540,9 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.request.HttpRequest`. + * A source of instances of `django.http.request.HttpRequest`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function + * This can include instantiations of the class, return values from function * calls, or a special parameter that will be set when functions are called by an external * library. * @@ -646,13 +646,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponse`. + * A source of instances of `django.http.response.HttpResponse`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponse::instance()` predicate to get references to instances of `django.http.response.HttpResponse`. + * Use the predicate `HttpResponse::instance()` to get references to instances of `django.http.response.HttpResponse`. */ abstract class InstanceSource extends HTTP::Server::HttpResponse::Range, DataFlow::Node { } @@ -716,13 +716,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponseRedirect`. + * A source of instances of `django.http.response.HttpResponseRedirect`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponseRedirect::instance()` predicate to get references to instances of `django.http.response.HttpResponseRedirect`. + * Use the predicate `HttpResponseRedirect::instance()` to get references to instances of `django.http.response.HttpResponseRedirect`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -782,13 +782,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponsePermanentRedirect`. + * A source of instances of `django.http.response.HttpResponsePermanentRedirect`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponsePermanentRedirect::instance()` predicate to get references to instances of `django.http.response.HttpResponsePermanentRedirect`. + * Use the predicate `HttpResponsePermanentRedirect::instance()` to get references to instances of `django.http.response.HttpResponsePermanentRedirect`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -849,13 +849,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponseNotModified`. + * A source of instances of `django.http.response.HttpResponseNotModified`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponseNotModified::instance()` predicate to get references to instances of `django.http.response.HttpResponseNotModified`. + * Use the predicate `HttpResponseNotModified::instance()` to get references to instances of `django.http.response.HttpResponseNotModified`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -910,13 +910,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponseBadRequest`. + * A source of instances of `django.http.response.HttpResponseBadRequest`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponseBadRequest::instance()` predicate to get references to instances of `django.http.response.HttpResponseBadRequest`. + * Use the predicate `HttpResponseBadRequest::instance()` to get references to instances of `django.http.response.HttpResponseBadRequest`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -973,13 +973,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponseNotFound`. + * A source of instances of `django.http.response.HttpResponseNotFound`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponseNotFound::instance()` predicate to get references to instances of `django.http.response.HttpResponseNotFound`. + * Use the predicate `HttpResponseNotFound::instance()` to get references to instances of `django.http.response.HttpResponseNotFound`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -1036,13 +1036,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponseForbidden`. + * A source of instances of `django.http.response.HttpResponseForbidden`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponseForbidden::instance()` predicate to get references to instances of `django.http.response.HttpResponseForbidden`. + * Use the predicate `HttpResponseForbidden::instance()` to get references to instances of `django.http.response.HttpResponseForbidden`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -1099,13 +1099,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponseNotAllowed`. + * A source of instances of `django.http.response.HttpResponseNotAllowed`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponseNotAllowed::instance()` predicate to get references to instances of `django.http.response.HttpResponseNotAllowed`. + * Use the predicate `HttpResponseNotAllowed::instance()` to get references to instances of `django.http.response.HttpResponseNotAllowed`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -1163,13 +1163,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponseGone`. + * A source of instances of `django.http.response.HttpResponseGone`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponseGone::instance()` predicate to get references to instances of `django.http.response.HttpResponseGone`. + * Use the predicate `HttpResponseGone::instance()` to get references to instances of `django.http.response.HttpResponseGone`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -1226,13 +1226,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.HttpResponseServerError`. + * A source of instances of `django.http.response.HttpResponseServerError`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `HttpResponseServerError::instance()` predicate to get references to instances of `django.http.response.HttpResponseServerError`. + * Use the predicate `HttpResponseServerError::instance()` to get references to instances of `django.http.response.HttpResponseServerError`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -1289,13 +1289,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.JsonResponse`. + * A source of instances of `django.http.response.JsonResponse`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `JsonResponse::instance()` predicate to get references to instances of `django.http.response.JsonResponse`. + * Use the predicate `JsonResponse::instance()` to get references to instances of `django.http.response.JsonResponse`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -1355,13 +1355,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.StreamingHttpResponse`. + * A source of instances of `django.http.response.StreamingHttpResponse`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `StreamingHttpResponse::instance()` predicate to get references to instances of `django.http.response.StreamingHttpResponse`. + * Use the predicate `StreamingHttpResponse::instance()` to get references to instances of `django.http.response.StreamingHttpResponse`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } @@ -1418,13 +1418,13 @@ private module Django { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `django.http.response.FileResponse`. + * A source of instances of `django.http.response.FileResponse`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `FileResponse::instance()` predicate to get references to instances of `django.http.response.FileResponse`. + * Use the predicate `FileResponse::instance()` to get references to instances of `django.http.response.FileResponse`. */ abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { } diff --git a/python/ql/src/semmle/python/frameworks/Fabric.qll b/python/ql/src/semmle/python/frameworks/Fabric.qll index 5037d918c78e..764dce0de808 100644 --- a/python/ql/src/semmle/python/frameworks/Fabric.qll +++ b/python/ql/src/semmle/python/frameworks/Fabric.qll @@ -281,13 +281,13 @@ private module FabricV2 { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `fabric.connection.Connection`. + * A source of instances of `fabric.connection.Connection`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function + * This can include instantiations of the class, return values from function * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `Connection::instance()` predicate to get references to instances of `fabric.connection.Connection`. + * Use the predicate `Connection::instance()` to get references to instances of `fabric.connection.Connection`. */ abstract class InstanceSource extends DataFlow::Node { } @@ -457,7 +457,7 @@ private module FabricV2 { */ module Group { /** - * A source of an instance of a subclass of `fabric.group.Group` + * A source of instances of a subclass of `fabric.group, extend this class to model new instances.Group` * * This can include instantiation of a class, return value from function * calls, or a special parameter that will be set when functions are called by an external diff --git a/python/ql/src/semmle/python/frameworks/Flask.qll b/python/ql/src/semmle/python/frameworks/Flask.qll index 571ec05f7382..3a420312be2f 100644 --- a/python/ql/src/semmle/python/frameworks/Flask.qll +++ b/python/ql/src/semmle/python/frameworks/Flask.qll @@ -97,13 +97,13 @@ private module FlaskModel { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `flask.Flask`. + * A source of instances of `flask.Flask`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `Flask::instance()` predicate to get references to instances of `flask.Flask`. + * Use the predicate `Flask::instance()` to get references to instances of `flask.Flask`. */ abstract class InstanceSource extends DataFlow::Node { } @@ -207,13 +207,13 @@ private module FlaskModel { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `flask.Response`. + * A source of instances of `flask.Response`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `Response::instance()` predicate to get references to instances of `flask.Response`. + * Use the predicate `Response::instance()` to get references to instances of `flask.Response`. */ abstract class InstanceSource extends HTTP::Server::HttpResponse::Range, DataFlow::Node { } diff --git a/python/ql/src/semmle/python/frameworks/PEP249.qll b/python/ql/src/semmle/python/frameworks/PEP249.qll index c84c15281be9..1a5d888949f0 100644 --- a/python/ql/src/semmle/python/frameworks/PEP249.qll +++ b/python/ql/src/semmle/python/frameworks/PEP249.qll @@ -29,13 +29,13 @@ DataFlow::Node connect() { result = connect(DataFlow::TypeTracker::end()) } */ module Connection { /** - * A source of an instance of `db.Connection`. + * A source of instances of `db.Connection`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function + * This can include instantiations of the class, return values from function * calls, or a special parameter that will be set when functions are called by external * libraries. * - * Use `Connection::instance()` predicate to get references to instances of `db.Connection`. + * Use the predicate `Connection::instance()` to get references to instances of `db.Connection`. * * Extend this class if the module implementing PEP 249 offers more direct ways to obtain * a connection than going through `connect`. diff --git a/python/ql/src/semmle/python/frameworks/Stdlib.qll b/python/ql/src/semmle/python/frameworks/Stdlib.qll index 246f6ba2545c..8840e1bba603 100644 --- a/python/ql/src/semmle/python/frameworks/Stdlib.qll +++ b/python/ql/src/semmle/python/frameworks/Stdlib.qll @@ -1116,13 +1116,13 @@ private module Stdlib { DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) } /** - * A source of an instance of `cgi.FieldStorage`. + * A source of instances of `cgi.FieldStorage`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `FieldStorage::instance()` predicate to get references to instances of `cgi.FieldStorage`. + * Use the predicate `FieldStorage::instance()` to get references to instances of `cgi.FieldStorage`. */ abstract class InstanceSource extends DataFlow::Node { } @@ -1569,13 +1569,13 @@ private module Stdlib { } /** - * A source of an instance of the `BaseHTTPRequestHandler` class or any subclass. + * A source of instances of the `BaseHTTPRequestHandler` class or any subclass, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `classname::instance()` predicate to get references to instances of the `BaseHTTPRequestHandler` class or any subclass. + * Use the predicate `classname::instance()` to get references to instances of the `BaseHTTPRequestHandler` class or any subclass. */ abstract class InstanceSource extends DataFlow::Node { } diff --git a/python/ql/src/semmle/python/frameworks/Werkzeug.qll b/python/ql/src/semmle/python/frameworks/Werkzeug.qll index 0e1c80629c5a..172c94682521 100644 --- a/python/ql/src/semmle/python/frameworks/Werkzeug.qll +++ b/python/ql/src/semmle/python/frameworks/Werkzeug.qll @@ -24,13 +24,13 @@ module Werkzeug { */ module MultiDict { /** - * A source of an instance of `werkzeug.datastructures.MultiDict`. + * A source of instances of `werkzeug.datastructures.MultiDict`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function - * calls, or a special parameter that will be set when functions are call by external + * This can include instantiations of the class, return values from function + * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `MultiDict::instance()` predicate to get references to instances of `werkzeug.datastructures.MultiDict`. + * Use the predicate `MultiDict::instance()` to get references to instances of `werkzeug.datastructures.MultiDict`. */ abstract class InstanceSource extends DataFlow::Node { } @@ -72,13 +72,13 @@ module Werkzeug { */ module FileStorage { /** - * A source of an instance of `werkzeug.datastructures.FileStorage`. + * A source of instances of `werkzeug.datastructures.FileStorage`, extend this class to model new instances. * - * This can include instantiation of the class, return value from function + * This can include instantiations of the class, return values from function * calls, or a special parameter that will be set when functions are called by an external * library. * - * Use `FileStorage::instance()` predicate to get references to instances of `werkzeug.datastructures.FileStorage`. + * Use the predicate `FileStorage::instance()` to get references to instances of `werkzeug.datastructures.FileStorage`. */ abstract class InstanceSource extends DataFlow::Node { }