OneEnv 🌟

Python environment variable management made simple.

OneEnv automatically discovers environment variable templates from your installed packages and manages them with namespaces.

Core Features 🎯

1. 🏗️ Intelligent Scaffolding System

Organize environment templates by categories (Database, VectorStore, LLM, etc.) with structured discovery and selective generation.

2. 📦 Package Environment Variable Discovery

Automatically collect environment variable templates from all installed packages - no manual configuration required.

3. 🏷️ Namespace Management

Organize environment variables by service/component with intelligent fallback.

4. 🛠️ Tool-Friendly APIs

Programmatic access to template structure for building custom scaffolding tools and integrations.

Installation 📦

pip install oneenv

Quick Start 🚀

Generate Environment Template

oneenv template

Explore Available Templates

# View all available categories and options
oneenv template --structure

# Get detailed info for a specific category
oneenv template --info Database

# Preview a specific option
oneenv template --preview Database postgres

# Generate custom configuration
oneenv template --generate Database:postgres VectorStore:chroma

Use Named Environments

import oneenv

# Load different environments
oneenv.env().load_dotenv("common.env")
oneenv.env("database").load_dotenv("database.env")
oneenv.env("web").load_dotenv("web.env")

# Get values with namespace fallback
db_host = oneenv.env("database").get("HOST", "localhost")
web_port = oneenv.env("web").get("PORT", "8000")
timeout = oneenv.env("database").get("TIMEOUT", "30")  # Falls back to common

Example: Before vs After

Before OneEnv:

# Scattered environment variables
DATABASE_URL = os.getenv("DATABASE_URL")
WEB_HOST = os.getenv("WEB_HOST")
API_KEY = os.getenv("API_KEY")

After OneEnv:

# Organized by namespace
db_url = oneenv.env("database").get("URL")
web_host = oneenv.env("web").get("HOST")
api_key = oneenv.env("api").get("KEY")

How It Works

1. Discovery: OneEnv finds environment variable templates from installed packages
2. Generation: Creates consolidated .env.example files
3. Namespace: Loads variables into separate namespaces with fallback to common settings

Advanced Usage: Scaffolding System 🏗️

OneEnv's intelligent scaffolding system organizes templates by categories and provides powerful APIs for custom tool development:

Interactive Template Discovery

# Discover available templates
oneenv template --structure

# Get category details with variable counts
oneenv template --info Database

# Preview what variables an option provides
oneenv template --preview Database postgres

# Generate templates with specific selections
oneenv template --generate Database:postgres VectorStore:chroma LLM:openai

# JSON output for automation
oneenv template --structure --json

Programmatic API for Custom Tools 🛠️

Build sophisticated scaffolding tools using OneEnv's comprehensive APIs:

import oneenv

# Discovery API
structure = oneenv.get_all_template_structure()
print("Available categories:", list(structure.keys()))
# Output: {'Database': ['postgres', 'sqlite'], 'VectorStore': ['chroma', 'pinecone']}

# Validation API
if oneenv.has_category("Database"):
    options = oneenv.get_options("Database")
    print(f"Database options: {options}")

# Information API
info = oneenv.get_category_info("Database")
print(f"Total variables: {info['total_variables']}")
print(f"Critical variables: {info['critical_variables']}")

# Preview API
preview = oneenv.get_option_preview("Database", "postgres")
for var_name, config in preview['variables'].items():
    print(f"{var_name}: {config['importance']} - {config['description']}")

# Generation API
selections = [
    {"category": "Database", "option": "postgres"},
    {"category": "VectorStore", "option": "chroma"},
    {"category": "LLM", "option": "openai"}
]

content = oneenv.generate_template(".env.example", selections)
print("Generated custom template with selected components!")

Create Package Templates 📦

Developers can create discoverable templates using the new scaffolding format:

# mypackage/templates.py
def database_template():
    return [
        {
            "category": "Database",
            "option": "postgres",
            "env": {
                "DATABASE_URL": {
                    "description": "PostgreSQL connection URL",
                    "default": "postgresql://user:pass@localhost:5432/dbname",
                    "required": True,
                    "importance": "critical"
                },
                "DATABASE_POOL_SIZE": {
                    "description": "Connection pool size",
                    "default": "10",
                    "required": False,
                    "importance": "important"
                }
            }
        },
        {
            "category": "Database",
            "option": "sqlite",
            "env": {
                "DATABASE_URL": {
                    "description": "SQLite database file path",
                    "default": "sqlite:///app.db",
                    "required": True,
                    "importance": "critical"
                }
            }
        }
    ]

Register in pyproject.toml:

[project.entry-points."oneenv.templates"]
database = "mypackage.templates:database_template"

Key Features:

• Category-based organization - Group related templates (Database, VectorStore, LLM, etc.)
• Multiple options per category - Provide alternatives (postgres, sqlite, mysql)
• Importance levels - Critical, Important, Optional for better user guidance
• Automatic discovery - Users automatically see your templates with oneenv template --structure

Learn More 📚

Step-by-Step Tutorials

🌱 Basics (5-10 min each)

1. Basic dotenv Usage - Learn environment variable fundamentals and OneEnv basics
2. Auto Template Generation - Discover how OneEnv automatically finds and generates environment templates
3. Named Environments - Master namespace management with intelligent fallback

🚀 Practical (10-15 min each)

4. Multi-Service Management - Configure complex applications with multiple services
5. Custom Templates - Create reusable project-specific templates
6. Production Best Practices - Secure configuration management for production environments

⚡ Advanced (15-20 min each)

7. Plugin Development - Build distributable OneEnv plugins for the community
8. CI/CD Integration - Automate configuration management in your deployment pipeline

🚀 New Scaffolding Features (10-20 min each)

9. New Template Creation - Create discoverable templates using the new scaffolding format
10. Scaffolding Tool Creation - Build custom scaffolding tools with OneEnv's APIs
11. Practical Guide - Real-world examples for RAG systems, web apps, and more

📚 Documentation

• Scaffolding Usage Guide - Comprehensive guide to the scaffolding system
• API Reference - Complete API documentation for custom tool development

Start here: Step 1: Basic dotenv Usage

License ⚖️

MIT License