$ show theskumar/python-dotenv
python-dotenv is a production-grade Python library that reads key-value pairs from .env files and sets them as environment variables, following the 12-factor configuration principles. It is widely used in development and deployment workflows to separate configuration from code. The library provides both programmatic APIs and a command-line interface for managing environment variables without manual file editing. The architecture centers on the `DotEnv` class, which orchestrates parsing, variable interpolation, and environment loading. Parsing is handled by a custom streaming parser (`parser.py`) that uses a `Reader` with position tracking and regex-based tokenization to handle single/double quoted values, comments, escape sequences, and UTF-8 BOM stripping. Variable expansion (`variables.py`) implements POSIX-style `${VAR:-default}` interpolation using an `Atom` abstract base class with `Literal` and `Variable` strategies. The core library has zero external dependencies; the CLI (built on `click`) and IPython integration are optional extras. Key entry points include `load_dotenv()` (loads .env into `os.environ`), `dotenv_values()` (returns a dict without touching the environment), `set_key()`/`unset_key()` for programmatic file manipulation, and `find_dotenv()` for locating .env files. The CLI offers `list`, `get`, `set`, `unset`, and `run` subcommands, with support for JSON/shell/export output formats. The IPython `%dotenv` magic provides interactive loading. Data flows from file or stream through the parser into an ordered dict, with optional interpolation and override control. External dependencies are minimal: `click` for the CLI, `IPython` for the magic extension, and standard library modules (`os`, `io`, `re`, `tempfile`, `pathlib`, etc.). The library supports Python 3.10–3.14 (including free-threaded 3.14t) and PyPy 3.11, with comprehensive CI testing across Linux and Windows.
The LLM identified 2 files worth highlighting for reuse:
Implements a streaming parser for .env file format. Uses a `Reader` class with character position and line tracking to parse key-value bindings, handling single/double quoted values, inline comments, escape sequences, multiline values, and UTF-8 BOM stripping. The parser yields `Binding` named tuples and is fully self-contained (stdlib only). Demonstrates robust error handling with per-line error flags and could be extracted for parsing similar configuration formats.
Implements POSIX variable expansion (`${VAR:-default}`) using an `Atom` abstract base class with `Literal` and `Variable` concrete strategies. The `parse_variables` function tokenizes a value string into a sequence of `Atom` objects, each with a `resolve` method that looks up variables in a provided environment mapping. This is a clean, reusable component for variable interpolation in any context, with no dependencies beyond the standard library.