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.

3 files changed, 21 insertions, 9 deletions

diff --git a/python/fatcat_tools/transforms/csl.py b/python/fatcat_tools/transforms/csl.py
index 2b39068a..03410ffb 100644
--- a/python/fatcat_tools/transforms/csl.py
+++ b/python/fatcat_tools/transforms/csl.py
@@ -1,4 +1,5 @@
 import json
+from typing import Any, Dict, List
 
 from citeproc import (
     Citation,
@@ -9,20 +10,21 @@ from citeproc import (
 )
 from citeproc.source.json import CiteProcJSON
 from citeproc_styles import get_style_filepath
+from fatcat_openapi_client import ReleaseContrib, ReleaseEntity
 
 
-def contribs_by_role(contribs, role):
+def contribs_by_role(contribs: List[ReleaseContrib], role: str) -> List[ReleaseContrib]:
     ret = [c.copy() for c in contribs if c["role"] == role]
     [c.pop("role") for c in ret]
     # TODO: some note to self here
     [c.pop("literal") for c in ret if "literal" in c]
     if not ret:
-        return None
+        return []
     else:
         return ret
 
 
-def release_to_csl(entity):
+def release_to_csl(entity: ReleaseEntity) -> Dict[str, Any]:
     """
     Returns a python dict which can be json.dumps() to get a CSL-JSON (aka,
     citeproc-JSON, aka Citation Style Language JSON)
@@ -188,9 +190,9 @@ def release_to_csl(entity):
     return csl
 
 
-def refs_to_csl(entity):
+def refs_to_csl(entity: ReleaseEntity) -> List[Dict[str, Any]]:
     ret = []
-    for ref in entity.refs:
+    for ref in entity.refs or []:
         if ref.release_id and False:
             # TODO: fetch full entity from API and convert with release_to_csl
             raise NotImplementedError
@@ -207,7 +209,7 @@ def refs_to_csl(entity):
     return ret
 
 
-def citeproc_csl(csl_json, style, html=False):
+def citeproc_csl(csl_json: Dict[str, Any], style: str, html: bool = False) -> str:
     """
     Renders a release entity to a styled citation.
 
diff --git a/python/fatcat_tools/transforms/entities.py b/python/fatcat_tools/transforms/entities.py
index ee4017d8..e5da633f 100644
--- a/python/fatcat_tools/transforms/entities.py
+++ b/python/fatcat_tools/transforms/entities.py
@@ -36,7 +36,9 @@ def entity_from_json(
     return api_client.deserialize(thing, entity_type)
 
 
-def entity_from_dict(obj: Mapping[str, Any], entity_type, api_client=None):
+def entity_from_dict(
+    obj: Mapping[str, Any], entity_type: Any, api_client: Optional[ApiClient] = None
+) -> Any:
     json_str = json.dumps(obj)
     return entity_from_json(json_str, entity_type, api_client=api_client)
 
diff --git a/python/fatcat_tools/transforms/ingest.py b/python/fatcat_tools/transforms/ingest.py
index 30b5b190..cbf9e9bf 100644
--- a/python/fatcat_tools/transforms/ingest.py
+++ b/python/fatcat_tools/transforms/ingest.py
@@ -1,4 +1,8 @@
-INGEST_TYPE_CONTAINER_MAP = {
+from typing import Any, Dict, Optional
+
+from fatcat_openapi_client import ReleaseEntity
+
+INGEST_TYPE_CONTAINER_MAP: Dict[str, str] = {
     # Optica
     "twtpsm6ytje3nhuqfu3pa7ca7u": "html",
     # Optics Express
@@ -14,7 +18,11 @@ INGEST_TYPE_CONTAINER_MAP = {
 }
 
 
-def release_ingest_request(release, ingest_request_source="fatcat", ingest_type=None):
+def release_ingest_request(
+    release: ReleaseEntity,
+    ingest_request_source: str = "fatcat",
+    ingest_type: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
     """
     Takes a full release entity object and returns an ingest request (as dict),
     or None if it seems like this release shouldn't be ingested.