Support for returning the file directory of loaded env file - Impleme…

…nts #362 (#364)

* feat: Add support for returning the file directory of loaded env file - Implements #362

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix return type for python 3.8 and 3.9 (#362)

* Update changelog

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Steven Loria <[email protected]>

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 11.1.0 (unreleased)
+
+Features:
+
+- Add `return_path` argument to `Env.read_env` to return the path of the
+  parsed file ([#362](https://github.com/sloria/environs/issues/362)).
+  Thanks [senese](https://github.com/senese) for the suggestion and PR.
+  NOTE: This is added as a backwards-compatible change that is scheduled to be
+  removed in 12.0.0. The path will stored as an attribute of `Env`.
+
 ## 11.0.0 (2024-03-04)
 
 Fixes:

src/environs/__init__.py

@@ -417,14 +417,17 @@ def read_env(
         recurse: _BoolType = True,
         verbose: _BoolType = False,
         override: _BoolType = False,
-    ) -> _BoolType:
+        return_path: _BoolType = False,
+    ) -> typing.Union[_BoolType, _StrType]:
         """Read a .env file into os.environ.
 
         If .env is not found in the directory from which this method is called,
         the default behavior is to recurse up the directory tree until a .env
         file is found. If you do not wish to recurse up the tree, you may pass
         False as a second positional argument.
         """
+
+        is_env_loaded = False
         if path is None:
             # By default, start search from the same directory this function is called
             current_frame = inspect.currentframe()
@@ -445,10 +448,18 @@ def read_env(
             for dirname in _walk_to_root(start_dir):
                 check_path = Path(dirname) / env_name
                 if check_path.exists():
-                    return load_dotenv(check_path, verbose=verbose, override=override)
-            return False
+                    is_env_loaded = load_dotenv(
+                        check_path, verbose=verbose, override=override
+                    )
+                    env_path = str(check_path)
+        else:
+            is_env_loaded = load_dotenv(str(start), verbose=verbose, override=override)
+            env_path = str(start)
+
+        if return_path:
+            return env_path
         else:
-            return load_dotenv(str(start), verbose=verbose, override=override)
+            return is_env_loaded
 
     @contextlib.contextmanager
     def prefixed(self, prefix: _StrType) -> typing.Iterator["Env"]:

tests/test_environs.py

@@ -362,6 +362,11 @@ def test_read_env_directory(self, env):
         with pytest.raises(ValueError, match="path must be a filename"):
             assert env.read_env("tests")
 
+    def test_read_env_return_path(self, env):
+        path = env.read_env(return_path=True)
+        env_path = str(HERE / ".env")
+        assert path == env_path
+
 
 def always_fail(value):
     raise environs.EnvError("something went wrong")