env.read_env returns False if file not found

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 10.2.0 (unreleased)
+
+Features:
+
+- `env.read_env` returns `False` if file not found ([#294](https://github.com/sloria/environs/issues/294)).
+  Thanks [rptaylor](https://github.com/rptaylor) for the suggestion.
+
 ## 10.1.0 (2024-01-08)
 
 Features:

environs/__init__.py

@@ -395,7 +395,7 @@ def read_env(
         recurse: _BoolType = True,
         verbose: _BoolType = False,
         override: _BoolType = False,
-    ) -> None:
+    ) -> _BoolType:
         """Read a .env file into os.environ.
 
         If .env is not found in the directory from which this method is called,
@@ -423,10 +423,10 @@ def read_env(
             for dirname in _walk_to_root(start_dir):
                 check_path = Path(dirname) / env_name
                 if check_path.exists():
-                    load_dotenv(check_path, verbose=verbose, override=override)
-                    return
+                    return load_dotenv(check_path, verbose=verbose, override=override)
+            return False
         else:
-            load_dotenv(str(start), verbose=verbose, override=override)
+            return load_dotenv(str(start), verbose=verbose, override=override)
 
     @contextlib.contextmanager
     def prefixed(self, prefix: _StrType) -> typing.Iterator["Env"]:

tests/test_environs.py

@@ -300,11 +300,16 @@ def test_read_env(self, env):
         if "STRING" in os.environ:
             os.environ.pop("STRING")
         assert env("STRING", "default") == "default"  # sanity check
-        env.read_env()
+        result = env.read_env()
+        assert result is True
         assert env("STRING") == "foo"
         assert env.list("LIST") == ["wat", "wer", "wen"]
         assert env("EXPANDED") == "foo"
 
+    def test_read_env_returns_false_if_file_not_found(self, env):
+        result = env.read_env(HERE / ".does_not_exist", verbose=True)
+        assert result is False
+
     # Regression test for https://github.com/sloria/environs/issues/96
     def test_read_env_recurse(self, env):
         if "CUSTOM_STRING" in os.environ: