docs: correct the silencing guidance - PYTHONWARNINGS cannot name the category

Interpreter warning filters (-W / PYTHONWARNINGS) are parsed before
site-packages is importable, so a third-party category never resolves and
the filter is silently dropped. And since entrypoint() runs from
sitecustomize at startup, an in-process filterwarnings() call only affects
a later manual entrypoint() call, not the startup pass.

Rewrite docs/configuration.md "Silencing warnings" into three honest
sections: from Python (filterwarnings / pytest config), at startup
(only ignore::UserWarning works, broadly), and better - remove the cause
(empty .env or AUTOREAD_DOTENV_PATH). Adjust the warnings.py and
entrypoint() docstrings and the changelog entry to match.

Author: woutervh

docs/changes.md

@@ -7,11 +7,14 @@ All notable changes to this project will be documented in this file.
 - 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`
-  (added to `__all__`, alongside `LoadStatus`). Callers can now silence just this package --
-  e.g. `PYTHONWARNINGS=ignore::autoread_dotenv.AutoreadDotenvWarning` -- without muting
-  unrelated `UserWarning`s. Documented under "Silencing warnings" in `docs/configuration.md`.
-  Also fixes the module-reload order in `tests/conftest.py` so reloaded modules re-bind to the
-  fresh category.
+  (added to `__all__`, alongside `LoadStatus`). Programmatic callers and test suites can now
+  filter just this package with `warnings.filterwarnings("ignore",
+  category=AutoreadDotenvWarning)` or pytest's `filterwarnings` config, without muting
+  unrelated `UserWarning`s. Note that `PYTHONWARNINGS` / `-W` cannot reference the category
+  (warning filters are parsed before `site-packages` is importable); the new "Silencing
+  warnings" section of `docs/configuration.md` covers the startup case. Also fixes the
+  module-reload order in `tests/conftest.py` so reloaded modules re-bind to the fresh
+  category.
 
 - Migrate the documentation from Sphinx to MkDocs + Material for MkDocs. The API
   reference is now generated by `mkdocstrings` (Python handler) instead of

docs/configuration.md

@@ -58,37 +58,56 @@ export AUTOREAD_ENFORCE_DOTENV=0
 `autoread-dotenv` never raises for a configuration problem - it emits a warning and records
 the reason in [`last_load_status`](reference/status.md). Every one of those warnings uses the
 category [`AutoreadDotenvWarning`](reference/warnings.md) (a subclass of `UserWarning`),
-re-exported as `autoread_dotenv.AutoreadDotenvWarning`, so you can suppress *only* this package
-without muting unrelated `UserWarning`s from the rest of your app:
+re-exported as `autoread_dotenv.AutoreadDotenvWarning`.
 
-```bash
-# environment (before the interpreter starts, like the variables above)
-export PYTHONWARNINGS="ignore::autoread_dotenv.AutoreadDotenvWarning"
+### From Python (tests, programmatic callers)
 
-# one-off invocation
-python -W "ignore::autoread_dotenv.AutoreadDotenvWarning" -m myapp
-```
+Filter the category directly:
 
 ```python
-# from code, before autoread_dotenv.entrypoint() runs
 import warnings
 from autoread_dotenv import AutoreadDotenvWarning
 
 warnings.filterwarnings("ignore", category=AutoreadDotenvWarning)
 ```
 
 ```toml
-# pytest
+# pytest resolves the category itself, so the dotted path works here
 [tool.pytest.ini_options]
-filterwarnings = ["ignore::autoread_dotenv.AutoreadDotenvWarning"]
+filterwarnings = ["ignore::autoread_dotenv.warnings.AutoreadDotenvWarning"]
+```
+
+Note the timing: `entrypoint()` runs from `sitecustomize` at interpreter startup, *before* any
+of your code. An in-process `filterwarnings()` call therefore only affects a later, manual
+`entrypoint()` invocation - it cannot retroactively silence the startup pass. Use the options
+in the next section for that.
+
+### At startup (`PYTHONWARNINGS` / `-W`)
+
+`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:
+
+```bash
+# broad - silences every UserWarning in the process, not just ours
+export PYTHONWARNINGS="ignore::UserWarning"
 ```
 
-The fully-qualified `autoread_dotenv.warnings.AutoreadDotenvWarning` works everywhere too.
+### Better: remove the cause
+
+The most common warning is the missing-`.env` notice. Rather than muting it, point the loader
+at a file that exists - an empty `.env` is enough - or set `AUTOREAD_DOTENV_PATH`:
+
+```bash
+touch "$PWD/.env"
+# or
+export AUTOREAD_DOTENV_PATH=/etc/myapp/production.env
+```
 
-This is all-or-nothing: it silences the missing-`.env` notice together with the genuine
-misconfiguration warnings (`python-dotenv` not installed, an unreadable `.env`, a typo'd
-boolean). Prefer narrowing by message with `warnings.filterwarnings(..., message=...)` if you
-only want to hide one of them.
+The remaining warnings (`python-dotenv` not installed, an unreadable `.env`, a typo'd boolean)
+signal genuine misconfiguration and are worth leaving on.
 
 ## Setting variables outside `.env`
 

src/autoread_dotenv/__init__.py

@@ -68,8 +68,8 @@ def entrypoint() -> LoadStatus:
     succeeded. A configuration problem is warned about, never raised - this runs on
     every interpreter startup. Every such warning uses the
     [`AutoreadDotenvWarning`][autoread_dotenv.AutoreadDotenvWarning] category (re-exported
-    here from `autoread_dotenv.warnings`), so it can be silenced in isolation - see
-    `docs/configuration.md`.
+    here from `autoread_dotenv.warnings`); see the "Silencing warnings" section of
+    `docs/configuration.md` for how to filter it (and why `PYTHONWARNINGS` cannot).
     """
     global last_load_status  # noqa: PLW0603
 

src/autoread_dotenv/warnings.py

@@ -11,13 +11,15 @@ class AutoreadDotenvWarning(UserWarning):
     """Category for every runtime warning `autoread-dotenv` emits.
 
     A dedicated subclass of `UserWarning` lets callers silence *only* this package
-    without also muting unrelated `UserWarning`s from the rest of their app, using
-    the standard mechanisms - e.g.::
-
-        PYTHONWARNINGS=ignore::autoread_dotenv.AutoreadDotenvWarning
-
-    or `warnings.filterwarnings("ignore", category=AutoreadDotenvWarning)`, or
-    pytest's `filterwarnings` marker. Re-exported as `autoread_dotenv.AutoreadDotenvWarning`.
+    without also muting unrelated `UserWarning`s, via
+    `warnings.filterwarnings("ignore", category=AutoreadDotenvWarning)` or pytest's
+    `filterwarnings` config. Re-exported as `autoread_dotenv.AutoreadDotenvWarning`.
+
+    Note: `PYTHONWARNINGS` / `-W` cannot reference this category - the interpreter
+    parses those filters before `site-packages` is importable, so only built-in
+    categories resolve there. And because `entrypoint()` runs from `sitecustomize`
+    at startup, an in-process filter only affects a later manual `entrypoint()` call,
+    not the startup pass. See `docs/configuration.md`.
     """