Python: Explain the funky logic in Find.ql

python/ql/src/meta/ClassHierarchy/Find.ql

@@ -478,6 +478,19 @@ predicate fullyQualifiedToYamlFormat(string fullyQualified, string type2, string
 from FindSubclassesSpec spec, string newModelFullyQualified, string type2, string path, Module mod
 where
   newModel(spec, newModelFullyQualified, _, mod, _) and
+  // Since a class C which is a subclass for flask.MethodView is always a subclass of
+  // flask.View, and we chose to care about this distinction, in a naive approach we
+  // would always record rows for _both_ specs... that's just wasteful, so instead we
+  // only record the row for the more specific spec -- this is captured by the
+  // .getSuperClass() method on a spec, which can links specs together in this way.
+  // However, if the definition actually depends on some logic, like below, we should
+  // still record both rows
+  // ```
+  // if <cond>:
+  //     class C(flask.View): ...
+  // else:
+  //     class C(flask.MethodView): ...
+  // ```
   not exists(FindSubclassesSpec subclass | subclass.getSuperClass() = spec |
     newModel(subclass, newModelFullyQualified, _, mod, _)
   ) and

python/ql/test/experimental/library-tests/FindSubclass/Find.expected

@@ -1,3 +1,4 @@
+| flask.MethodView~Subclass | find_subclass_test | Member[C] |
 | flask.MethodView~Subclass | find_subclass_test | Member[MethodView] |
 | flask.MethodView~Subclass | find_subclass_test | Member[clash] |
 | flask.View~Subclass | find_subclass_test | Member[A] |

python/ql/test/experimental/library-tests/FindSubclass/find_subclass_test.py

@@ -1,4 +1,5 @@
 from flask.views import View
+import flask.views
 
 class A(View):
     pass
@@ -6,6 +7,8 @@ class A(View):
 class B(A):
     pass
 
+class C(flask.views.MethodView):
+    pass
 
 ViewAlias = View