Additional deprecations

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/job.py

@@ -281,6 +281,9 @@ 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._document = None
@@ -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 :meth:`~Job.path`."""
+        return self.path
 
     @property
     def _statepoint_filename(self):
@@ -359,11 +355,36 @@ 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
+    # 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 :meth:`~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._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
+
+    @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 +469,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 +490,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 +523,6 @@ def statepoint(self, new_statepoint):
         ----------
         new_statepoint : dict
             The new state point to be assigned.
-
         """
         self.reset_statepoint(new_statepoint)
 
@@ -500,6 +531,7 @@ def sp(self):
         """Alias for :attr:`~Job.statepoint`."""
         return self.statepoint
 
+    # TODO: Same concern as statepoint setter.
     @sp.setter
     def sp(self, new_sp):
         """Alias for :attr:`~Job.statepoint`."""

signac/contrib/project.py

@@ -41,7 +41,7 @@
 from .hashing import calc_id
 from .indexing import MainCrawler, SignacProjectCrawler
 from .job import Job
-from .schema import ProjectSchema
+from .schema import ProjectSchema, _collect_by_type
 from .utility import _mkdir_p, _nested_dicts_to_dotted_keys, split_and_print_progress
 
 logger = logging.getLogger(__name__)
@@ -215,6 +215,9 @@ def __setitem__(self, key, value):
 
 def _invalidate_config_cache(project):
     """Invalidate cached properties derived from a project config."""
+    # 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).
     project._id = None
     project._rd = None
     project._wd = None
@@ -263,9 +266,7 @@ def __init__(self, config=None):
         self._lock = RLock()
 
         # Prepare cached properties derived from the project config.
-        self._id = None
-        self._rd = None
-        self._wd = None
+        _invalidate_config_cache(self)
 
         # Ensure that the project id is configured.
         if self.id is None:
@@ -353,15 +354,19 @@ def config(self):
         """
         return self._config
 
+    @deprecated(
+        deprecated_in="1.8",
+        removed_in="2.0",
+        current_version=__version__,
+        details="Use Project.path instead.",
+    )
     def root_directory(self):
-        """Return the project's root directory.
+        """Alias for :meth:`~Project.path`."""
+        return self.path
 
-        Returns
-        -------
-        str
-            Path of project directory.
-
-        """
+    @property
+    def path(self):
+        """str: The path to the project directory."""
         if self._rd is None:
             self._rd = self.config["project_dir"]
         return self._rd
@@ -517,18 +522,6 @@ def isfile(self, filename):
         """
         return os.path.isfile(self.fn(filename))
 
-    def _reset_document(self, new_doc):
-        """Reset document to new document passed.
-
-        Parameters
-        ----------
-        new_doc : dict
-            The new project document.
-
-        """
-        with self._lock:
-            self.document.reset(new_doc)
-
     @property
     def document(self):
         """Get document associated with this project.
@@ -557,7 +550,8 @@ def document(self, new_doc):
             The new project document.
 
         """
-        self._reset_document(new_doc)
+        with self._lock:
+            self.document.reset(new_doc)
 
     @property
     def doc(self):
@@ -757,6 +751,12 @@ def _job_dirs(self):
                 )
                 raise WorkspaceError(error)
 
+    @deprecated(
+        deprecated_in="1.8",
+        removed_in="2.0",
+        current_version=__version__,
+        details="The num_jobs method is deprecated. Use len(project) instead.",
+    )
     def num_jobs(self):
         """Return the number of initialized jobs.
 
@@ -766,15 +766,16 @@ def num_jobs(self):
             Count of initialized jobs.
 
         """
+        return len(self)
+
+    def __len__(self):
         # We simply count the the number of valid directories and avoid building a list
         # for improved performance.
         i = 0
         for i, _ in enumerate(self._job_dirs(), 1):
             pass
         return i
 
-    __len__ = num_jobs
-
     def _contains_job_id(self, job_id):
         """Determine whether a job id is in the project's data space.
 
@@ -790,7 +791,7 @@ def _contains_job_id(self, job_id):
 
         """
         # 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.
+        # os.sep.join instead of os.path.join for speed.
         return os.path.exists(os.sep.join((self.workspace(), job_id)))
 
     def __contains__(self, job):
@@ -926,7 +927,9 @@ def detect_schema(self, exclude_const=False, subset=None, index=None):
         statepoint_index = _build_job_statepoint_index(
             exclude_const=exclude_const, index=index
         )
-        return ProjectSchema.detect(statepoint_index)
+        return ProjectSchema(
+            {key: _collect_by_type(value) for key, value in statepoint_index}
+        )
 
     @deprecated(
         deprecated_in="1.3",
@@ -1530,7 +1533,7 @@ def create_linked_view(self, prefix=None, job_ids=None, index=None, path=None):
         deprecated_in="1.3",
         removed_in="2.0",
         current_version=__version__,
-        details="Use job.reset_statepoint() instead.",
+        details="Use job.statepoint = new_statepoint instead.",
     )
     def reset_statepoint(self, job, new_statepoint):
         """Overwrite the state point of this job while preserving job data.
@@ -2638,17 +2641,19 @@ def __iter__(self):
             self._project, self._project._find_job_ids(self._filter)
         )
 
+    @deprecated(
+        deprecated_in="0.9.6",
+        removed_in="2.0",
+        current_version=__version__,
+        details="Use next(iter(...)) instead.",
+    )
     def next(self):
         """Return the next element.
 
         This function is deprecated. Users should use ``next(iter(..))`` instead.
         .. deprecated:: 0.9.6
 
         """
-        warnings.warn(
-            "Calling next() directly on a JobsCursor is deprecated! Use next(iter(..)) instead.",
-            FutureWarning,
-        )
         if self._next_iter is None:
             self._next_iter = iter(self)
         try: