Rename statepoint_mapping to cached_statepoint.

Also attempt to fix sphinx-doc links.

signac/job.py

@@ -292,7 +292,7 @@ def __init__(self, project, statepoint=None, id_=None, directory_known=False):
             except TypeError:
                 raise KeyTypeError
 
-            self._statepoint_mapping = statepoint
+            self._cached_statepoint = statepoint
             self._statepoint_requires_init = True
         else:
             # Only an id was provided. State point will be loaded lazily.
@@ -302,9 +302,9 @@ def __init__(self, project, statepoint=None, id_=None, directory_known=False):
             # Fetch the statepoint mapping from the project's cache. Don't load it
             # from disk on a cache miss (will be loaded on demand).
             try:
-                self._statepoint_mapping = project._sp_cache[id_]
+                self._cached_statepoint = project._sp_cache[id_]
             except KeyError:
-                self._statepoint_mapping = None
+                self._cached_statepoint = None
 
     def _initialize_lazy_properties(self):
         """Initialize all properties that are designed to be loaded lazily."""
@@ -342,7 +342,7 @@ def __str__(self):
 
     def __repr__(self):
         return "{}(project={}, statepoint={})".format(
-            self.__class__.__name__, repr(self._project), self.statepoint_mapping
+            self.__class__.__name__, repr(self._project), self.cached_statepoint
         )
 
     @property
@@ -415,30 +415,31 @@ def update_statepoint(self, update, overwrite=False):
         self.statepoint = statepoint
 
     @property
-    def statepoint_mapping(self):
+    def cached_statepoint(self):
         """Get a copy of the job's statepoint as a read-only mapping.
 
-        `statepoint_mapping` uses the statepoint cache to provide fast access to the
-        job's statepoint for reading.
+        :py:attr:`cached_statepoint` uses the statepoint cache to provide fast access to
+        the job's statepoint for reading.
 
         .. note::
 
-            Create and update the statepoint cache with ``signac update-cache`` on the
+            Create and update the statepoint cache by calling
+            :py:meth:`Project.update_cache` or running``signac update-cache`` on the
             command line.
 
         .. seealso::
 
-            Use `statepoint` to modify the job's statepoint.
+            Use :py:attr:`statepoint` to modify the job's statepoint.
 
         Returns
         -------
         Mapping
             Returns the job's state point.
         """
-        if self._statepoint_mapping is None:
-            self._statepoint_mapping = self._project._get_statepoint(self._id)
+        if self._cached_statepoint is None:
+            self._cached_statepoint = self._project._get_statepoint(self._id)
 
-        return MappingProxyType(self._statepoint_mapping)
+        return MappingProxyType(self._cached_statepoint)
 
     @property
     def statepoint(self):
@@ -452,7 +453,7 @@ def statepoint(self):
 
         .. tip::
 
-            Use `statepoint_mapping` for faster access to read the statepoint.
+            Use :py:attr:`cached_statepoint` for fast access to read the statepoint.
 
         .. warning::
 
@@ -481,7 +482,7 @@ def statepoint(self):
         """
         with self._lock:
             if self._statepoint_requires_init:
-                if self._statepoint_mapping is None:
+                if self._cached_statepoint is None:
                     # Load state point data lazily (on access).
                     self._statepoint = _StatePointDict(
                         jobs=[self],
@@ -491,13 +492,13 @@ def statepoint(self):
 
                     # Update the project's state point cache when loaded lazily
                     self._project._register(self.id, statepoint)
-                    self._statepoint_mapping = statepoint
+                    self._cached_statepoint = statepoint
                 else:
                     # Create _StatePointDict lazily with a known statepoint dict.
                     self._statepoint = _StatePointDict(
                         jobs=[self],
                         filename=self._statepoint_filename,
-                        data=self._statepoint_mapping,
+                        data=self._cached_statepoint,
                     )
 
                 self._statepoint_requires_init = False

tests/test_job.py

@@ -492,26 +492,26 @@ class A:
             with pytest.raises(TypeError):
                 job.doc = {key: "test"}
 
-    def test_statepoint_mapping_read_only(self):
+    def test_cached_statepoint_read_only(self):
         statepoint = {"a": 0, "b": 1, "dict": {"value": "string"}}
         job = self.open_job(statepoint=statepoint)
         job.init()
 
-        assert "a" in job.statepoint_mapping
-        assert "b" in job.statepoint_mapping
-        assert "c" not in job.statepoint_mapping
-        assert "dict" in job.statepoint_mapping
-        assert job.statepoint_mapping["a"] == 0
-        assert job.statepoint_mapping["b"] == 1
-        assert job.statepoint_mapping["dict"] == {"value": "string"}
+        assert "a" in job.cached_statepoint
+        assert "b" in job.cached_statepoint
+        assert "c" not in job.cached_statepoint
+        assert "dict" in job.cached_statepoint
+        assert job.cached_statepoint["a"] == 0
+        assert job.cached_statepoint["b"] == 1
+        assert job.cached_statepoint["dict"] == {"value": "string"}
         with pytest.raises(KeyError):
-            job.statepoint_mapping["c"]
-        assert list(job.statepoint_mapping.keys()) == ["a", "b", "dict"]
+            job.cached_statepoint["c"]
+        assert list(job.cached_statepoint.keys()) == ["a", "b", "dict"]
 
         with pytest.raises(TypeError):
-            job.statepoint_mapping["c"] = 2
+            job.cached_statepoint["c"] = 2
 
-    def test_statepoint_mapping_lazy_init(self):
+    def test_cached_statepoint_lazy_init(self):
         statepoint = {"a": 0}
         job = self.project.open_job(statepoint=statepoint)
         job.init()
@@ -520,7 +520,7 @@ def test_statepoint_mapping_lazy_init(self):
         # Clear the cache to force a lazy load of the statepoint mapping
         self.project._sp_cache.clear()
         job = self.project.open_job(id=id_)
-        job.statepoint_mapping
+        job.cached_statepoint
 
     def test_no_args_error(self):
         with pytest.raises(ValueError):