Clarify usage of the elements cache

Author: PeterJCLaw

scripts/element_tracking.py

@@ -14,6 +14,15 @@
 
 
 class ElementsCache:
+    """
+    Load and cache the tasks that have been created in a file.
+
+    Use like:
+    ```
+    with ElementsCache(Path('cache.json')) as elements:
+        elements['key'] = 14
+    """
+
     def __init__(self, cache_path: Path) -> None:
         self.cache_path = cache_path
         self.elements: Dict[str, int] = {}
@@ -23,7 +32,7 @@ def __init__(self, cache_path: Path) -> None:
         except IOError:
             pass
 
-    def __enter__(self) -> Dict[str, int]:
+    def __enter__(self) -> MutableMapping[str, int]:
         return self.elements
 
     def __exit__(

scripts/import.py

@@ -3,7 +3,7 @@
 import argparse
 import contextlib
 from pathlib import Path
-from typing import TYPE_CHECKING, Callable, Dict, MutableMapping, Optional
+from typing import TYPE_CHECKING, Callable, MutableMapping, Optional
 
 import yaml
 from element_tracking import ElementsCache, ElementsInProgress
@@ -156,11 +156,11 @@ def main(arguments: argparse.Namespace) -> None:
 
     with contextlib.ExitStack() as stack:
         if arguments.cache:
-            elements: Optional[Dict[str, int]] = stack.enter_context(
+            elements: MutableMapping[str, int] = stack.enter_context(
                 ElementsCache(arguments.cache),
             )
         else:
-            elements = None
+            elements = {}
 
         add(arguments.base, backend, arguments.year, known_elements=elements)