feat: add strict parameter to load_dotenv() and dotenv_values()

[AhsanSheraz]

Summary

• Adds an opt-in strict parameter (default False) to load_dotenv() and dotenv_values() that enables fail-fast behavior
• When strict=True, raises FileNotFoundError if the .env file is missing
• When strict=True, raises ValueError with line number if any line cannot be parsed
• 100% backwards compatible — existing behavior unchanged when strict=False (default)

Motivation

Silent failures are the #1 complaint about python-dotenv across GitHub issues, blog posts, and community discussions:

• Raise exceptions when encountering errors in files. #467 — "Raise exceptions when encountering errors in files" (open since 2023)
• requireFile option for strict checking of env file existence #297 — "requireFile option for strict checking of env file existence" (closed without implementation)
• load_dotenv() returns True even if .env file is not found #321 — load_dotenv() used to return True even when file not found (fixed by feat: return False when we do not discover any environment variables #388, but no exception option)
• File parsing: Option to raise exception instead of warning #520 — Open PR for parse-error exceptions (not yet merged)
• Feature Request: Exception or Warning on Duplicate Configuration Items #591 — "Exception or Warning on Duplicate Configuration Items" (open, 2025)
• dotenv_load with bad file path doesn't error #164 — "dotenv_load with bad file path doesn't error" (2019)

The DEV Community article "Why load_dotenv() Is an Anti-Pattern" specifically cites silent failures as the primary reason developers migrate to alternatives.

Real-world impact from PR #520: "I dealt with an .env file that accidentally contained an unparsable line. The software then set a default value and I almost wrote to a wrong database."

Design Philosophy — Parser Correctness, Not Config Validation

This PR intentionally stays within python-dotenv's existing philosophy of "populate what is available, let consuming code validate requirements." strict mode does not validate whether specific keys exist, whether values are the correct type, or whether the configuration is "complete" — that is the domain of tools like pydantic-settings.

What strict does is make python-dotenv honest about its own job: "did the file I was asked to read exist?" and "could I parse every line in it?" These are parser-level guarantees, not application-level config validation.

Usage

from dotenv import load_dotenv

# Existing behavior preserved (default)
load_dotenv()

# Opt-in strict mode — fail fast on missing file or parse errors
load_dotenv(strict=True)

# Works with dotenv_values too
from dotenv import dotenv_values
values = dotenv_values(".env", strict=True)

What changes

Scenario	strict=False (default)	strict=True
File not found	Returns False	Raises FileNotFoundError
Unparseable line	logger.warning()	Raises ValueError with line number
Valid file	Returns True	Returns True

Interaction with verbose

strict takes precedence over verbose. When both are True, the exception is raised without emitting a warning first — logging the same message before raising would be redundant since the exception already carries the information. When strict=False, verbose continues to work exactly as before.

strict	verbose	Missing file behavior
False	False	Silent (returns False)
False	True	logger.info() warning
True	False	Raises FileNotFoundError
True	True	Raises FileNotFoundError (no warning logged)

Changes

• src/dotenv/main.py: Added strict parameter to DotEnv.__init__(), load_dotenv(), dotenv_values(), and with_warn_for_invalid_lines(). Docstrings explicitly document strict vs verbose precedence.
• tests/test_main.py: Added 14 tests covering all strict mode scenarios + backwards compatibility verification

Test plan

• All 127 tests pass (113 existing + 14 new)
• ruff check passes
• ruff format --check passes
• Backwards compatibility verified: strict defaults to False, no behavior change for existing users

Closes #631
Related: #467, #297, #321, #520, #591, #164