How public-repositories/python-dotenv works
Project Type and Purpose
• Type: A small, open-source Python library/tool with both an API and command-line interface.
• Purpose: Read key-value pairs from one or more .env sources (filesystem, streams), parse them according to Bash-like syntax (with interpolation and multiline support), and either (a) set them in os.environ or (b) return them as a dict.
• Extensions: A CLI (dotenv command) and an IPython extension (%load_ext dotenv).
File Structure
• src/dotenv/ – core modules:
• parser.py – tokenizes and parses .env syntax.
• variables.py – resolves variable interpolation and defaulting rules.
• main.py – public APIs: load_dotenv, dotenv_values, find_dotenv.
• cli.py – subcommands (set, get, list, run).
• ipython.py – registers IPython magics.
• version.py – version info.
• Entry points: declared via setup.py/pyproject.toml:
• Console script dotenv → cli.py.
• IPython extension → ipython.py.
• Tests: mirror each component.
• Config: tox.ini, Makefile, CI in .github/workflows.
Extract Key Architectural Insights from README
• Core operations: load from file vs. stream, parse → expand → apply.
• Two modes: override or preserve existing environment.
• Exposed to three audiences: Python code (API), CLI users, IPython users.
• Supports extensibility by passing custom streams to parser functions.
a. Main Components
1. User code / Applications
2. python-dotenv Core Library
• Parser Module
• Variable Resolver
• Loader Engine (load_dotenv / dotenv_values)
3. CLI Tool (dotenv)
4. IPython Extension
5. Data Sources
• .env File(s) on Disk
• In-Memory Streams (e.g. StringIO)
6. Target Environment
• os.environ (Process Environment)
b. Relationships & Data Flow
• Users invoke API → calls Loader Engine → reads Data Source → Parser → Resolver →
either mutates os.environ or returns a dict.
• CLI wraps Loader Engine; parses CLI args, calls same Loader Engine, then prints or applies.
• IPython Extension bootstraps Loader Engine at notebook startup.
c. Architectural Patterns & Principles
• Single Responsibility: each module has a clear role.
• Separation of concerns: parsing vs. variable resolution vs. application layer (API/CLI/IPython).
• Extensibility: Loader Engine accepts generic streams.
• Twelve-Factor compliance: configuration as code, environment decoupling.
d. Key Technologies & Libraries
• Python standard library (io, os, re)
• click or argparse (depending on CLI implementation)
• IPython plugin API
Detail Checklist
• Override vs. non-override logic path in the Loader Engine.
• Call out the two main API functions: load_dotenv vs. dotenv_values.
• IPython’s %dotenv magic hooking into the same pipeline.