Additional deprecations

signac/__main__.py

@@ -258,7 +258,7 @@ def main_project(args):
             print(json.dumps(doc))
         return
     if args.workspace:
-        print(project.workspace())
+        print(project.workspace)
     else:
         print(project)
 
@@ -279,6 +279,13 @@ def main_job(args):
     if args.create:
         job.init()
     if args.workspace:
+        warnings.warn(
+            "The `-w/--workspace` parameter is deprecated as of version 1.8 and will be removed in "
+            "version 2.0. Use -p/--path instead",
+            FutureWarning,
+        )
+        args.path = True
+    if args.path:
         print(job.workspace())
     else:
         print(job)
@@ -658,7 +665,7 @@ def _main_import_interactive(project, origin, args):
                     project_id=project.get_id(),
                     job_banner="",
                     root_path=project.root_directory(),
-                    workspace_path=project.workspace(),
+                    workspace_path=project.workspace,
                     size=len(project),
                     origin=args.origin,
                 ),
@@ -1169,7 +1176,7 @@ def write_history_file():
                     project_id=project.id,
                     job_banner=f"\nJob:\t\t{job.id}" if job is not None else "",
                     root_path=project.root_directory(),
-                    workspace_path=project.workspace(),
+                    workspace_path=project.workspace,
                     size=len(project),
                 ),
             )
@@ -1244,6 +1251,12 @@ def main():
         action="store_true",
         help="Print the job's workspace path instead of the job id.",
     )
+    parser_job.add_argument(
+        "-p",
+        "--path",
+        action="store_true",
+        help="Print the job's path instead of the job id.",
+    )
     parser_job.add_argument(
         "-c",
         "--create",

signac/cite.py

@@ -8,6 +8,11 @@
 
 from .version import __version__
 
+"""
+THIS MODULE IS DEPRECATED!
+"""
+
+
 ARXIV_BIBTEX = """@online{signac,
     author      = {Carl S. Adorf and Paul M. Dodd and Sharon C. Glotzer},
     title       = {signac - A Simple Data Management Framework},

signac/contrib/import_export.py

@@ -758,7 +758,7 @@ def _crawl_directory_data_space(root, project, schema_function):
 
     """
     # We compare paths to the 'realpath' of the project workspace to catch loops.
-    workspace_real_path = os.path.realpath(project.workspace())
+    workspace_real_path = os.path.realpath(project.workspace)
 
     for path, dirs, _ in os.walk(root):
         sp = schema_function(path)

signac/contrib/indexing.py

@@ -428,7 +428,7 @@ class SignacProjectCrawler(RegexFileCrawler):
     def __init__(self, root):
         from .project import get_project
 
-        root = get_project(root=root).workspace()
+        root = get_project(root=root).workspace
         self._statepoints = {}
         return super().__init__(root=root)
 

signac/contrib/job.py

@@ -103,7 +103,7 @@ def _save(self):
             # Move the state point to an intermediate location as a backup.
             os.replace(self.filename, tmp_statepoint_file)
             try:
-                new_workspace = os.path.join(job._project.workspace(), new_id)
+                new_workspace = os.path.join(job._project.workspace, new_id)
                 os.replace(job.workspace(), new_workspace)
             except OSError as error:
                 os.replace(tmp_statepoint_file, self.filename)  # rollback
@@ -281,8 +281,11 @@ def __init__(self, project, statepoint=None, _id=None):
 
     def _initialize_lazy_properties(self):
         """Initialize all properties that are designed to be loaded lazily."""
+        # TODO: Consider using functools.cached_property for these instead.  That simplify our code,
+        # although at the expense of creating multiple locks (each cached_property has its own lock
+        # AFAICT from looking at the implementation).
         with self._lock:
-            self._wd = None
+            self._path = None
             self._document = None
             self._stores = None
             self._cwd = []
@@ -335,22 +338,15 @@ def __repr__(self):
             self.__class__.__name__, repr(self._project), self.statepoint
         )
 
+    @deprecated(
+        deprecated_in="1.8",
+        removed_in="2.0",
+        current_version=__version__,
+        details="Use Job.path instead.",
+    )
     def workspace(self):
-        """Return the job's unique workspace directory.
-
-        See :ref:`signac job -w <signac-cli-job>` for the command line equivalent.
-
-        Returns
-        -------
-        str
-            The path to the job's workspace directory.
-
-        """
-        if self._wd is None:
-            # We can rely on the project workspace to be well-formed, so just
-            # use str.join with os.sep instead of os.path.join for speed.
-            self._wd = os.sep.join((self._project.workspace(), self.id))
-        return self._wd
+        """Alias for :attr:`~Job.path`."""
+        return self.path
 
     @property
     def _statepoint_filename(self):
@@ -359,11 +355,37 @@ def _statepoint_filename(self):
         # use str.join with os.sep instead of os.path.join for speed.
         return os.sep.join((self.workspace(), self.FN_MANIFEST))
 
-    @property
+    # Tell mypy to ignore type checking of the decorator because decorated
+    # properties aren't supported: https://github.com/python/mypy/issues/1362
+    @property  # type: ignore
+    @deprecated(
+        deprecated_in="1.8",
+        removed_in="2.0",
+        current_version=__version__,
+        details="Use Job.path instead.",
+    )
     def ws(self):
-        """Alias for :meth:`~Job.workspace`."""
-        return self.workspace()
+        """Alias for :attr:`~Job.path`."""
+        return self.path
 
+    @property
+    def path(self):
+        """str: The path to the job directory.
+
+        See :ref:`signac job -w <signac-cli-job>` for the command line equivalent.
+        """
+        if self._path is None:
+            # We can rely on the project workspace to be well-formed, so just
+            # use str.join with os.sep instead of os.path.join for speed.
+            self._path = os.sep.join((self._project.workspace, self.id))
+        return self._path
+
+    @deprecated(
+        deprecated_in="1.8",
+        removed_in="2.0",
+        current_version=__version__,
+        details="Use job.statepoint = new_statepoint instead.",
+    )
     def reset_statepoint(self, new_statepoint):
         """Overwrite the state point of this job while preserving job data.
 
@@ -448,7 +470,13 @@ def update_statepoint(self, update, overwrite=False):
 
     @property
     def statepoint(self):
-        """Get the job's state point.
+        """Get or set the job's state point.
+
+        Setting the state point to a different value will change the job id.
+
+        For more information, see
+        `Modifying the State Point
+        <https://docs.signac.io/en/latest/jobs.html#modifying-the-state-point>`_.
 
         .. warning::
 
@@ -463,11 +491,16 @@ def statepoint(self):
 
         See :ref:`signac statepoint <signac-cli-statepoint>` for the command line equivalent.
 
+        .. danger::
+
+            Use this function with caution! Resetting a job's state point
+            may sometimes be necessary, but can possibly lead to incoherent
+            data spaces.
+
         Returns
         -------
         dict
             Returns the job's state point.
-
         """
         with self._lock:
             if self._statepoint_requires_init:
@@ -491,7 +524,6 @@ def statepoint(self, new_statepoint):
         ----------
         new_statepoint : dict
             The new state point to be assigned.
-
         """
         self.reset_statepoint(new_statepoint)
 
@@ -785,7 +817,7 @@ def move(self, project):
         with self._lock:
             statepoint = self.statepoint()
             dst = project.open_job(statepoint)
-            _mkdir_p(project.workspace())
+            _mkdir_p(project.workspace)
             try:
                 os.replace(self.workspace(), dst.workspace())
             except OSError as error: