Metadata-Version: 2.4
Name: fast-dotenv-rs
Version: 0.1.1
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Dist: click>=5.0
Requires-Dist: pytest>=8,<9 ; extra == 'test'
Requires-Dist: click>=5.0 ; extra == 'test'
Requires-Dist: ipython>=8 ; extra == 'test'
Provides-Extra: cli
Provides-Extra: test
License-File: LICENSE
License-File: licenses/python-dotenv-BSD-3-Clause.txt
Summary: Fast Rust-backed drop-in replacement for python-dotenv 1.2.2
Keywords: dotenv,python-dotenv,env,parser,pyo3,rust,environment-variables,drop-in-replacement
Home-Page: https://github.com/lowmiaq-gmail/fast-dotenv-rs
Author: fast-dotenv-rs contributors
License-Expression: MIT AND BSD-3-Clause
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/lowmiaq-gmail/fast-dotenv-rs/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/lowmiaq-gmail/fast-dotenv-rs
Project-URL: Issues, https://github.com/lowmiaq-gmail/fast-dotenv-rs/issues
Project-URL: Repository, https://github.com/lowmiaq-gmail/fast-dotenv-rs

# fast-dotenv-rs

[![CI](https://github.com/lowmiaq-gmail/fast-dotenv-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/lowmiaq-gmail/fast-dotenv-rs/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/fast-dotenv-rs.svg)](https://pypi.org/project/fast-dotenv-rs/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![Rust](https://img.shields.io/badge/Rust-PyO3-orange.svg)](https://pyo3.rs/)
[![License](https://img.shields.io/badge/license-MIT%20AND%20BSD--3--Clause-green.svg)](LICENSE)

A fast Rust-backed drop-in replacement for `python-dotenv==1.2.2`, built with
PyO3 and Maturin. It preserves the `dotenv` Python API, CLI, IPython extension,
interpolation rules, and file mutation behavior.

[中文说明](README.zh-CN.md)

```python
from dotenv import dotenv_values, load_dotenv

load_dotenv()
config = dotenv_values(".env")
```

The distribution is named `fast-dotenv-rs`, but existing application code keeps
importing `dotenv`.

## Why this project

- **Low migration cost:** keep `from dotenv import load_dotenv` and the `dotenv` CLI.
- **Verifiable compatibility:** run the complete pinned `python-dotenv==1.2.2`
  upstream suite, not only basic `KEY=value` examples.
- **Reproducible performance evidence:** compare candidate and Oracle in isolated
  processes and validate values, types, and ordering before timing.
- **Cross-platform packaging:** build abi3 wheels with PyO3 and Maturin.

## Status

Version `0.1.1` is the formal-release line. It makes Click a default dependency so a
plain public install provides the complete `dotenv` CLI. The release workflow
builds five native wheels and one sdist, publishes that immutable set through
Trusted Publishing, then reinstalls the base public package and passes the full
upstream compatibility suite on every advertised platform before creating the
formal GitHub Release. Until those public links exist, the release remains blocked.

[GitHub Actions CI #3](https://github.com/lowmiaq-gmail/fast-dotenv-rs/actions/runs/31511953697)
passed all four jobs:

| Platform | Python | Installed-wheel verification |
|---|---:|---|
| Linux x86-64 | 3.10 and 3.12 | Rust gates, project tests, 10,000-case differential gate, full upstream suite, artifact audit |
| macOS arm64 | 3.12 | wheel install, CLI, 219 upstream tests passed |
| Windows x86-64 | 3.12 | wheel install, CLI, 169 passed / 50 upstream platform skips |

The local Linux x86-64 / CPython 3.12 upstream result is:

```text
218 passed, 1 skipped, 0 failed
```

The single Linux skip is an upstream platform/root condition. IPython was installed,
so all three upstream IPython tests ran.

## Installation

After the `0.1.1` public release exists, install the package with:

```bash
python -m pip install "fast-dotenv-rs==0.1.1"
```

Application code continues importing `dotenv`. To build from source instead:

```bash
git clone https://github.com/lowmiaq-gmail/fast-dotenv-rs.git
cd fast-dotenv-rs
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
python -m pip install -U pip maturin
maturin develop --release
```

Build a wheel:

```bash
maturin build --release --out wheelhouse
python -m pip install wheelhouse/*.whl
```

### Do not install the Oracle in the same environment

Both `python-dotenv` and this project provide the top-level `dotenv` package and
the `dotenv` command. Installing both in one environment causes the last installed
distribution to overwrite the other. Use separate virtual environments for
candidate/Oracle comparisons.

## Compatible surface

Top-level exports match `python-dotenv==1.2.2`:

```python
from dotenv import (
    dotenv_values, find_dotenv, get_cli_string, get_key,
    load_dotenv, load_ipython_extension, set_key, unset_key,
)
```

The compatibility surface also includes:

- `dotenv.main.DotEnv`, `rewrite`, and `resolve_variables`;
- parser `Binding`, `Original`, `Reader`, `Position`, and parser functions;
- variable `Atom`, `Literal`, `Variable`, and `parse_variables`;
- CLI `list`, `set`, `get`, `unset`, and `run`;
- `dotenv.ipython.IPythonDotEnv` and the `%dotenv` magic.

See [`docs/UPSTREAM-CONTRACT.md`](docs/UPSTREAM-CONTRACT.md) for signatures,
return values, logging, exceptions, filesystem effects, and environment behavior.

## CLI

```bash
dotenv list
dotenv list --format=json
dotenv set DATABASE_URL 'postgres://localhost/app'
dotenv get DATABASE_URL
dotenv unset DATABASE_URL
dotenv run -- python app.py
python -m dotenv --version
```

## Reproduce the compatibility gates

```bash
python -m pip install "pytest>=8,<9" "click>=5" "ipython>=8"
cargo test --all-targets
PYTHONPATH=python python -m pytest -q tests
bash scripts/run_upstream_full.sh
PYTHONPATH=python python scripts/run_differential.py
```

The upstream runner pins and verifies the official `python-dotenv==1.2.2` sdist
and every upstream test fixture hash. It also checks that the candidate, not an
installed Oracle, owns the imported `dotenv` namespace.

## Benchmark snapshot

On one Linux x86-64 / CPython 3.12 machine, isolated-process `dotenv_values()`
in-memory parsing workloads measured **15.957×–88.609×** faster. The harness checks
the return type, item order, and values before timing.

```bash
python tests/benchmark.py --repeats 7 --warmup 2 --iterations 1000
```

These numbers do not represent file I/O, process startup, macOS, Windows, or every
application workload. See [`BENCHMARK.md`](BENCHMARK.md) for inputs, raw context,
and limitations.

## Documentation

- [`FULL-RELEASE-REPORT.md`](FULL-RELEASE-REPORT.md) — current evidence and remaining release gates;
- [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) — compatibility matrix;
- [`docs/UPSTREAM-CONTRACT.md`](docs/UPSTREAM-CONTRACT.md) — pinned upstream contract;
- [`docs/REUSE-AUDIT.md`](docs/REUSE-AUDIT.md) — reuse and license audit;
- [`docs/LAUNCH-SEO.md`](docs/LAUNCH-SEO.md) — launch, discovery, and adoption plan.
- [`docs/LAUNCH-STATUS.md`](docs/LAUNCH-STATUS.md) — evidence-backed public launch status and review checkpoints.

## License

Rust/PyO3 project code is MIT licensed. BSD-3-Clause notices for the upstream
compatibility baseline are recorded in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)
and [`licenses/`](licenses/).

