oneenv 0.2.0

OneEnv: Environment variable management and generation tool

OneEnv 🌟　

OneEnv is a revolutionary environment variable management tool for Python applications that makes configuration management incredibly simple. It automatically discovers and consolidates environment variable templates from all your installed packages into a single .env.example file - no manual configuration required!

Why OneEnv Makes Your Life Easier 🚀

Before OneEnv:

• 😓 Manual creation of .env.example files for each project
• 😤 Hunting through documentation to find required environment variables
• 😱 Missing critical configuration when integrating new packages
• 🤯 Inconsistent environment variable formats across projects

After OneEnv:

• ✨ Automatic discovery of environment variables from all packages
• 🎯 One command generates complete .env.example files
• 🔄 Smart merging of duplicate variables with detailed descriptions
• 📦 Plugin ecosystem where packages provide their own templates
• 🛡️ Type safety with Pydantic validation

Revolutionary Features 🌟

🔌 Plugin System with Entry-points

Packages can automatically provide their environment variable templates - just install and use!

🎨 Smart Duplicate Handling

When multiple packages define the same variable, OneEnv intelligently merges descriptions while keeping configuration consistent.

⚡ Zero Configuration Setup

Install a package with OneEnv templates? They're automatically discovered. No imports, no manual registration needed.

🔒 Type-Safe Templates

Built with Pydantic models for runtime validation and better error messages.

📋 Legacy Decorator Support

Existing @oneenv decorators continue to work seamlessly alongside the new plugin system.

Supported Environments 🖥️

• Python: ≥ 3.10
• Operating Systems: Windows, macOS, Linux

Installation 📦

You can install OneEnv easily via pip:

pip install oneenv

For development mode, install from the source using:

pip install -e .

Super Simple Usage 🎯

Step 1: Install Packages with OneEnv Support

pip install oneenv
pip install django-oneenv-plugin  # Example: Django templates
pip install fastapi-oneenv-plugin # Example: FastAPI templates

Step 2: Generate Your Environment Template

oneenv template

That's it! 🎉 OneEnv automatically discovers all environment variables from your installed packages and creates a complete .env.example file.

Advanced Usage 🚀

🔍 See What's Discovered

oneenv template -d

This shows you:

• 📦 Which plugins were discovered
• 🔄 Which variables are duplicated across packages
• ⚡ Template generation process

📝 Custom Output File

oneenv template -o my-custom.env

🔄 Compare Environment Files

oneenv diff old.env new.env

For Package Developers: Creating OneEnv Plugins 📦

Method 1: Modern Plugin System (Recommended) ⭐

Create environment templates that are automatically discovered:

1. Create your template function:

# mypackage/templates.py
def database_template():
    """Database configuration template"""
    return {
        "DATABASE_URL": {
            "description": "Database connection URL\nExample: postgresql://user:pass@localhost:5432/db",
            "default": "sqlite:///app.db",
            "required": True
        },
        "DB_POOL_SIZE": {
            "description": "Database connection pool size",
            "default": "10",
            "required": False,
            "choices": ["5", "10", "20", "50"]
        }
    }

2. Register in pyproject.toml:

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

3. That's it! 🎉 When users install your package, OneEnv automatically discovers your templates.

Method 2: Legacy Decorator System 📋

Still supported for backward compatibility:

from oneenv import oneenv

@oneenv
def my_env_template():
    return {
        "MY_API_KEY": {
            "description": "API key for accessing the service",
            "default": "",
            "required": True
        },
        "MODE": {
            "description": "Application mode setting",
            "default": "development",
            "required": False,
            "choices": ["development", "production"]
        }
    }

Smart Duplicate Variable Handling 🎨

When multiple packages define the same environment variable, OneEnv intelligently merges them:

Example Output:

# Auto-generated by OneEnv

# (Defined in: django-plugin, fastapi-plugin)
# Django database connection URL
# Example: postgresql://user:pass@localhost:5432/django_db
# From fastapi-plugin:
# FastAPI application database connection
# Supports: PostgreSQL, MySQL, SQLite
# Required
DATABASE_URL=sqlite:///django.db

# (Defined in: redis-plugin)
# Redis connection URL
# Example: redis://localhost:6379/0
REDIS_URL=redis://localhost:6379/0

How it works:

• ✅ Single entry: Each variable appears only once
• 📝 Merged descriptions: All package descriptions are combined
• ⚙️ First wins: Configuration (default, required, choices) uses the first package's settings
• 📋 Source tracking: Shows which packages define each variable

Template Field Reference 📚

{
    "VARIABLE_NAME": {
        "description": "Clear description of what this variable does",  # Required
        "default": "default_value",      # Optional: Default value
        "required": True,                # Optional: Whether required (default: False)
        "choices": ["option1", "option2"] # Optional: Valid choices
    }
}

Real-World Examples 🌍

Django + FastAPI + Redis Project

pip install oneenv django-oneenv fastapi-oneenv redis-oneenv
oneenv template

Generated .env.example:

# Auto-generated by OneEnv

# (Defined in: django-oneenv, fastapi-oneenv)
# Django database connection URL
# From fastapi-oneenv: FastAPI database connection
# Required
DATABASE_URL=sqlite:///django.db

# (Defined in: redis-oneenv)
# Redis connection for caching and sessions
REDIS_URL=redis://localhost:6379/0

# (Defined in: django-oneenv)
# Django secret key for security
# Required
SECRET_KEY=your-secret-key-here

Custom Project Templates

# myproject/env_templates.py
from oneenv import oneenv

@oneenv
def custom_project_config():
    return {
        "PROJECT_NAME": {
            "description": "Name of your awesome project",
            "default": "My Awesome App",
            "required": True
        },
        "ENVIRONMENT": {
            "description": "Deployment environment",
            "default": "development",
            "choices": ["development", "staging", "production"]
        }
    }

Integration with dotenv 🔄

OneEnv wraps python-dotenv, so you can use all dotenv features directly:

from oneenv import load_dotenv, dotenv_values

# Load environment variables
load_dotenv()

# Get variables as dictionary
config = dotenv_values(".env")

What's New in v0.2.0 🆕

🎉 Revolutionary Plugin System

• Entry-points Integration: Packages automatically provide environment variable templates
• Smart Duplicate Handling: Intelligent merging of variables from multiple packages
• Pydantic Type Safety: Runtime validation with clear error messages
• Zero Configuration: Automatic discovery - no imports or manual registration needed

🔄 Migration from v0.1.x

Your existing @oneenv decorators continue to work without any changes! The new plugin system runs alongside your current setup.

For package developers: Consider adding entry-points to your pyproject.toml for automatic discovery:

[project.entry-points."oneenv.templates"]
myfeature = "mypackage.templates:my_template_function"

Why OneEnv is Game-Changing 🎯

• 🚫 No more hunting: Environment variables are automatically documented
• ⚡ Zero setup time: Install packages, run one command, done
• 🔄 Stay synchronized: Environment configs update automatically with package updates
• 👥 Team harmony: Everyone gets the same environment setup
• 📦 Ecosystem growth: Package authors can provide better configuration experiences

Running Tests 🧪

pytest tests

Contributing 🤝

We welcome contributions! Please feel free to submit a Pull Request or open an issue on GitHub.

License ⚖️

This project is released under the MIT License.