chore: strict annotations

We annotate the entire codebase to support `--strict` mode in mypy.

Author: regisb

.gitignore

@@ -75,3 +75,5 @@ default.db
 # Generated reports and test reports
 reports/*
 test_reports/*
+
+**/.claude/settings.local.json

Makefile

@@ -77,7 +77,7 @@ test: clean ## run tests in the current virtualenv
 	pytest
 
 test-types: ## run mypy tests on the whole codebase
-	mypy --ignore-missing-imports code_annotations/ tests/ test_utils/ setup.py
+	mypy --ignore-missing-imports --strict code_annotations/ tests/ test_utils/ setup.py
 
 diff_cover: test ## find diff lines that need test coverage
 	diff-cover coverage.xml

code_annotations/annotation_errors.py

@@ -2,17 +2,19 @@
 List possible annotation error types.
 """
 from collections import namedtuple
+import typing as t
 
 AnnotationError = namedtuple(
     "AnnotationError", ["message", "symbol", "description"]
 )
 
 # The TYPES list should contain all AnnotationError instances. This list can then be parsed by others, for instance
 # to expose errors to pylint.
-TYPES = []
+TYPES: list[AnnotationError] = []
 
+T = t.TypeVar('T', bound=AnnotationError)
 
-def add_error_type(message, symbol, description):
+def add_error_type(message: str, symbol: str, description: str) -> AnnotationError:
     """
     Create an AnnotationError instance and add it to TYPES.
     """
@@ -32,32 +34,32 @@ def add_error_type(message, symbol, description):
 # It is important to preserve the insertion order of these error types in the TYPES list, as edx-lint uses the error
 # type indices to generate numerical pylint IDs. If the insertion order is changed, the pylint IDs will change too,
 # which might cause incompatibilities down the road. Thus, new items should be added at the end.
-InvalidChoice = add_error_type(
+InvalidChoice: AnnotationError = add_error_type(
     '"%s" is not a valid choice for "%s". Expected one of %s.',
     "annotation-invalid-choice",
     "Emitted when the value of a choice field is not one of the valid choices",
 )
-DuplicateChoiceValue = add_error_type(
+DuplicateChoiceValue: AnnotationError = add_error_type(
     '"%s" is already present in this annotation.',
     "annotation-duplicate-choice-value",
     "Emitted when duplicate values are found in a choice field",
 )
-MissingChoiceValue = add_error_type(
+MissingChoiceValue: AnnotationError = add_error_type(
     'no value found for "%s". Expected one of %s.',
     "annotation-missing-choice-value",
     "Emitted when a choice field does not have any value",
 )
-InvalidToken = add_error_type(
+InvalidToken: AnnotationError = add_error_type(
     "'%s' token does not belong to group '%s'. Expected one of: %s",
     "annotation-invalid-token",
     "Emitted when a token is found in a group for which it is not valid",
 )
-DuplicateToken = add_error_type(
+DuplicateToken: AnnotationError = add_error_type(
     "found duplicate token '%s'",
     "annotation-duplicate-token",
     "Emitted when a token is found twice in a group",
 )
-MissingToken = add_error_type(
+MissingToken: AnnotationError = add_error_type(
     "missing non-optional annotation: '%s'",
     "annotation-missing-token",
     "Emitted when a required token is missing from a group",

code_annotations/helpers.py

@@ -4,13 +4,14 @@
 import os
 import re
 import sys
+import typing as t
 from io import StringIO
 from pprint import pprint
 
 import click
 
 
-def fail(msg):
+def fail(msg: str) -> t.NoReturn:
     """
     Log the message and exit.
 
@@ -26,9 +27,9 @@ class VerboseEcho:
     Helper to handle verbosity-dependent logging.
     """
 
-    verbosity = 1
+    verbosity: int = 1
 
-    def __call__(self, output, **kwargs):
+    def __call__(self, output: str, **kwargs: t.Any) -> None:
         """
         Echo the given output regardless of verbosity level.
 
@@ -40,18 +41,17 @@ def __call__(self, output, **kwargs):
         """
         self.echo(output, **kwargs)
 
-    def set_verbosity(self, verbosity):
+    def set_verbosity(self, verbosity: int) -> None:
         """
         Override the default verbosity level.
 
         Args:
             verbosity: The verbosity level to set to
-            kwargs: Any additional keyword args to pass to click.echo
         """
         self.verbosity = verbosity
         self.echo_v(f"Verbosity level set to {verbosity}")
 
-    def echo(self, output, verbosity_level=0, **kwargs):
+    def echo(self, output: str, verbosity_level: int = 0, **kwargs: t.Any) -> None:
         """
         Echo the given output, if over the verbosity threshold.
 
@@ -63,7 +63,7 @@ def echo(self, output, verbosity_level=0, **kwargs):
         if verbosity_level <= self.verbosity:
             click.secho(output, **kwargs)
 
-    def echo_v(self, output, **kwargs):
+    def echo_v(self, output: str, **kwargs: t.Any) -> None:
         """
         Echo the given output if verbosity level is >= 1.
 
@@ -73,7 +73,7 @@ def echo_v(self, output, **kwargs):
         """
         self.echo(output, 1, **kwargs)
 
-    def echo_vv(self, output, **kwargs):
+    def echo_vv(self, output: str, **kwargs: t.Any) -> None:
         """
         Echo the given output if verbosity level is >= 2.
 
@@ -83,7 +83,7 @@ def echo_vv(self, output, **kwargs):
         """
         self.echo(output, 2, **kwargs)
 
-    def echo_vvv(self, output, **kwargs):
+    def echo_vvv(self, output: str, **kwargs: t.Any) -> None:
         """
         Echo the given output if verbosity level is >= 3.
 
@@ -93,7 +93,7 @@ def echo_vvv(self, output, **kwargs):
         """
         self.echo(output, 3, **kwargs)
 
-    def pprint(self, data, indent=4, verbosity_level=0):
+    def pprint(self, data: t.Any, indent: int = 4, verbosity_level: int = 0) -> None:
         """
         Pretty-print some data with the given verbosity level.
         """
@@ -103,7 +103,7 @@ def pprint(self, data, indent=4, verbosity_level=0):
         self.echo(formatted.read(), verbosity_level=verbosity_level)
 
 
-def clean_abs_path(filename_to_clean, parent_path):
+def clean_abs_path(filename_to_clean: str, parent_path: str) -> str:
     """
     Safely strips the parent path from the given filename, leaving only the relative path.
 
@@ -121,7 +121,7 @@ def clean_abs_path(filename_to_clean, parent_path):
     return os.path.relpath(filename_to_clean, parent_path)
 
 
-def get_annotation_regex(annotation_regexes):
+def get_annotation_regex(annotation_regexes: list[str]) -> t.Pattern[str]:
     """
     Return the full regex to search inside comments for configured annotations.
 
@@ -166,7 +166,7 @@ def get_annotation_regex(annotation_regexes):
     return re.compile(annotation_regex, flags=re.VERBOSE)
 
 
-def clean_annotation(token, data):
+def clean_annotation(token: str, data: str) -> tuple[str, str]:
     """
     Clean annotation token and data by stripping all trailing/prefix empty spaces.
 

setup.py

@@ -10,7 +10,7 @@
 from setuptools import setup
 
 
-def get_version(*file_paths):
+def get_version(*file_paths: str) -> str:
     """
     Extract the version string from the file at the given relative path fragments.
     """
@@ -22,14 +22,14 @@ def get_version(*file_paths):
     raise RuntimeError("Unable to find version string.")
 
 
-def load_requirements(*requirements_paths):
+def load_requirements(*requirements_paths: str) -> list[str]:
     """
     Load all requirements from the specified requirements files.
 
     Returns:
         list: Requirements file relative path strings
     """
-    requirements = set()
+    requirements: set[str] = set()
     for path in requirements_paths:
         requirements.update(
             line.split("#")[0].strip()
@@ -39,7 +39,7 @@ def load_requirements(*requirements_paths):
     return list(requirements)
 
 
-def is_requirement(line):
+def is_requirement(line: str) -> bool:
     """
     Return True if the requirement line is a package requirement.