Deprecate state point backup files.

changelog.txt

@@ -7,6 +7,14 @@ The **signac** package follows `semantic versioning <https://semver.org/>`_.
 Version 1
 =========
 
+[1.8.0] -- 2021-xx-xx
+---------------------
+
+Deprecated
+++++++++++
+
+ - ``Project`` methods ``read_statepoints``, ``write_statepoints``, and ``dump_statepoints`` are deprecated (#579, #197).
+
 [1.7.0] -- 2021-06-08
 ---------------------
 

signac/contrib/project.py

@@ -233,6 +233,8 @@ class Project:
     KEY_DATA = "signac_data"
     "The project's datastore key."
 
+    # Remove in signac 2.0.
+    # State point backup files are being removed in favor of Project.update_cache().
     FN_STATEPOINTS = "signac_statepoints.json"
     "The default filename to read from and write state points to."
 
@@ -1195,6 +1197,12 @@ def to_dataframe(self, *args, **kwargs):
         """
         return self.find_jobs().to_dataframe(*args, **kwargs)
 
+    @deprecated(
+        deprecated_in="1.8",
+        removed_in="2.0",
+        current_version=__version__,
+        details="State point backup files are being removed in favor of Project.update_cache().",
+    )
     def read_statepoints(self, fn=None):
         """Read all state points from a file.
 
@@ -1221,6 +1229,12 @@ def read_statepoints(self, fn=None):
         with open(fn) as file:
             return json.loads(file.read())
 
+    @deprecated(
+        deprecated_in="1.8",
+        removed_in="2.0",
+        current_version=__version__,
+        details="State point backup files are being removed in favor of Project.update_cache().",
+    )
     def dump_statepoints(self, statepoints):
         """Dump the state points and associated job ids.
 
@@ -1244,6 +1258,12 @@ def dump_statepoints(self, statepoints):
         """
         return {calc_id(sp): sp for sp in statepoints}
 
+    @deprecated(
+        deprecated_in="1.8",
+        removed_in="2.0",
+        current_version=__version__,
+        details="State point backup files are being removed in favor of Project.update_cache().",
+    )
     def write_statepoints(self, statepoints=None, fn=None, indent=2):
         """Dump state points to a file.
 
@@ -1376,6 +1396,10 @@ def _get_statepoint(self, job_id, fn=None):
             except KeyError as error:
                 # Fall back to a file containing all state points because the state
                 # point could not be read from the job workspace.
+                #
+                # In signac 2.0, Project.read_statepoints will be removed.
+                # Update this code path to "raise error" and update the method
+                # documentation accordingly.
                 try:
                     statepoints = self.read_statepoints(fn=fn)
                     # Update the project's state point cache
@@ -1847,6 +1871,9 @@ def check(self):
             )
             raise JobsCorruptedError(corrupted)
 
+    # State point backup files are being removed in favor of Project.update_cache().
+    # Change this method in signac 2.0 to use the state point cache by default
+    # instead of FN_STATEPOINTS.
     def repair(self, fn_statepoints=None, index=None, job_ids=None):
         """Attempt to repair the workspace after it got corrupted.
 
@@ -1876,6 +1903,10 @@ def repair(self, fn_statepoints=None, index=None, job_ids=None):
         self._read_cache()
         try:
             # Updates the state point cache from the provided file
+            #
+            # In signac 2.0, Project.read_statepoints will be removed.
+            # Remove this code path (only use "self._read_cache()" above) and
+            # update the method signature and docs to remove "fn_statepoints."
             self._sp_cache.update(self.read_statepoints(fn=fn_statepoints))
         except OSError as error:
             if error.errno != errno.ENOENT or fn_statepoints is not None: