runenv

Manage your application’s settings with runenv, using the 12-factor principles. This library provides both a CLI tool and a Python API to simplify the management of environment variables in your projects.

CI/CD
Package
Meta
Changes	CHANGELOG.md

---

Table of Contents

• Features at a Glance
• Getting Started
  • Installation
  • Quick CLI Usage
  • Python API Overview
• In-Depth Usage and Examples
  • Using the CLI Tool
  • Python API Details
  • Framework Integration
• Example .env File
• Similar Projects

Features at a Glance

• CLI Tool: Run programs with customized environment variables from a .env file.
• Python API: Load and manage environment variables programmatically.
• Integration: Easily integrate with frameworks like Django and Flask.

---

Getting Started

Installation

To install runenv along with its CLI tool, run:

pip install runenv

Quick CLI Usage

1. Create a .env file in your project’s root directory:

   BASE_URL=http://127.0.0.1:8000
   DATABASE_URI=postgres://postgres:password@localhost/dbname

2. Run a command with the environment loaded from the .env file:

   runenv .env ./your_command

Python API Overview

You can load environment variables directly in Python:

from runenv import load_env

# Load variables from the specified .env file
load_env(".env")

In-Depth Usage and Examples

Using the CLI Tool

The runenv CLI provides flexibility to run any command with custom environment settings:

runenv .env.development ./manage.py runserver

Options:

• --prefix: Load variables with a specific prefix, e.g., DJANGO_.
• --strip-prefix: Remove the prefix from variable names after loading.
• --dry-run: Output the parsed .env file as environment without executing the command.

Full help and options:

runenv --help

Python API Details

load_env

Load variables into the environment:

load_env(env_file=".env", prefix="DJANGO_", strip_prefix=True, force=False, search_parent=0)

Parameters:

• env_file (str, optional): The environment file to read from (default is .env).
• prefix (str, optional): Load only variables that start with this prefix.
• strip_prefix (bool, optional): If True, removes the prefix from variable names when loaded (default is True).
• force (bool, optional): Force loading the .env file again even if already loaded by runenv CLI (default is False).
• search_parent (int, optional): Number of parent directories to search for .env file (default is 0).

create_env

Parse .env contents into a dictionary without modifying the environment:

env_vars = create_env(env_file=".env", prefix="APP_", strip_prefix=True)
print(env_vars)

Parameters:

• env_file (str, optional): The environment file to read from (default is .env).
• prefix (str, optional): Load only variables that start with this prefix.
• strip_prefix (bool, optional): If True, removes the prefix from variable names when loaded (default is True).

Framework Integration

Easily integrate runenv with web frameworks:

# In Django's manage.py or Flask's app setup
from runenv import load_env
load_env(".env")

Example .env File

The .env file can contain simple key-value pairs, comment lines, and inline comments:

# Base settings
BASE_URL=http://127.0.0.1:8000
DATABASE_URI=postgres://postgres:password@localhost/dbname

# Email configuration
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587  # Port for SMTP
EMAIL_USER="[email protected]"
EMAIL_PASSWORD='password'
EMAIL_USE_TLS=1

# Reusing variables
EMAIL_FROM=user@${EMAIL_HOST}

• Variables are set in KEY=VALUE pairs.
• Use # for comments.
• Inline comments are also supported after a #.

Similar Projects

• envdir: Run programs with a modified environment based on files in a directory.
• python-dotenv: Reads key-value pairs from .env files and adds them to the environment.

---

With runenv, managing environment variables becomes simpler and more consistent, making it easier to develop and deploy applications across different environments.