rename _allow_empty to on_empty

filefinder/_filefinder.py

@@ -21,7 +21,18 @@
 keys: {repr_keys}
 """
 
-_RESERVED_PLACEHOLDERS = {"keys", "on_parse_error", "_allow_empty"}
+
+def _deprecate_allow_empty(on_empty, **kwargs):
+
+    _allow_empty = kwargs.get("_allow_empty")
+
+    if _allow_empty is not None and on_empty is not None:
+        raise TypeError("Cannot pass `_allow_empty` and `on_empty`")
+
+
+
+
+_RESERVED_PLACEHOLDERS = {"keys", "on_parse_error", "on_empty", "_allow_empty"}
 
 
 def _assert_valid_keys(keys):
@@ -80,7 +91,7 @@ def _create_condition_dict(self, **kwargs):
         return cond_dict
 
     def find(
-        self, keys=None, *, on_parse_error="raise", _allow_empty=False, **keys_kwargs
+        self, keys=None, *, on_parse_error="raise", on_empty="error", **keys_kwargs
     ):
         """find files in the file system using the file and path (folder) pattern
 
@@ -92,8 +103,9 @@ def find(
         on_parse_error : "raise" | "warn" | "ignore", default: "raise"
             What to do if a path/file name cannot be parsed. If "raise" raises a ValueError,
             if "warn" raises a warning and if "ignore" ignores the file.
-        _allow_empty : bool, default: False
-            If False (default) raises an error if no files are found. If True returns
+        on_empty : "raise" | "warn" | "allow", default: "raise"
+            Behaviour when no files are found: "raise" (default) raises a ValueError,
+            "warn" raises a warning. For "warn" and "allow" an empty FileContainer is returned.
             an empty list.
         **keys_kwargs : {key: indexer, ...}, optional
             The keyword arguments form of ``keys``. When the same key is passed in
@@ -130,15 +142,18 @@ def find(
 
             all_patterns.append(full_pattern)
 
-        if all_paths:
-            df = self._parse_paths(all_paths, on_parse_error=on_parse_error)
-        elif _allow_empty:
-            return []
-        else:
+        if len(all_paths) == 0:
             msg = "Found no files matching criteria. Tried the following pattern(s):"
             msg += "".join(f"\n- '{pattern}'" for pattern in all_patterns)
-            raise ValueError(msg)
 
+            if on_empty == "raise":
+                raise ValueError(msg)
+            elif on_empty == "warn":
+                warnings.warn(msg)
+
+            return []
+
+        df = self._parse_paths(all_paths, on_parse_error=on_parse_error)
         fc = FileContainer(df)
 
         len_all = len(fc.df)
@@ -173,7 +188,7 @@ def find_single(self, keys=None, **keys_kwargs):
         ValueError : if more or less than one file/ path is found
         """
 
-        fc = self.find(keys, on_parse_error="raise", _allow_empty=False, **keys_kwargs)
+        fc = self.find(keys, on_parse_error="raise", on_empty="raise", **keys_kwargs)
 
         if len(fc) > 1:
             n_found = len(fc)
@@ -385,7 +400,7 @@ def create_full_name(self, keys=None, **keys_kwargs):
         return self.full.create_name(keys, **keys_kwargs)
 
     def find_paths(
-        self, keys=None, *, on_parse_error="raise", _allow_empty=False, **keys_kwargs
+        self, keys=None, *, on_parse_error="raise", on_empty="raise", **keys_kwargs
     ):
         """find files in the file system using the file and path (folder) pattern
 
@@ -397,9 +412,9 @@ def find_paths(
         on_parse_error : "raise" | "warn" | "skip", default: "raise"
             What to do if a path/file name cannot be parsed. If "raise" raises a ValueError,
             if "warn" raises a warning and if "skip" ignores the file.
-        _allow_empty : bool, default: False
-            If False (default) raises an error if no files are found. If True returns
-            an empty list.
+        on_empty : "raise" | "warn" | "allow", default: "raise"
+            Behaviour when no files are found: "raise" (default) raises a ValueError,
+            "warn" raises a warning. For "warn" and "allow" an empty FileContainer is returned.
         **keys_kwargs : {key: indexer, ...}, optional
             The keyword arguments form of ``keys``. When the same key is passed in
             ``keys`` and ``keys_kwargs`` the latter takes priority.
@@ -430,12 +445,12 @@ def find_paths(
         return self.path.find(
             keys,
             on_parse_error=on_parse_error,
-            _allow_empty=_allow_empty,
+            on_empty=on_empty,
             **keys_kwargs,
         )
 
     def find_files(
-        self, keys=None, *, on_parse_error="raise", _allow_empty=False, **keys_kwargs
+        self, keys=None, *, on_parse_error="raise", on_empty="raise", **keys_kwargs
     ):
         """find files in the file system using the file pattern
 
@@ -447,9 +462,9 @@ def find_files(
         on_parse_error : "raise" | "warn" | "skip", default: "raise"
             What to do if a path/file name cannot be parsed. If "raise" raises a ValueError,
             if "warn" raises a warning and if "skip" ignores the file.
-        _allow_empty : bool, default: False
-            If False (default) raises an error if no files are found. If True returns
-            an empty list.
+        on_empty : "raise" | "warn" | "allow", default: "raise"
+            Behaviour when no files are found: "raise" (default) raises a ValueError,
+            "warn" raises a warning. For "warn" and "allow" an empty FileContainer is returned.
         **keys_kwargs : {key: indexer, ...}, optional
             The keyword arguments form of ``keys``. When the same key is passed in
             ``keys`` and ``keys_kwargs`` the latter takes priority.
@@ -483,7 +498,7 @@ def find_files(
         return self.full.find(
             keys,
             on_parse_error=on_parse_error,
-            _allow_empty=_allow_empty,
+            on_empty=on_empty,
             **keys_kwargs,
         )
 

filefinder/tests/test_filefinder.py

@@ -211,10 +211,10 @@ def test_find_path_none_found(tmp_path, test_paths):
     with pytest.raises(ValueError, match="Found no files matching criteria"):
         ff.find_paths({"a": "foo"})
 
-    result = ff.find_paths(a="foo", _allow_empty=True)
+    result = ff.find_paths(a="foo", on_empty="allow")
     assert result == []
 
-    result = ff.find_paths({"a": "foo"}, _allow_empty=True)
+    result = ff.find_paths({"a": "foo"}, on_empty="allow")
     assert result == []
 
 
@@ -369,13 +369,13 @@ def test_find_file_none_found(tmp_path, test_paths):
     with pytest.raises(ValueError, match="Found no files matching criteria"):
         ff.find_files({"a": "XXX"})
 
-    result = ff.find_files(a="XXX", _allow_empty=True)
+    result = ff.find_files(a="XXX", on_empty="allow")
     assert result == []
 
-    result = ff.find_files({"a": "XXX"}, _allow_empty=True)
+    result = ff.find_files({"a": "XXX"}, on_empty="allow")
     assert result == []
 
-    result = ff.find_files({"a": "XXX"}, _allow_empty=True, a="XXX")
+    result = ff.find_files({"a": "XXX"}, on_empty="allow", a="XXX")
     assert result == []