Document and fix autoread-dotenv's startup-time impact

autoread-dotenv runs on every Python process start in the venv via the
sitecustomize hook, so its startup-time cost is worth measuring and
tracking explicitly.

Measured with hyperfine (throwaway venvs, 50+ runs each):

  bare venv                                    12.3ms +- 0.5ms  (1.00x)
  sitecustomize-entrypoints, no entries         36.5ms +- 1.8ms  (2.97x)
  autoread-dotenv, no .env found      before:   60.4ms           (4.88x)
                                       after:    38.7ms +- 3.7ms  (3.14x)
  autoread-dotenv, .env loaded                  58.0ms +- 2.5ms  (4.71x)

The entry-point discovery mechanism (sitecustomize-entrypoints scanning
every installed distribution's metadata) accounts for most of the jump
from bare to "hooks installed" - not autoread-dotenv's to optimize.
autoread-dotenv itself was adding another ~24-25ms on top of that,
entirely import cost (import dotenv + about.py's eager
importlib.metadata lookup), not actual .env-parsing work. Fixed both:

- entrypoint() now checks whether a .env exists via get_dotenv_path()
  before importing dotenv at all - `import dotenv` moved inside the
  function, deferred until there's an actual file to load. Removed the
  now-unneeded DOTENV_INSTALLED module-level sentinel along with it.

- __init__.py no longer re-exports about.py's version/license_/authors
  as __version__/__author__/__license__, so about.py's
  importlib.metadata lookup is never triggered by the sitecustomize
  hook - only if something explicitly imports autoread_dotenv.about
  (as the test-suite does).

BREAKING: autoread_dotenv.__version__, __author__, and __license__ no
longer exist. Use autoread_dotenv.about.version/.license_/.authors
directly - unchanged, just no longer re-exported from the package
root. tests/test_init.py (only tested those two dunders) deleted;
conftest.py's importlib.reload(autoread_dotenv.about) removed since
nothing imports it by default anymore.

Net effect: the common "no .env found" case (pip/uv/utility scripts
run outside a project root) now costs essentially nothing beyond
opting into sitecustomize-entrypoints itself.

Adds:
- docs/performance.md: methodology, before/after numbers, what was
  fixed and why, linked from docs/readme.md and docs/index.rst.
- .just/benchmark.justfile (benchmark-startup, benchmark-importtime)
  so the numbers are reproducible rather than a one-off snapshot.
  Flags that PyPI's "hyperfine" package is an unrelated
  scientific-fitting library, not the real Rust CLI tool.

Tracking approach: doc-only, re-run manually. No CI job or
third-party benchmarking service for now.

Author: woutervh

.just/benchmark.justfile

@@ -0,0 +1,65 @@
+# See ../makefile
+#
+# Benchmarks for the startup-time cost autoread-dotenv adds via the sitecustomize hook.
+# See docs/performance.md for the methodology, current numbers, and how to read them.
+#
+# Requires `hyperfine` (https://github.com/sharkdp/hyperfine) on PATH for benchmark-startup.
+# That is a Rust CLI binary, NOT the PyPI package of the same name (`pip install hyperfine` /
+# `uv add hyperfine` installs an unrelated scientific-fitting library that pulls in numpy,
+# jax, scipy, pandas, iminuit). Install hyperfine via your system package manager instead,
+# e.g. `apt install hyperfine`, `brew install hyperfine`, or `cargo install hyperfine`.
+
+
+# check that the real (Rust) hyperfine is on PATH, not the unrelated PyPI package
+[group: 'benchmark']
+benchmark-check-hyperfine:
+	@command -v hyperfine >/dev/null || { \
+		echo "hyperfine not found on PATH."; \
+		echo "Install: https://github.com/sharkdp/hyperfine#installation"; \
+		echo "(NOT 'pip install hyperfine' / 'uv add hyperfine' - that installs an unrelated PyPI package)."; \
+		exit 1; \
+	}
+
+
+# compare python startup time: bare venv vs sitecustomize-entrypoints vs autoread-dotenv
+[group: 'benchmark']
+benchmark-startup: benchmark-check-hyperfine
+	#!/usr/bin/env bash
+	# Builds throwaway venvs in a tempdir (no side-effects on this project's own .venv):
+	# bare / sitecustomize-entrypoints-only / autoread-dotenv-without-.env /
+	# autoread-dotenv-with-.env. Prints a markdown table - copy the numbers you want to
+	# keep into docs/performance.md, noting the date, `uv --version`, `python --version`,
+	# and how many packages were installed in the compared venvs.
+	set -euo pipefail
+	workdir="$(mktemp -d)"
+	trap 'rm -rf "$workdir"' EXIT
+
+	echo "Building throwaway venvs in $workdir ..." >&2
+	uv venv --python 3.14 "$workdir/bare" -q
+	uv venv --python 3.14 "$workdir/ste-only" -q
+	uv pip install --python "$workdir/ste-only/bin/python" sitecustomize-entrypoints -q
+	uv venv --python 3.14 "$workdir/autoread" -q
+	uv pip install --python "$workdir/autoread/bin/python" . -q
+	echo "FOO=bar" > "$workdir/dotenv-fixture.env"
+
+	hyperfine --warmup 10 --min-runs 50 \
+		-n "bare venv (no sitecustomize hooks)" \
+			"$workdir/bare/bin/python -c pass" \
+		-n "sitecustomize-entrypoints only (no entries registered)" \
+			"$workdir/ste-only/bin/python -c pass" \
+		-n "autoread-dotenv installed, no .env found" \
+			"$workdir/autoread/bin/python -c pass" \
+		-n "autoread-dotenv installed, .env loaded" \
+			"env AUTOREAD_DOTENV_PATH=$workdir/dotenv-fixture.env $workdir/autoread/bin/python -c pass"
+
+
+# show which imports the sitecustomize hook pulls in and what they cost
+[group: 'benchmark']
+benchmark-importtime:
+	# Complements benchmark-startup (total end-to-end cost) with an attribution breakdown:
+	# which specific imports the hook triggers. Uses this project's own dev .venv, so the
+	# numbers include however many dev-dependencies happen to be installed there - see
+	# docs/performance.md for why that matters (entry-point discovery scans every
+	# installed distribution, not just autoread-dotenv's own dependencies).
+	uv run python -X importtime -c pass 2>&1 | grep -E \
+		"dotenv|autoread_dotenv|importlib_metadata$|importlib\.metadata$|sitecustomize$|\\| site$"

docs/changes.md

@@ -62,6 +62,25 @@ All notable changes to this project will be documented in this file.
   no stable 3.15 release yet, so `uv` treats the rc as the match), and the full test-suite
   passes against it unmodified.
 
+- Document and fix autoread-dotenv's startup-time cost in the new `docs/performance.md`, since it
+  runs on every Python process start in the venv. Measured with `hyperfine`: opting into
+  `sitecustomize-entrypoints`'s entry-point discovery costs ~2.9x a bare venv's startup time
+  regardless of which entrypoints are registered (not autoread-dotenv's to fix); autoread-dotenv
+  itself was adding another ~24-25ms on top of that, entirely import cost (`import dotenv` +
+  `about.py`'s eager `importlib.metadata` lookup), not actual `.env`-parsing work. Fixed both:
+  `entrypoint()` now checks whether a `.env` exists before importing `dotenv` at all, and
+  `__init__.py` no longer imports `about.py` (see BREAKING note below). The "no `.env` found" case
+  dropped from 60.4ms to 38.7ms - now within noise of the bare hook-mechanism floor. Added
+  `.just/benchmark.justfile` (`just benchmark-startup`, `just benchmark-importtime`) so the
+  numbers are reproducible rather than a one-off snapshot. Tracking is doc-only / re-run manually
+  for now, no CI job or third-party benchmarking service.
+
+- **BREAKING:** Remove `autoread_dotenv.__version__`, `__author__`, and `__license__`. They forced
+  `about.py`'s `importlib.metadata` lookup to run on every process start via the sitecustomize
+  hook, whether or not anything read them (see above). Use
+  `autoread_dotenv.about.version`/`.license_`/`.authors` directly instead - unchanged, just no
+  longer re-exported from the package root.
+
 ## 1.0.5 (2026-08-16)
 
 - Add codespell as dev-dependency for spellchecking.

docs/index.rst

@@ -5,6 +5,7 @@ autoread_dotenv
     :maxdepth: 2
 
     readme
+    performance
     changes
     security
     license

docs/modules/autoread_dotenv/index.rst

@@ -52,16 +52,6 @@ Submodules
    /modules/autoread_dotenv/warnings/index
 
 
-Attributes
-----------
-
-.. autoapisummary::
-
-   autoread_dotenv.__author__
-   autoread_dotenv.__license__
-   autoread_dotenv.__version__
-
-
 Functions
 ---------
 
@@ -76,15 +66,6 @@ Functions
 Package Contents
 ----------------
 
-.. py:data:: __author__
-   :type:  str
-
-.. py:data:: __license__
-   :type:  str
-
-.. py:data:: __version__
-   :type:  str
-
 .. py:function:: get_dotenv_path()
 
    Return the location of the .env for in-project virtualenvs.

docs/performance.md

@@ -0,0 +1,158 @@
+# Performance
+
+`autoread-dotenv` hooks into `sitecustomize`, which runs on the start of *every* Python
+process in the venv - short-lived CLI invocations, `pytest`, `pip`/`uv` themselves, and so
+on. That makes its startup-time cost worth measuring and tracking explicitly, rather than
+assuming it away.
+
+## Summary
+
+Measured with `hyperfine` (see "Methodology" section below), comparing four scenarios in
+throwaway venvs:
+
+| Scenario                                                     |             Mean | vs. bare venv |
+| ------------------------------------------------------------ | ---------------: | ------------: |
+| Bare venv, no sitecustomize hooks at all                     | 12.3 ms ± 0.5 ms |         1.00x |
+| `sitecustomize-entrypoints` installed, no entries registered | 36.5 ms ± 1.8 ms |         2.97x |
+| `autoread-dotenv` installed, no `.env` found                 | 38.7 ms ± 3.7 ms |         3.14x |
+| `autoread-dotenv` installed, `.env` loaded                   | 58.0 ms ± 2.5 ms |         4.71x |
+
+Measured 2026-08-16, uv 0.12.3, hyperfine 1.20.0, Python 3.14.7, Linux x86_64. Each venv had
+only the packages named above installed (see "Methodology" section for why that matters).
+Re-run `just benchmark-startup` to reproduce/update these numbers - they are a point-in-time
+snapshot, not a guarantee.
+
+**Reading these numbers:**
+
+- The jump from "bare venv" to "`sitecustomize-entrypoints` only" (+24.2 ms) is the cost of
+  the entry-point *discovery* mechanism itself - scanning every installed distribution's
+  metadata for a registered `sitecustomize` entry point - and happens regardless of whether
+  autoread-dotenv is one of the packages found. This is not something autoread-dotenv
+  controls or can optimize away; it is the fixed cost of opting into
+  `sitecustomize-entrypoints` at all.
+- **"No `.env` found" now costs essentially nothing beyond that floor** (38.7 ms vs. 36.5 ms
+  for the bare hook mechanism - within noise). This is the result of the fix described
+  below; it used to cost 60.4 ms, +~24 ms over the same floor. See "What was fixed".
+- "`.env` loaded" still costs +~21 ms over the floor (58.0 ms), because actually loading a
+  `.env` requires importing `python-dotenv` - that part of the cost is real, unavoidable
+  work, not overhead.
+- All of these numbers scale with **how many packages are installed in the venv**, because
+  the entry-point discovery scan has to check all of them, not just autoread-dotenv's own
+  dependencies. A real project's venv (with its own dependencies, dev tools, etc.) will see
+  a larger absolute number than the minimal venvs used here. `just benchmark-importtime`
+  (below) uses this project's own ~95-package dev venv for that reason, and shows
+  proportionally larger absolute numbers for the same relative breakdown.
+
+## What was fixed
+
+Measuring this surfaced two things that were costing every process a lookup or an import it
+usually didn't need, regardless of whether there was a `.env` to load:
+
+1. **`import dotenv` was eager.** [`src/autoread_dotenv/__init__.py`](../src/autoread_dotenv/__init__.py)
+   used to `import dotenv` (python-dotenv) unconditionally at module level, before
+   `entrypoint()` even checked whether a `.env` file exists. Fixed: `entrypoint()` now
+   checks `get_dotenv_path()` *first*, and only imports `dotenv` once it knows there's an
+   actual file to hand to `dotenv.load_dotenv()`. No `.env` found -> `dotenv` is never
+   imported.
+
+1. **`autoread_dotenv.about`'s metadata lookup was eager, and pulled in unconditionally.**
+   `about.py` called `importlib.metadata.metadata()` at module level purely to populate
+   `__version__`/`__author__`/`__license__` on the `autoread_dotenv` package - and
+   `__init__.py` re-exported those three names, which forced `about.py` to be imported (and
+   its metadata lookup to run) on every process start via the sitecustomize hook, whether or
+   not anything ever read them. Fixed by removing that re-export: `__init__.py` no longer
+   imports `about.py` at all, so its cost is paid only if something explicitly does
+   `from autoread_dotenv.about import version` (as the test-suite does) - never as a side
+   effect of the sitecustomize hook firing.
+
+   **This is a breaking change to the public API:** `autoread_dotenv.__version__`,
+   `__author__`, and `__license__` no longer exist. Use
+   `autoread_dotenv.about.version`/`.license_`/`.authors` directly if you need them (see
+   `about.py` - unchanged, still eager, but now only runs when you actually import it).
+
+Net effect: the "no `.env` found" scenario dropped from 60.4 ms to 38.7 ms - it now sits
+right at the `sitecustomize-entrypoints`-only floor, meaning autoread-dotenv itself adds
+essentially nothing in that case anymore. The "`.env` loaded" scenario only dropped slightly
+(59.6 ms -> 58.0 ms), because it still needs to import `dotenv` to actually do its job - see
+"Where the remaining cost goes" below for confirmation neither `dotenv` nor
+`autoread_dotenv.about` show up in the "no `.env`" import tree anymore.
+
+## Where the remaining cost goes
+
+`python -X importtime` breaks down import cost per module. Filtered to the relevant lines
+(via `just benchmark-importtime`, run against this project's own dev venv, which has a real
+`.env`):
+
+```text
+import time:      2223 |      38934 |     sitecustomize._vendor.importlib_metadata
+import time:       358 |        358 |     autoread_dotenv.utils
+import time:       464 |        464 |     autoread_dotenv.warnings
+import time:      1149 |       1149 |         dotenv.parser
+import time:       585 |        585 |         dotenv.variables
+import time:      1063 |      23467 |       dotenv.main
+import time:       508 |      23975 |     dotenv
+import time:     12760 |      81876 |   sitecustomize
+import time:      2745 |      94071 | site
+```
+
+(First column is self-time in µs, second is cumulative including sub-imports, both in
+`site`'s subtree.) Note `autoread_dotenv.about` no longer appears in this tree at all - only
+`utils` and `warnings`, both negligible. `dotenv` still does, because a `.env` was actually
+found and loaded here; re-running against a venv with no `.env` drops the `dotenv` lines too,
+leaving only `autoread_dotenv.utils`/`warnings` under `sitecustomize`.
+
+What's left is `sitecustomize-entrypoints`'s own entry-point discovery scan (not
+autoread-dotenv's to optimize) and, when a `.env` is actually found, the real cost of
+importing `python-dotenv` to load it.
+
+## Conclusions
+
+1. **autoread-dotenv no longer meaningfully adds to the hook-mechanism tax when there's no
+   `.env` to load.** Before the fix, autoread-dotenv doubled the cost of opting into
+   `sitecustomize-entrypoints` at all (+~24 ms on top of the +~24 ms discovery-scan floor).
+   After: the "no `.env`" case sits within noise of that floor.
+
+1. **The remaining cost, when a `.env` *is* found, is real work - not overhead.** Loading a
+   `.env` requires importing `python-dotenv` (~21 ms of the +~21 ms over the floor); that's
+   the package doing its actual job, not something left on the table. **Caveat:** the `.env`
+   fixture used here is a single line. This isolates the import-cost floor for that path, not
+   necessarily the ceiling for a much larger, real-world `.env` (dozens of vars, `${VAR}`
+   interpolation) - that's an open question this benchmark doesn't answer yet.
+
+1. **The cost scales with venv size, so these numbers aren't fixed constants.** The discovery
+   scan checks every installed distribution, not just autoread-dotenv's own dependencies - a
+   lean production venv pays less than a kitchen-sink dev venv. This project's own
+   ~95-package dev venv (used for the `importtime` breakdown above) shows proportionally
+   larger absolute numbers for the same relative shape.
+
+1. **Practical takeaway:** the "no `.env`" case - which covers `pip`/`uv`/utility scripts run
+   from outside a project root, or any venv where autoread-dotenv is installed but unused -
+   now costs essentially nothing beyond opting into `sitecustomize-entrypoints` itself. The
+   "`.env` found and loaded" case still carries `python-dotenv`'s own import cost, which
+   compounds for anything that spawns Python repeatedly (CI matrices, per-test subprocess
+   isolation, cold-start-sensitive environments) - but that's now the honest floor for doing
+   the job, not accidental overhead.
+
+## Methodology
+
+Two complementary tools, both wrapped in `justfile` recipes so they're reproducible rather
+than one-off measurements:
+
+- **[`hyperfine`](https://github.com/sharkdp/hyperfine)** (`just benchmark-startup`) for
+  end-to-end wall-clock comparisons, with proper warmup runs and statistical variance - a
+  single-shot `time python -c pass` is not trustworthy enough to publish. Builds throwaway
+  venvs in a tempdir (no side-effects on this project's own `.venv`) for four scenarios:
+  bare / `sitecustomize-entrypoints`-only / autoread-dotenv-without-`.env` /
+  autoread-dotenv-with-`.env`.
+
+  > `hyperfine` is a Rust CLI binary, install via your system package manager (`apt install hyperfine`, `brew install hyperfine`, `cargo install hyperfine`, ...). **Not** `pip install hyperfine` / `uv add hyperfine` - that installs an unrelated PyPI package (a
+  > scientific curve-fitting library depending on `numpy`, `jax`, `scipy`, `pandas`,
+  > `iminuit`) that happens to share the name.
+
+- **`python -X importtime`** (stdlib, `just benchmark-importtime`) for *attributing* cost to
+  specific imports, to see where the wall-clock difference actually goes rather than just
+  how big it is.
+
+Tracking approach: doc-only, re-run manually (e.g. before releases, or when touching
+`entrypoint()`/`about.py`/dependencies). No CI job or third-party benchmarking service for
+now - revisit if regressions start slipping through unnoticed.

docs/readme.md

@@ -71,6 +71,12 @@ entirely:
 > export AUTOREAD_DOTENV_PATH=/etc/myapp/production.env
 ```
 
+## Performance
+
+`autoread-dotenv` runs on the start of every Python process in the venv, so its startup-time
+cost is measured and tracked explicitly - see [docs/performance.md](performance.md) for the
+current numbers and how to reproduce them.
+
 ## Compatibility
 
 [![Python Version](https://img.shields.io/pypi/pyversions/autoread-dotenv?:alt:PyPI-PythonVersion)](https://pypi.org/project/autoread-dotenv/)

justfile

@@ -34,6 +34,7 @@ set shell := ["bash", "-uc"]
 # - https://github.com/casey/just/issues/1885
 # - https://github.com/casey/just/pull/2376
 import? '.just/bandit.justfile'
+import? '.just/benchmark.justfile'
 import? '.just/dir-structure.justfile'
 import? '.just/dotenv.justfile'
 import? '.just/gh.justfile'

src/autoread_dotenv/__init__.py

@@ -43,25 +43,10 @@
 if tp.TYPE_CHECKING:  # pragma: no cover
     import pathlib as pl
 
-try:
-    import dotenv
-
-    DOTENV_INSTALLED = True
-except ImportError:  # pragma: no cover
-    DOTENV_INSTALLED = False
-
-from autoread_dotenv.about import (
-    authors as __author__,
-    license_ as __license__,
-    version as __version__,
-)
 from autoread_dotenv.utils import get_dotenv_path, get_expected_dotenv_path, str_to_bool
 from autoread_dotenv.warnings import simple_warning
 
 __all__: list[str] = [
-    "__author__",
-    "__license__",
-    "__version__",
     "entrypoint",
     "get_dotenv_path",
     "simple_warning",
@@ -72,19 +57,25 @@
 def entrypoint() -> None:
     """Set environment-variable from the in-project .env-file."""
     dotenv_file: pl.Path | None = get_dotenv_path()
-    enforce_dotenv: bool = str_to_bool(os.getenv("AUTOREAD_ENFORCE_DOTENV", "1"))
-
-    if not DOTENV_INSTALLED:  # pragma: no cover
-        with simple_warning():
-            stdlib_warnings.warn("Module 'dotenv' not found. Please pip install 'python-dotenv'.", stacklevel=2)
-        return
 
     if not dotenv_file:  # pragma: no cover
         with simple_warning():
             expected_path = get_expected_dotenv_path()
             stdlib_warnings.warn(f"{expected_path} does not exist, please create it.", stacklevel=2)
         return
 
+    try:
+        # deferred on purpose: avoids paying python-dotenv's import cost on every Python
+        # process start via the sitecustomize entrypoint when there's no .env to load
+        # anyway. See docs/performance.md.
+        import dotenv  # noqa: PLC0415
+    except ImportError:  # pragma: no cover
+        with simple_warning():
+            stdlib_warnings.warn("Module 'dotenv' not found. Please pip install 'python-dotenv'.", stacklevel=2)
+        return
+
+    enforce_dotenv: bool = str_to_bool(os.getenv("AUTOREAD_ENFORCE_DOTENV", "1"))
+
     try:
         dotenv.load_dotenv(dotenv_file, override=enforce_dotenv, interpolate=True, verbose=True)
     except AttributeError:  # pragma: no cover

tests/conftest.py

@@ -57,7 +57,6 @@
 
 # reload each module to fix coverage report
 importlib.reload(autoread_dotenv)
-importlib.reload(autoread_dotenv.about)
 importlib.reload(autoread_dotenv.utils)
 importlib.reload(autoread_dotenv.warnings)