Terminology: rename "checkpoint" to "bookmark"

2 files changed, 29 insertions, 21 deletions

diff --git a/jimbrella/config.py b/jimbrella/config.py
index 1bde65b..77e944e 100644
--- a/jimbrella/config.py
+++ b/jimbrella/config.py
@@ -5,7 +5,7 @@ JFORM_TAKEAWAY_URL = (
 # JFORM_GIVEBACK_URL= (
 #     "https://wj.sjtu.edu.cn/api/v1/public/export/900e25bf6a039da04da7c5165a7cd41a/json"
 # )
-JFORM_CHECKPOINTS_PATH = "/home/fkfd/p/jimbrella/jform"
+JFORM_BOOKMARK_DIR = "/home/fkfd/p/jimbrella/"
 
 # database
 DATABASE_PATH = "/home/fkfd/p/jimbrella/jimbrella.db.csv"
diff --git a/jimbrella/jform.py b/jimbrella/jform.py
index dff6654..cd48c3e 100644
--- a/jimbrella/jform.py
+++ b/jimbrella/jform.py
@@ -1,5 +1,6 @@
 import requests
 import json
+from pathlib import Path
 
 
 class JForm:
@@ -10,15 +11,22 @@ class JForm:
 
     JImbrella's database relies on JForm to sync its database against jForm's.
 
-    Each JForm object requires a checkpoint file in which to store the id of the latest answer
+    Each JForm object requires a bookmark file in which to store the id of the latest answer
     sheet it has read. Each time the API detects the presence of new answer sheets, the file will
     be overwritten.
     """
 
-    def __init__(self, name: str, url: str, checkpoint_fp: str):
-        self._name = name  # internal identifier
+    def __init__(self, name: str, url: str, bookmark_dir: str):
+        """Initializes a JForm instance.
+
+        name:           Internal identifier. Must be unique.
+        url:            URL of the API endpoint jForm exposed to creators of questionnaire.
+        bookmark_dir: A directory to store bookmark files, which are named under the format
+                        "<name>.bookmark".
+        """
+        self._name = name
         self.url = url
-        self._checkpoint_fp = checkpoint_fp
+        self._bookmark_fp = Path(bookmark_dir).join(f"{name}.bookmark")
 
     def _get(self, page=1) -> dict:
         """Internal method to HTTP GET the API in JSON format."""
@@ -36,30 +44,30 @@ class JForm:
         )
         return resp
 
-    def _read_checkpoint(self) -> int:
-        """Read checkpoint file and returns contents. No safeguards."""
+    def _read_bookmark(self) -> int:
+        """Read bookmark file and returns contents. No safeguards."""
         try:
-            with open(self._checkpoint_fp) as f:
-                checkpoint = f.read()
+            with open(self._bookmark_fp) as f:
+                bookmark = f.read()
                 f.close()
-                return int(checkpoint)
+                return int(bookmark)
         except FileNotFoundError:
             return 0
 
-    def _write_checkpoint(self, checkpoint: int) -> None:
-        """Write into checkpoint file."""
+    def _write_bookmark(self, bookmark: int) -> None:
+        """Write into bookmark file."""
         try:
-            with open(self._checkpoint_fp, "x") as f:
-                f.write(str(checkpoint))
+            with open(self._bookmark_fp, "x") as f:
+                f.write(str(bookmark))
                 f.close()
         except FileExistsError:
-            with open(self._checkpoint_fp, "w") as f:
-                f.write(str(checkpoint))
+            with open(self._bookmark_fp, "w") as f:
+                f.write(str(bookmark))
                 f.close()
 
     def get_unread(self) -> list:
         """Get unread answers to required fields as a list of dicts, most recent last."""
-        checkpoint = self._read_checkpoint()
+        bookmark = self._read_bookmark()
         unread = []
         latest_id = 0
         page = 1
@@ -76,9 +84,9 @@ class JForm:
             if not latest_id:
                 # the first page of sheets we have retrieved this run.
                 # on this page, the first answer sheet is the latest.
-                # update checkpoint. next time, stop before this id.
+                # update bookmark. next time, stop before this id.
                 latest_id = sheets[0]["id"]
-                self._write_checkpoint(latest_id)
+                self._write_bookmark(latest_id)
 
             if not sheets:
                 # somehow jForm doesn't respond with a 404
@@ -86,8 +94,8 @@ class JForm:
                 # instead it just returns 200 along with an empty data field
                 break
             for sheet in sheets:
-                if sheet["id"] <= checkpoint:
-                    # is checkpoint or earlier than checkpoint
+                if sheet["id"] <= bookmark:
+                    # is bookmark or earlier than bookmark
                     found_read = True
                     break
                 ans = sheet["answers"]