FileContainer: add search_single (#158)

* `FileContainer`: add `search_single`

* changelog

Author: mathause

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## v1.0.2 - unreleased
 
 - Restore behavior of `FileContainer.search(key=None)` - passing `None` to `search` is ignored again [#143](https://github.com/mpytools/filefisher/issues/143).
+- Added `FileContainer.search_single` to search for _exacly_ one path in a `FileContainer` ([#158](https://github.com/mpytools/filefisher/pull/158)).
 
 ## v1.0.1 - 16.01.205
 This version patches a bug from v1.0.0. that broke `FileContainer.concat()`.

filefisher/_filefinder.py

@@ -675,14 +675,18 @@ def _combine_by_keys(self, keys=None, sep="."):
 
         return self.df[list(keys)].apply(lambda x: sep.join(x.map(str)), axis=1)
 
-    def search(self, **query):
+    def search(self, **query) -> "FileContainer":
         """subset paths given a search query
 
         Parameters
         ----------
         **query : Mapping[str, str | int | list[str | int]]
             Search query.
 
+        Returns
+        -------
+        search_result : FileContainer
+
         Notes
         -----
         - individual conditions are combined with "and", e.g., ``model="a", exp="b"``
@@ -695,6 +699,39 @@ def search(self, **query):
         df = self._get_subset(**query)
         return type(self)(df)
 
+    def search_single(self, **query) -> "FileContainer":
+        """find exactly one path given a search query - raises an error otherwise
+
+        Parameters
+        ----------
+        **query : Mapping[str, str | int | list[str | int]]
+            Search query.
+
+        Returns
+        -------
+        search_result : FileContainer
+
+        See also
+        --------
+        FileContainer.search
+        """
+
+        fc = self.search(**query)
+
+        if len(fc) == 0:
+            msg = "Found no paths"
+            raise ValueError(msg)
+
+        if len(fc) > 1:
+            n_found = len(fc)
+            msg = (
+                f"Found more than one ({n_found}) paths. Please adjust your"
+                f" query.\nFirst five paths:\n{fc.df.head()}"
+            )
+            raise ValueError(msg)
+
+        return fc
+
     def concat(self, other, drop_duplicates=True):
         """concatenate two FileContainers
 

filefisher/tests/test_filecontainer.py

@@ -170,6 +170,23 @@ def test_filecontainer_search_none_key(example_df, example_fc):
     pd.testing.assert_frame_equal(result.df, expected)
 
 
+def test_filecontainer_search_single(example_df, example_fc):
+
+    # empty search query results in an empty FileContainer
+    with pytest.raises(ValueError, match="Found no paths"):
+        example_fc.search_single()
+
+    with pytest.raises(ValueError, match="Found more than one \(5\) paths"):
+        example_fc.search_single(model=None)
+
+    with pytest.raises(ValueError, match="Found more than one \(2\) paths"):
+        example_fc.search_single(model="a")
+
+    result = example_fc.search_single(model="a", scen="h")
+    expected = example_df.iloc[[1]]
+    pd.testing.assert_frame_equal(result.df, expected)
+
+
 def test_filecontainer_concat(example_fc):
 
     with pytest.raises(ValueError, match="Can only concatenate two FileContainers."):