Metadata-Version: 2.4
Name: oneenv
Version: 0.3.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 📚

### Basic Template (v0.1.x - v0.2.x)
```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
    }
}
```

### Enhanced Template (v0.3.0+)
```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
        "group": "Category Name",        # NEW: Group for organization
        "importance": "critical"         # NEW: critical/important/optional
    }
}
```

### Importance Levels
- **`critical`**: Essential settings for application operation (必須設定項目)
- **`important`**: Settings to configure for production use (重要設定項目)  
- **`optional`**: Fine-tuning settings where defaults are sufficient (デフォルトで十分)

## Real-World Examples 🌍

### Django + FastAPI + Redis Project
```bash
pip install oneenv django-oneenv fastapi-oneenv redis-oneenv
oneenv template
```

**Generated .env.example (v0.3.0 with grouping):**
```bash
# Auto-generated by OneEnv

# ========== CRITICAL: Essential Settings for Application Operation ==========

# ----- Database -----

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

# ----- Security -----

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

# ========== IMPORTANT: Settings to Configure for Production Use ==========

# ----- Cache -----

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

### Custom Project Templates (v0.3.0 Enhanced)
```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,
            "group": "Application",
            "importance": "critical"
        },
        "ENVIRONMENT": {
            "description": "Deployment environment",
            "default": "development",
            "choices": ["development", "staging", "production"],
            "group": "Application", 
            "importance": "important"
        },
        "LOG_ROTATION_DAYS": {
            "description": "Number of days to keep log files",
            "default": "30",
            "required": False,
            "group": "Logging",
            "importance": "optional"
        }
    }
```

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

### 🎯 **Smart Organization & Prioritization**
Environment variables are now intelligently organized by importance and grouped by category for maximum clarity:

- **📊 Grouping System**: Related variables are grouped together (Database, Security, Logging, etc.)
- **⚡ Importance Levels**: 
  - `critical`: Essential for application operation
  - `important`: Should be configured for production
  - `optional`: Fine-tuning settings (defaults are sufficient)
- **🌐 Multilingual Headers**: Automatic locale detection with Japanese/English support

### 📋 **Enhanced Template Format**
```python
@oneenv
def advanced_template():
    return {
        "DATABASE_URL": {
            "description": "Primary database connection",
            "default": "postgresql://localhost:5432/mydb",
            "required": True,
            "group": "Database",        # NEW: Group organization
            "importance": "critical"    # NEW: Priority level
        },
        "LOG_LEVEL": {
            "description": "Application logging level",
            "default": "INFO",
            "required": False,
            "group": "Logging",
            "importance": "important"
        }
    }
```

### 🌍 **Multilingual Support**
**Japanese Environment:**
```
# ========== CRITICAL: 必須設定項目 ==========
# ========== IMPORTANT: 重要設定項目 ==========
# ========== OPTIONAL: デフォルトで十分 ==========
```

**English Environment:**
```
# ========== CRITICAL: Essential Settings for Application Operation ==========
# ========== IMPORTANT: Settings to Configure for Production Use ==========
# ========== OPTIONAL: Fine-tuning Settings (Defaults are Sufficient) ==========
```

### 🔄 **Perfect Backward Compatibility**
All existing templates work unchanged! New features use sensible defaults:
- `group`: "General" (if not specified)
- `importance`: "important" (if not specified)

## Previous Updates

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

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