style: Nits on type hints and docstrings and comments

openedx_tagging/core/tagging/api.py

@@ -89,6 +89,11 @@ def get_root_tags(taxonomy: Taxonomy) -> list[Tag]:
 
 
 def search_tags(taxonomy: Taxonomy, search_term: str) -> list[Tag]:
+    """
+    Returns a list of all tags that contains `search_term` of the given taxonomy.
+
+    Note that if the taxonomy allows free-text tags, then the returned list will be empty.
+    """
     return list(
         taxonomy.cast().get_filtered_tags(
             search_term=search_term,

openedx_tagging/core/tagging/models/base.py

@@ -330,6 +330,9 @@ def get_filtered_tags(
         Use `search_term` to filter the results by values that contains `search_term`.
 
         Set `search_in_all` to True to make the search in all tags on the given taxonomy.
+
+        Note: This is mostly an 'internal' API and generally code outside of openedx_tagging
+        should use the APIs in openedx_tagging.api which in turn use this.
         """
         if tag_set is None:
             tag_set = self.tag_set.all()
@@ -338,9 +341,11 @@ def get_filtered_tags(
             return tag_set.none()
 
         if not search_in_all:
+            # If not search in all taxonomy, then apply parent filter.
             tag_set = tag_set.filter(parent=parent_tag_id)
 
         if search_term:
+            # Apply search filter
             tag_set = tag_set.filter(value__icontains=search_term)
 
         return tag_set.order_by("value", "id")

openedx_tagging/core/tagging/rest_api/paginators.py

@@ -1,4 +1,4 @@
-from edx_rest_framework_extensions.paginators import DefaultPagination  # type: ignore
+from edx_rest_framework_extensions.paginators import DefaultPagination  # type: ignore[import]
 from rest_framework.response import Response
 
 # From this point, the tags begin to be paginated

openedx_tagging/core/tagging/rest_api/v1/permissions.py

@@ -1,7 +1,7 @@
 """
 Tagging permissions
 """
-import rules  # type: ignore
+import rules  # type: ignore[import]
 from rest_framework.permissions import DjangoObjectPermissions
 
 

openedx_tagging/core/tagging/rest_api/v1/views.py

@@ -353,7 +353,10 @@ class TaxonomyTagsView(ListAPIView):
 
     permission_classes = [TagListPermissions]
     pagination_enabled = True
-    serializer_class = TagsSerializer
+
+    def __init__(self):
+        # Initialized here to avoid errors on type hints
+        self.serializer_class = TagsSerializer
 
     def get_pagination_class(self):
         """
@@ -388,11 +391,11 @@ def _build_search_tree(self, tags: list[Tag]) -> list[Tag]:
         # Get missing parents.
         # Not all parents are in the search result.
         # This occurs when a child tag is on the search result, but its parent not,
-        # we need to add the parent to show the tree from the roor to the child.
+        # we need to add the parent to show the tree from the root to the child.
         for tag in tags:
             if tag.parent and tag.parent_id and tag.parent_id not in tag_ids:
                 tag_ids.append(tag.parent_id)
-                tags.append(tag.parent)
+                tags.append(tag.parent)  # Our loop will iterate over this new parent tag too.
 
         groups: dict[int, list[Tag]] = {}
         roots: list[Tag] = []
@@ -408,7 +411,7 @@ def _build_search_tree(self, tags: list[Tag]) -> list[Tag]:
 
         for tag in tags:
             # Used to serialize searched childrens
-            tag.sub_tags = groups.get(tag.id, [])  # type: ignore
+            tag.sub_tags = groups.get(tag.id, [])  # type: ignore[attr-defined]
 
         return roots
 
@@ -457,7 +460,7 @@ def get_matching_tags(
 
                 # Use the special serializer to only show the tree
                 # of the search result.
-                self.serializer_class = TagsForSearchSerializer  # type: ignore
+                self.serializer_class = TagsForSearchSerializer
 
                 result = self._build_search_tree(result)
             else:
@@ -475,13 +478,13 @@ def get_matching_tags(
                     # If pagination is disabled, use the special serializer
                     # to show children. In this case, we return all taxonomy tags
                     # in a tree structure.
-                    self.serializer_class = TagsWithSubTagsSerializer  # type: ignore
+                    self.serializer_class = TagsWithSubTagsSerializer
 
                 result = get_root_tags(taxonomy)
 
             return result
 
-    def get_queryset(self) -> list[Tag]:  # type: ignore
+    def get_queryset(self) -> list[Tag]:  # type: ignore[override]
         """
         Builds and returns the queryset to be paginated.
 

tests/openedx_tagging/core/tagging/test_models.py

@@ -257,11 +257,6 @@ def test_get_children_tags(self):
         assert list(
             self.taxonomy.get_filtered_tags(parent_tag_id=self.animalia.id)
         ) == self.phylum_tags
-        print(self.taxonomy.get_filtered_tags(
-                parent_tag_id=self.animalia.id,
-                search_term='dA',
-            ))
-        print(self.filtered_phylum_tags)
         assert list(
             self.taxonomy.get_filtered_tags(
                 parent_tag_id=self.animalia.id,

tests/openedx_tagging/core/tagging/test_views.py

@@ -924,14 +924,10 @@ def test_large_taxonomy(self):
         assert results[0].get("taxonomy_id") == self.large_taxonomy.id
         assert results[0].get("parent_id") == root_tag.parent_id
         assert results[0].get("children_count") == root_tag.children.count()
-        assert (
-            results[0].get("sub_tags_link")
-            ==
-            (
-                "http://testserver/tagging/"
-                f"rest_api/v1/taxonomies/{self.large_taxonomy.id}"
-                f"/tags/?parent_tag_id={root_tag.id}"
-            )
+        assert results[0].get("sub_tags_link") == (
+            "http://testserver/tagging/"
+            f"rest_api/v1/taxonomies/{self.large_taxonomy.id}"
+            f"/tags/?parent_tag_id={root_tag.id}"
         )
 
         # Checking pagination values
@@ -1060,14 +1056,10 @@ def test_get_children(self):
         assert results[0].get("taxonomy_id") == self.large_taxonomy.id
         assert results[0].get("parent_id") == tag.parent_id
         assert results[0].get("children_count") == tag.children.count()
-        assert (
-            results[0].get("sub_tags_link")
-            ==
-            (
-                "http://testserver/tagging/"
-                f"rest_api/v1/taxonomies/{self.large_taxonomy.id}"
-                f"/tags/?parent_tag_id={tag.id}"
-            )
+        assert results[0].get("sub_tags_link") == (
+            "http://testserver/tagging/"
+            f"rest_api/v1/taxonomies/{self.large_taxonomy.id}"
+            f"/tags/?parent_tag_id={tag.id}"
         )
 
         # Checking pagination values