typing: first batch of python bulk type annotations

While these changes are more delicate than simple lint changes, this
specific batch of edits and annotations was *relatively* simple, and
resulted in few code changes other than function signature additions.

1 files changed, 64 insertions, 23 deletions

diff --git a/python/fatcat_tools/reviewers/review_common.py b/python/fatcat_tools/reviewers/review_common.py
index 59ff1c4e..d599b31f 100644
--- a/python/fatcat_tools/reviewers/review_common.py
+++ b/python/fatcat_tools/reviewers/review_common.py
@@ -5,6 +5,7 @@ from collections import Counter
 from typing import Any, List, Optional
 
 import fatcat_openapi_client
+from fatcat_openapi_client import ApiClient, Editgroup, EditgroupAnnotation, EntityEdit
 
 """
 checks should return:
@@ -29,7 +30,13 @@ class CheckResult:
     rev = None
     check_type = None
 
-    def __init__(self, status, check_type=None, description=None, **kwargs):
+    def __init__(
+        self,
+        status: str,
+        check_type: Optional[str] = None,
+        description: Optional[str] = None,
+        **kwargs
+    ):
         self.status = status
         self.check_type = check_type
         self.description = description
@@ -45,36 +52,64 @@ class EditCheck:
     scope: List[Any] = []
     name: Optional[str] = None
 
-    def check_editgroup(self, editgroup):
+    def check_editgroup(self, editgroup: fatcat_openapi_client.Editgroup) -> CheckResult:
         raise NotImplementedError
 
-    def check_container(self, edit, entity):
+    def check_container(
+        self,
+        edit: EntityEdit,
+        entity: fatcat_openapi_client.ContainerEntity,
+    ) -> CheckResult:
         raise NotImplementedError
 
-    def check_creator(self, edit, entity):
+    def check_creator(
+        self,
+        edit: EntityEdit,
+        entity: fatcat_openapi_client.CreatorEntity,
+    ) -> CheckResult:
         raise NotImplementedError
 
-    def check_file(self, edit, entity):
+    def check_file(
+        self,
+        edit: EntityEdit,
+        entity: fatcat_openapi_client.FileEntity,
+    ) -> CheckResult:
         raise NotImplementedError
 
-    def check_fileset(self, edit, entity):
+    def check_fileset(
+        self,
+        edit: EntityEdit,
+        entity: fatcat_openapi_client.FilesetEntity,
+    ) -> CheckResult:
         raise NotImplementedError
 
-    def check_webcapture(self, edit, entity):
+    def check_webcapture(
+        self,
+        edit: EntityEdit,
+        entity: fatcat_openapi_client.WebcaptureEntity,
+    ) -> CheckResult:
         raise NotImplementedError
 
-    def check_release(self, edit, entity):
+    def check_release(
+        self,
+        edit: EntityEdit,
+        entity: fatcat_openapi_client.ReleaseEntity,
+    ) -> CheckResult:
         raise NotImplementedError
 
-    def check_work(self, edit, work):
+    def check_work(
+        self,
+        edit: EntityEdit,
+        work: fatcat_openapi_client.WorkEntity,
+    ) -> CheckResult:
         raise NotImplementedError
 
 
 class ReviewBot:
-    def __init__(self, api, verbose=False, **kwargs):
+    def __init__(self, api: fatcat_openapi_client.ApiClient, verbose: bool = False, **kwargs):
 
         self.api = api
-        self.checks = []
+        self.checks: List[EditCheck] = []
         self.verbose = verbose
         self.extra = kwargs.get("extra", dict())
         self.extra["git_rev"] = self.extra.get(
@@ -83,16 +118,18 @@ class ReviewBot:
         self.extra["agent"] = self.extra.get("agent", "fatcat_tools.ReviewBot")
         self.poll_interval = kwargs.get("poll_interval", 10.0)
 
-    def run_single(self, editgroup_id, annotate=True):
+    def run_single(self, editgroup_id: str, annotate: bool = True) -> CheckResult:
         eg = self.api.get_editgroup(editgroup_id)
         annotation = self.review_editgroup(eg)
         if annotate:
             self.api.create_editgroup_annotation(eg.editgroup_id, annotation)
         return annotation
 
-    def run(self, since=None):
-        if since is None:
+    def run(self, start_since: Optional[datetime.datetime] = None) -> None:
+        if start_since is None:
             since = datetime.datetime.utcnow()
+        else:
+            since = start_since
         while True:
             # XXX: better isoformat conversion?
             eg_list = self.api.get_editgroups_reviewable(
@@ -116,7 +153,7 @@ class ReviewBot:
             # editgroups in the same second)
             since = since + datetime.timedelta(seconds=1)
 
-    def review_editgroup(self, editgroup):
+    def review_editgroup(self, editgroup: Editgroup) -> EditgroupAnnotation:
         results = self.run_checks(editgroup)
         result_counts = self.result_counts(results)
         disposition = self.disposition(results)
@@ -159,20 +196,20 @@ class ReviewBot:
         )
         return annotation
 
-    def result_counts(self, results):
-        counts = Counter()
+    def result_counts(self, results: List[CheckResult]) -> Counter:
+        counts: Counter = Counter()
         for result in results:
             counts["total"] += 1
             counts[result.status] += 1
         return counts
 
-    def disposition(self, results):
+    def disposition(self, results: List[CheckResult]) -> str:
         """
         Returns one of: accept, revise, reject
         """
         raise NotImplementedError
 
-    def run_checks(self, editgroup):
+    def run_checks(self, editgroup: Editgroup) -> List[CheckResult]:
 
         results = []
 
@@ -222,7 +259,7 @@ class DummyCheck(EditCheck):
     scope = ["editgroup", "work"]
     name = "DummyCheck"
 
-    def check_editgroup(self, editgroup):
+    def check_editgroup(self, editgroup: Editgroup) -> CheckResult:
         return CheckResult(
             "pass",
             "editgroup",
@@ -231,7 +268,11 @@ class DummyCheck(EditCheck):
             ),
         )
 
-    def check_work(self, entity, edit):
+    def check_work(
+        self,
+        edit: EntityEdit,
+        work: fatcat_openapi_client.WorkEntity,
+    ) -> CheckResult:
         return CheckResult("pass", "work", "this work edit is beautiful")
 
 
@@ -240,9 +281,9 @@ class DummyReviewBot(ReviewBot):
     This bot reviews everything and always passes.
     """
 
-    def __init__(self, api, **kwargs):
+    def __init__(self, api: ApiClient, **kwargs):
         super().__init__(api, **kwargs)
         self.checks = [DummyCheck()]
 
-    def disposition(self, results):
+    def disposition(self, results: List[CheckResult]) -> str:
         return "accept"