Raise error on underspecified path for import/export and view

changelog.txt

@@ -29,6 +29,7 @@ Fixed
 +++++
 
  - ``H5Store.mode`` returns the file mode (#607).
+ - User-provided path functions now raise an error if not unique (#666).
 
 [1.7.0] -- 2021-06-08
 ---------------------

signac/contrib/import_export.py

@@ -11,7 +11,7 @@
 import shutil
 import tarfile
 import zipfile
-from collections import OrderedDict
+from collections import Counter, OrderedDict
 from contextlib import closing, contextmanager
 from string import Formatter
 from tempfile import TemporaryDirectory
@@ -149,6 +149,40 @@ class _SchemaPathEvaluationError(RuntimeError):
     pass
 
 
+def _check_path_function_unique(jobs, path_spec, path_function):
+    """Validate that path function specifies a 1-1 mapping.
+
+    Parameters
+    ----------
+    jobs : iterable of :class:`~signac.contrib.job.Job`
+        A sequence of jobs (instances of :class:`~signac.contrib.job.Job`).
+    path_spec : str
+        The path string that generated the path_function. Displayed in the
+        error message.
+    path_function : callable
+        A callable path generating function.
+
+    Raises
+    ------
+    RuntimeError
+        If paths generated with given path function are not unique.
+
+    """
+    job_paths = Counter(path_function(job) for job in jobs)
+    duplicates = {path for path, count in job_paths.items() if count > 1}
+    if len(duplicates) > 0:
+        # Log paths generated more than once
+        for path in duplicates:
+            logger.debug(f"Generated path '{path}' is not unique.")
+        raise RuntimeError(
+            f"The path specification '{path_spec}' would result in duplicate "
+            "paths. See the debug log for the list of duplicate paths. The "
+            "easiest way to fix this is to append the job id to the path "
+            "specification like "
+            f"'{os.path.join(str(path_spec), 'id', '{job.id}')}'."
+        )
+
+
 def _make_path_function(jobs, path):
     """Generate a path function for jobs or use ``path`` if it is callable.
 
@@ -194,7 +228,7 @@ def path_function(job):
             return str(job.id)
 
     elif isinstance(path, str):
-        # Detect keys that are already provided as part of the path specifier and
+        # Detect keys that are already provided as part of the path specifier
         # and should therefore be excluded from the 'auto'-part.
         exclude_keys = [x[1] for x in Formatter().parse(path)]
 
@@ -241,6 +275,9 @@ def path_function(job):
             except Exception as error:
                 raise _SchemaPathEvaluationError(error)
 
+        # Check that the user-specified path generates a 1-1 mapping
+        _check_path_function_unique(jobs, path_spec=path, path_function=path_function)
+
     else:
         raise ValueError(
             "The path argument must either be `None`, `False`, or of type `str`."
@@ -297,21 +334,18 @@ def _export_jobs(jobs, path, copytree):
     ------
     RuntimeError
         If paths generated with given path function are not unique.
-
     """
     # Transform the path argument into a callable if necessary.
     if callable(path):
         path_function = path
+        _check_path_function_unique(jobs, path_spec=path, path_function=path_function)
     else:
         path_function = _make_path_function(jobs, path)
+        # path_function is checked for uniqueness inside _make_path_function
 
     # Determine export path for each job.
     paths = {job.workspace(): path_function(job) for job in jobs}
 
-    # Check whether the mapped paths are unique.
-    if len(set(paths.values())) != len(paths):
-        raise RuntimeError("Paths generated with given path function are not unique!")
-
     # Check leaf/node consistency
     _check_directory_structure_validity(paths.values())
 

signac/contrib/linked_view.py

@@ -109,8 +109,8 @@ def create_linked_view(project, prefix=None, job_ids=None, index=None, path=None
             links["./job"] = job.workspace()
         assert len(links) < 2
     _check_directory_structure_validity(links.keys())
-
     _update_view(prefix, links)
+
     return links
 
 

tests/test_project.py

@@ -2003,6 +2003,12 @@ def test_create_linked_view_homogeneous_schema_nested_provide_partial_path(self)
                     sp = {"a": a, "d": {"b": b, "c": c}}
                     self.project.open_job(sp).init()
 
+        # Should error if user-provided path doesn't make 1-1 mapping
+        with pytest.raises(RuntimeError):
+            self.project.create_linked_view(
+                prefix=view_prefix, path=os.path.join("a", "{a}")
+            )
+
         self.project.create_linked_view(
             prefix=view_prefix, path="a/{a}/d.c/{d.c}/{{auto}}"
         )
@@ -2230,6 +2236,23 @@ def test_create_linked_view_with_slash_raises_error(self):
             with pytest.raises(RuntimeError):
                 self.project.create_linked_view(prefix=view_prefix)
 
+    @pytest.mark.skipif(WINDOWS, reason="Linked views unsupported on Windows.")
+    def test_create_linked_view_duplicate_paths(self):
+        view_prefix = os.path.join(self._tmp_pr, "view")
+        a_vals = range(2)
+        b_vals = range(3, 8)
+        for a in a_vals:
+            for b in b_vals:
+                sp = {"a": a, "b": b}
+                self.project.open_job(sp).init()
+
+        # An error should be raised if the user-provided path function doesn't
+        # make a 1-1 mapping.
+        with pytest.raises(RuntimeError):
+            self.project.create_linked_view(
+                prefix=view_prefix, path=os.path.join("a", "{a}")
+            )
+
 
 class UpdateCacheAfterInitJob(signac.contrib.job.Job):
     def init(self, *args, **kwargs):

tests/test_shell.py

@@ -237,6 +237,24 @@ def test_view(self):
                 "view/a/{}/job".format(sp["a"])
             ) == os.path.realpath(project.open_job(sp).workspace())
 
+    @pytest.mark.skipif(WINDOWS, reason="Symbolic links are unsupported on Windows.")
+    def test_view_incomplete_path_spec(self):
+        self.call("python -m signac init my_project".split())
+        project = signac.Project()
+        sps = [{"a": i} for i in range(3)]
+        for sp in sps:
+            project.open_job(sp).init()
+        os.mkdir("view")
+
+        # An error should be raised if the user-provided path function
+        # doesn't make a 1-1 mapping.
+        err = self.call(
+            "python -m signac view view non_unique".split(),
+            error=True,
+            raise_error=False,
+        )
+        assert "duplicate paths" in err
+
     def test_find(self):
         self.call("python -m signac init my_project".split())
         project = signac.Project()