Metadata-Version: 2.4
Name: oneenv
Version: 0.2.0
Summary: OneEnv: Environment variable management and generation tool
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0; python_version < "3.10"
Provides-Extra: dev
Requires-Dist: pytest>=8.3.4; extra == "dev"
Dynamic: license-file

# OneEnv 🌟　[![PyPI Downloads](https://static.pepy.tech/badge/oneenv)](https://pepy.tech/projects/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:

```bash
pip install oneenv
```

For development mode, install from the source using:

```bash
pip install -e .
```

## Super Simple Usage 🎯

### Step 1: Install Packages with OneEnv Support
```bash
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
```bash
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
```bash
oneenv template -d
```
This shows you:
- 📦 Which plugins were discovered
- 🔄 Which variables are duplicated across packages
- ⚡ Template generation process

### 📝 Custom Output File
```bash
oneenv template -o my-custom.env
```

### 🔄 Compare Environment Files
```bash
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:**
```python
# 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:**
```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:

```python
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:**
```bash
# 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 📚

```python
{
    "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
```bash
pip install oneenv django-oneenv fastapi-oneenv redis-oneenv
oneenv template
```

**Generated .env.example:**
```bash
# 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
```python
# 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](https://github.com/theskumar/python-dotenv), so you can use all dotenv features directly:

```python
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:
```toml
[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 🧪

```bash
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.
