Skip to content

Latest commit

 

History

History
177 lines (123 loc) · 6.04 KB

README.md

File metadata and controls

177 lines (123 loc) · 6.04 KB

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.

Section Details
CI/CD CI - Test
Package PyPI - Version
Downloads PyPI - Downloads
Python Version PyPI - Python Version
Meta Linting - Ruff Code Style - Black Types - MyPy
License License - MIT
Changes CHANGELOG.md

Table of Contents

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:

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 #.

  1. 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

Full help and options:

runenv --help
usage: runenv [-h] [-V] [-v {1,2,3}] [-p PREFIX] [-s] [--dry-run] env_file command

Run program with given environment file loaded

positional arguments:
  env_file              Environment file to load
  command               Command to run with loaded environment

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -v {1,2,3}, --verbosity {1,2,3}
                        verbosity level, 1 - (ERROR, default), 2 - (INFO) or 3 - (DEBUG)
  -p PREFIX, --prefix PREFIX
                        Load only variables with given prefix
  -s, --strip-prefix    Strip prefix given with --prefix from environment variables names
  --dry-run             Return parsed .env instead of running command

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")

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.