Metadata-Version: 2.4
Name: runenv
Version: 1.3.0
Project-URL: Documentation, https://github.com/onjin/runenv#readme
Project-URL: Issues, https://github.com/onjin/runenv/issues
Project-URL: Source, https://github.com/onjin/runenv
Author-email: Marek Wywiał <onjinx@gmail.com>
License-Expression: MIT
License-File: AUTHORS.md
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.7
Provides-Extra: devel
Requires-Dist: coverage[toml]; extra == 'devel'
Requires-Dist: mkchangelog; extra == 'devel'
Requires-Dist: mkdocs; extra == 'devel'
Requires-Dist: mkdocs-material; extra == 'devel'
Requires-Dist: mypy; extra == 'devel'
Requires-Dist: pytest; extra == 'devel'
Requires-Dist: pytest-cov; extra == 'devel'
Requires-Dist: ruff==0.11.12; extra == 'devel'
Provides-Extra: devel-docs
Requires-Dist: mkdocs; extra == 'devel-docs'
Requires-Dist: mkdocs-material; extra == 'devel-docs'
Provides-Extra: devel-test
Requires-Dist: coverage[toml]; extra == 'devel-test'
Requires-Dist: pytest; extra == 'devel-test'
Requires-Dist: pytest-cov; extra == 'devel-test'
Provides-Extra: devel-types
Requires-Dist: mypy; extra == 'devel-types'
Provides-Extra: toml
Requires-Dist: tomli; (python_version < '3.11') and extra == 'toml'
Provides-Extra: yaml
Requires-Dist: pyyaml; extra == 'yaml'
Description-Content-Type: text/markdown

# runenv

Manage application settings with ease using `runenv`, a lightweight tool inspired by [The Twelve-Factor App](https://12factor.net/config) methodology for configuration through environment variables.

`runenv` provides:
- A CLI for language-agnostic `.env` profile execution
- A Python API for programmatic `.env` loading

> “Store config in the environment” — [12factor.net/config](https://12factor.net/config)

| Section  | Status |
|----------|--------|
| CI/CD    | [![CI - Test](https://github.com/onjin/runenv/actions/workflows/test.yml/badge.svg)](https://github.com/onjin/runenv/actions/workflows/test.yml) |
| PyPI     | [![PyPI - Version](https://img.shields.io/pypi/v/runenv.svg?logo=pypi&label=PyPI)](https://pypi.org/project/runenv/) [![Downloads](https://img.shields.io/pypi/dm/runenv.svg?color=blue)](https://pypi.org/project/runenv/) |
| Python   | [![Python Versions](https://img.shields.io/pypi/pyversions/runenv.svg?logo=python&label=Python)](https://pypi.org/project/runenv/) |
| Style    | [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) |
| License  | [![License - MIT](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/) |
| Docs     | [CHANGELOG.md](CHANGELOG.md) |

---

## Table of Contents

- [Key Features](#key-features)
- [Quick Start](#quick-start)
  - [Installation](#installation)
  - [CLI Usage](#cli-usage)
  - [Python API](#python-api)
- [Multiple Profiles](#multiple-profiles)
- [Framework Integrations](#framework-integrations)
- [Sample `.env` File](#sample-env-file)
- [Similar Tools](#similar-tools)

---

## Key Features

- 🚀 **CLI-First**: Use `.env` files across any language or platform.
- 🐍 **Python-native API**: Load and transform environment settings inside Python.
- ⚙️ **Multiple Profiles**: Switch easily between `.env.dev`, `.env.prod`, etc.
- ⚙️ **Multiple Formats**: Use plain `.env`, `.env.json`, `.env.toml`, or `.env.yaml`
- ⚙️ **Autodetect Env File**: Looking for `.env`, `.env.json`, `.env.toml`, and `.env.yaml`
- 🧩 **Framework-Friendly**: Works well with Django, Flask, FastAPI, and more.

---

## Quick Start

### Installation

```bash
pip install runenv
pip install runenv[toml] # if you want to use .env.toml in python < 3.11
pip install runenv[yaml] # if you want to use .env.yaml
```

### CLI Usage

Run any command with a specified environment:

```bash
runenv run --env-file .env.dev -- python manage.py runserver
runenv run --env-file .env.prod -- uvicorn app:app --host 0.0.0.0
runenv list [--env-file .env] # view parsed variables
runenv lint [--env-file .env] # check common errors in env file
```

---

## Python API

### Load `.env` into `os.environ`

> **Note**: The `load_env` will not parse env_file if the `runenv` CLI was used, unless you `force=True` it.

```python
from runenv import load_env

load_env() # loads .env
load_env(
    env_file=".env.dev",    # file to load - will be autodetected if not passed
    prefix='APP_',          # load only APP_.* variables from file
    strip_prefix=True,      # strip ^ prefix when loading variables
    force=True,             # load env_file even if the `runvenv` CLI was used
    search_parent=1,        # look for env_file in current dir and its 1 parent dirs
    require_env_file=False  # raise error if env file is missing, otherwise just ignore
)
```

### Read `.env` as a dictionary

```python
from runenv import create_env

config = create_env() # parse .env content into dictionary
config = create_env(
    env_file=".env.dev",    # file to load - will be autodetected if not passed
    prefix='APP_',          # parse only APP_.* variables from file
    strip_prefix=True,      # strip ^ prefix when parsing variables
    search_parent=1,        # look for env_file in current dir and its 1 parent dirs
)
print(config)
```

Options include:
- Filtering by prefix
- Automatic prefix stripping
- Searching parent directories

---

## Multiple Profiles

Use separate `.env` files per environment:

```bash
runenv .env.dev flask run
runenv .env.staging python main.py
runenv .env.production uvicorn app.main:app
```

Recommended structure:
```
.env.dev
.env.test
.env.staging
.env.production
```

---

## Framework Integrations

> **Note**: If you're using `runenv .env [./manage.py, ...]` CLI then you do not need change your code. Use these integrations only if you're using Python API.

### Django

```python
# manage.py or wsgi.py
from runenv import load_env
load_env(".env")
```

### Flask

```python
from flask import Flask
from runenv import load_env

load_env(".env")
app = Flask(__name__)
```

### FastAPI

```python
from fastapi import FastAPI
from runenv import load_env

load_env(".env")
app = FastAPI()
```

---

## Sample `.env` File

```ini
# Basic
DEBUG=1
PORT=8000

# Nested variable
HOST=localhost
URL=http://${HOST}:${PORT}

# Quotes and comments
EMAIL="admin@example.com" # Inline comment
SECRET='s3cr3t'
```

---

## Similar Tools

- [python-dotenv](https://github.com/theskumar/python-dotenv) – Python-focused, lacks CLI tool
- [envdir](https://github.com/jezdez/envdir) – Directory-based env manager
- [dotenv-linter](https://github.com/dotenv-linter/dotenv-linter) – Linter for `.env` files

---

With `runenv`, you get portable, scalable, and explicit configuration management that aligns with modern deployment standards. Ideal for CLI usage, Python projects, and multi-environment pipelines.
