Merge pull request #141 from libranet/feat/quiet-env-var

feat: AUTOREAD_DOTENV_QUIET env var to silence warnings at startup

Author: woutervh

docs/changes.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ## 1.0.7 (unreleased)
 
+- Add an `AUTOREAD_DOTENV_QUIET` environment-variable. When truthy (`1`/`true`/`yes`,
+  parsed by `str_to_bool()`), `entrypoint()` installs a process-wide `ignore` filter for the
+  `AutoreadDotenvWarning` category before doing anything else, silencing every warning the
+  package emits - the missing-`.env` notice and the genuine misconfiguration warnings alike.
+  This is the startup-time knob that `PYTHONWARNINGS` cannot provide. Like the other
+  `AUTOREAD_*` variables it must be set outside `.env`. Documented in `docs/configuration.md`.
+
 - Emit every runtime warning under a dedicated `AutoreadDotenvWarning` category (a
   `UserWarning` subclass) instead of a bare `UserWarning`. It lives in
   `autoread_dotenv.warnings` and is re-exported as `autoread_dotenv.AutoreadDotenvWarning`

docs/configuration.md

@@ -53,6 +53,30 @@ Set it to `0` when the surrounding environment (CI secrets, systemd `Environment
 export AUTOREAD_ENFORCE_DOTENV=0
 ```
 
+## `AUTOREAD_DOTENV_QUIET`
+
+Suppress every warning `autoread-dotenv` emits. When truthy, [`entrypoint()`](reference/index.md)
+installs a process-wide `ignore` filter for the
+[`AutoreadDotenvWarning`](reference/warnings.md) category before it does anything else.
+
+- **Default:** `0` (false) - warnings are shown.
+- **True values:** `1`, `true`, `yes` (case-insensitive).
+- **False values:** `0`, `false`, `no`, `""` (empty).
+- **Anything else:** treated as false, *and a warning is emitted* (typo guard) - so a
+  misspelled value like `AUTOREAD_DOTENV_QUIET=ture` still warns once.
+- **Read by:** [`entrypoint()`](reference/index.md), parsed via
+  [`str_to_bool()`](reference/utils.md); the name lives in
+  `autoread_dotenv.utils.AUTOREAD_DOTENV_QUIET_VAR`.
+
+```bash
+export AUTOREAD_DOTENV_QUIET=1
+```
+
+This is the blunt instrument: it hides the missing-`.env` notice together with the genuine
+misconfiguration warnings (`python-dotenv` not installed, an unreadable `.env`, a typo'd
+boolean elsewhere). Reach for it when the process legitimately runs without a `.env` and you
+have accepted that trade-off; otherwise prefer removing the cause (see below).
+
 ## Silencing warnings
 
 `autoread-dotenv` never raises for a configuration problem - it emits a warning and records
@@ -82,19 +106,22 @@ of your code. An in-process `filterwarnings()` call therefore only affects a lat
 `entrypoint()` invocation - it cannot retroactively silence the startup pass. Use the options
 in the next section for that.
 
-### At startup (`PYTHONWARNINGS` / `-W`)
+### At startup
 
-`PYTHONWARNINGS` and `-W` **cannot** name `AutoreadDotenvWarning`. The interpreter parses
-warning filters before `site` puts `site-packages` on `sys.path`, so a third-party category
-cannot be imported yet and the whole filter is silently dropped
-(`Invalid -W option ignored: invalid module name: 'autoread_dotenv'`). Only built-in
-categories resolve there:
+Set [`AUTOREAD_DOTENV_QUIET=1`](#autoread_dotenv_quiet). It is read at the very top of
+`entrypoint()`, so it covers the startup pass that an in-process `filterwarnings()` call
+misses:
 
 ```bash
-# broad - silences every UserWarning in the process, not just ours
-export PYTHONWARNINGS="ignore::UserWarning"
+export AUTOREAD_DOTENV_QUIET=1
 ```
 
+`PYTHONWARNINGS` and `-W` are *not* an option here: they **cannot** name
+`AutoreadDotenvWarning`. The interpreter parses warning filters before `site` puts
+`site-packages` on `sys.path`, so a third-party category cannot be imported yet and the whole
+filter is silently dropped (`Invalid -W option ignored: invalid module name: 'autoread_dotenv'`).
+Only built-in categories resolve there, so the closest `PYTHONWARNINGS` equivalent is the much broader `ignore::UserWarning`.
+
 ### Better: remove the cause
 
 The most common warning is the missing-`.env` notice. Rather than muting it, point the loader

pyproject.toml

@@ -127,7 +127,7 @@ test-pypi = "https://test.pypi.org/project/autoread-dotenv/"
 
 
 [tool.codespell]
-ignore-words-list = "fasle, hove"
+ignore-words-list = "fasle, hove,ture"
 skip = "uv.lock, var"
 
 

src/autoread_dotenv/__init__.py

@@ -43,7 +43,12 @@
     import pathlib as pl
 
 from autoread_dotenv.status import LoadStatus
-from autoread_dotenv.utils import get_dotenv_path, get_expected_dotenv_path, str_to_bool
+from autoread_dotenv.utils import (
+    AUTOREAD_DOTENV_QUIET_VAR,
+    get_dotenv_path,
+    get_expected_dotenv_path,
+    str_to_bool,
+)
 from autoread_dotenv.warnings import AutoreadDotenvWarning, simple_warning
 
 __all__: list[str] = [
@@ -70,9 +75,16 @@ def entrypoint() -> LoadStatus:
     [`AutoreadDotenvWarning`][autoread_dotenv.AutoreadDotenvWarning] category (re-exported
     here from `autoread_dotenv.warnings`); see the "Silencing warnings" section of
     `docs/configuration.md` for how to filter it (and why `PYTHONWARNINGS` cannot).
+    Setting `AUTOREAD_DOTENV_QUIET=1` suppresses every such warning for the process.
     """
     global last_load_status  # noqa: PLW0603
 
+    if str_to_bool(os.getenv(AUTOREAD_DOTENV_QUIET_VAR, "0")):
+        # Opt-out: silence every AutoreadDotenvWarning for the rest of this process.
+        # Installed as a real filter (rather than just skipped here) so warnings emitted
+        # later in this call - and by any later entrypoint() call - are covered too.
+        stdlib_warnings.filterwarnings("ignore", category=AutoreadDotenvWarning)
+
     dotenv_file: pl.Path | None = get_dotenv_path()
 
     if not dotenv_file:

src/autoread_dotenv/utils.py

@@ -19,6 +19,12 @@
 #: "load an unexpected path" crosses no privilege boundary. See docs/security.md.
 AUTOREAD_DOTENV_PATH_VAR: str = "AUTOREAD_DOTENV_PATH"
 
+#: When truthy (parsed by str_to_bool), entrypoint() installs a process-wide filter that
+#: silences every AutoreadDotenvWarning - the missing-.env notice and the genuine
+#: misconfiguration warnings alike. Like AUTOREAD_DOTENV_PATH it cannot live in .env itself
+#: (it is read before .env is parsed). See docs/configuration.md.
+AUTOREAD_DOTENV_QUIET_VAR: str = "AUTOREAD_DOTENV_QUIET"
+
 #: Recognized spellings for str_to_bool(), case-insensitive.
 TRUE_VALUES: frozenset[str] = frozenset({"1", "true", "yes"})
 FALSE_VALUES: frozenset[str] = frozenset({"0", "false", "no", ""})

tests/test_autoread.py

@@ -185,6 +185,54 @@ def test_entrypoint_missing_dotenv_reports_status(tmp_path: pl.Path, monkeypatch
     assert warning_list[-1].category is AutoreadDotenvWarning
 
 
+def test_entrypoint_quiet_env_suppresses_missing_warning(tmp_path: pl.Path, monkeypatch) -> None:
+    """AUTOREAD_DOTENV_QUIET=1 silences the warning but leaves the LoadStatus intact."""
+    import autoread_dotenv
+    from autoread_dotenv import LoadStatus, entrypoint
+
+    monkeypatch.setenv("AUTOREAD_DOTENV_PATH", str(tmp_path / "does-not-exist.env"))
+    monkeypatch.setenv("AUTOREAD_DOTENV_QUIET", "1")
+
+    with warnings.catch_warnings(record=True) as warning_list:
+        warnings.simplefilter("always")
+        status = entrypoint()
+
+    assert status is LoadStatus.MISSING
+    assert autoread_dotenv.last_load_status is LoadStatus.MISSING
+    assert warning_list == []
+
+
+def test_entrypoint_quiet_env_falsey_still_warns(tmp_path: pl.Path, monkeypatch) -> None:
+    """An explicit AUTOREAD_DOTENV_QUIET=0 must not suppress anything."""
+    from autoread_dotenv import entrypoint
+
+    monkeypatch.setenv("AUTOREAD_DOTENV_PATH", str(tmp_path / "does-not-exist.env"))
+    monkeypatch.setenv("AUTOREAD_DOTENV_QUIET", "0")
+
+    with warnings.catch_warnings(record=True) as warning_list:
+        warnings.simplefilter("always")
+        entrypoint()
+
+    assert len(warning_list) == 1
+    assert "does not exist" in str(warning_list[-1].message)
+
+
+@pytest.mark.usefixtures("dotenv_project")
+def test_entrypoint_quiet_env_suppresses_unrelated_warning(monkeypatch) -> None:
+    """QUIET covers every AutoreadDotenvWarning, not just the missing-.env one."""
+    from autoread_dotenv import LoadStatus, entrypoint
+
+    monkeypatch.setenv("AUTOREAD_DOTENV_QUIET", "1")
+    monkeypatch.setenv("AUTOREAD_ENFORCE_DOTENV", "ture")  # would warn: unrecognized boolean
+
+    with warnings.catch_warnings(record=True) as warning_list:
+        warnings.simplefilter("always")
+        status = entrypoint()
+
+    assert status is LoadStatus.LOADED
+    assert warning_list == []
+
+
 def test_get_dotenv_path_permission_error_on_stat(monkeypatch) -> None:
     """A PermissionError raised by is_file() itself must not crash get_dotenv_path().