Add type hints and docstrings

depicts/barnesfoundation.py

@@ -1,32 +1,51 @@
-import requests
-import os
+"""Barnes Foundation (Q808462) - art museum in Philadephia, Pennsylvania."""
+
 import json
+import os
+import typing
 
-def get_json(catalog_id):
-    filename = f'cache/barnesfoundation_{catalog_id}.html'
+import requests
 
-    url = 'https://collection.barnesfoundation.org/api/search'
+from .type import CatalogDict
 
-    body = {"query": {"bool": {"filter": {"exists": {"field": "imageSecret"}},
-                               "must": {"match": {"_id": int(catalog_id)}}}}}
+JsonData = dict[str, dict[str, typing.Any]]
 
-    if os.path.exists(filename):
-        return json.load(open(filename))
-    else:
-        r = requests.get(url, params={'body': json.dumps(body)})
-        print(r.url)
-        open(filename, 'w').write(r.text)
-        return r.json()
 
-def parse_catalog(data):
-    hit = data['hits']['hits'][0]['_source']
+def get_json(catalog_id: str | int) -> JsonData:
+    """Get JSON from website and cache."""
+    filename = f"cache/barnesfoundation_{catalog_id}.html"
 
-    return {
-        'institution': 'Barnes Foundation',
-        'description': hit['shortDescription'],
-        'keywords': [tag['tag'] for tag in hit['tags']],
+    url = "https://collection.barnesfoundation.org/api/search"
+
+    body = {
+        "query": {
+            "bool": {
+                "filter": {"exists": {"field": "imageSecret"}},
+                "must": {"match": {"_id": int(catalog_id)}},
+            }
+        }
     }
 
-def get_catalog(catalog_id):
+    if os.path.exists(filename):
+        return typing.cast(JsonData, json.load(open(filename)))
+    r = requests.get(url, params={"body": json.dumps(body)})
+    print(r.url)
+    open(filename, "w").write(r.text)
+    return typing.cast(JsonData, r.json())
+
+
+def parse_catalog(data: JsonData) -> CatalogDict:
+    """Parse catalog JSON."""
+    hit = data["hits"]["hits"][0]["_source"]
+
+    return {
+        "institution": "Barnes Foundation",
+        "description": hit["shortDescription"],
+        "keywords": [tag["tag"] for tag in hit["tags"]],
+    }
+
+
+def get_catalog(catalog_id: str | int) -> CatalogDict:
+    """Lookup artwork using catalog ID and return keywords."""
     data = get_json(catalog_id)
     return parse_catalog(data)