Metadata-Version: 2.4
Name: envguard-python
Version: 0.1.0
Summary: A Python utility for robust serverless environment variable validation using Pydantic
Project-URL: Homepage, https://github.com/envguard/envguard
Project-URL: Documentation, https://github.com/envguard/envguard/tree/main/packages/envguard-python#readme
Project-URL: Repository, https://github.com/envguard/envguard.git
Project-URL: Issues, https://github.com/envguard/envguard/issues
Author-email: EnvGuard Contributors <envguard@example.com>
License: MIT
Keywords: aws-lambda,azure-functions,configuration,environment-variables,google-cloud-functions,pydantic,serverless,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pydantic
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.5.0
Provides-Extra: dev
Requires-Dist: black>=23.3.0; extra == 'dev'
Requires-Dist: mypy>=1.3.0; extra == 'dev'
Requires-Dist: ruff>=0.0.270; extra == 'dev'
Requires-Dist: types-setuptools>=68.0.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# EnvGuard for Python

A lightweight, efficient utility for validating serverless function environment variables against defined schemas at cold start.

## Features

- 🚀 Optimized for serverless cold starts
- 🛡️ Strong type validation using Pydantic models
- 🔍 Clear, structured error messages
- 💻 Simple, intuitive API
- ⚡ Fail-fast approach for robust serverless functions

## Installation

```bash
pip install envguard-python
```

## Quick Start

```python
from pydantic import BaseModel, EmailStr
from envguard_python import load_env_or_fail

class AppConfig(BaseModel):
    # Required environment variables
    DATABASE_URL: str
    API_KEY: str
    ADMIN_EMAIL: EmailStr

    # Optional environment variables with defaults
    DEBUG: bool = False
    PORT: int = 8000
    ENVIRONMENT: str = "development"

try:
    # Validate environment variables at cold start
    config = load_env_or_fail(AppConfig)

    # Use the validated configuration
    print(f"Running on port {config.PORT}")
    print(f"Debug mode: {config.DEBUG}")

except EnvGuardValidationError as e:
    print("Environment validation failed:")
    print(e)  # Prints detailed error messages
    raise  # Re-raise to fail the function
```

## Usage Examples

### Basic Usage

```python
from pydantic import BaseModel
from envguard_python import load_env_or_fail

class DatabaseConfig(BaseModel):
    DB_HOST: str
    DB_PORT: int
    DB_NAME: str
    DB_USER: str
    DB_PASSWORD: str

# Will raise EnvGuardValidationError if any required variables are missing
# or if type validation fails (e.g., if DB_PORT is not a valid integer)
db_config = load_env_or_fail(DatabaseConfig)
```

### With Pydantic Validators

```python
from pydantic import BaseModel, field_validator
from envguard_python import load_env_or_fail

class APIConfig(BaseModel):
    API_URL: str
    API_TIMEOUT: int = 30
    API_RETRIES: int = 3

    @field_validator("API_TIMEOUT", "API_RETRIES")
    def validate_positive(cls, v: int) -> int:
        if v <= 0:
            raise ValueError("must be positive")
        return v

# Will use Pydantic's validation system
api_config = load_env_or_fail(APIConfig)
```

### Error Handling

```python
from envguard_python import load_env_or_fail, EnvGuardValidationError

try:
    config = load_env_or_fail(AppConfig)
except EnvGuardValidationError as e:
    # Access structured error information
    for var_name, error in e.errors.items():
        print(f"Error in {var_name}: {error}")

    # Or use the formatted string representation
    print(e)  # Includes all errors in a readable format

    # Handle the error (e.g., log to error monitoring, fail fast)
    raise
```

## API Reference

### `load_env_or_fail`

```python
def load_env_or_fail(
    schema_model: Type[SupportsEnvironmentValidation],
    **kwargs: Any
) -> Any:
    """
    Load and validate environment variables against a schema model.

    Args:
        schema_model: A Pydantic model class defining the environment schema
        **kwargs: Additional keyword arguments passed to Pydantic's model_validate

    Returns:
        An instance of the schema model populated with validated environment variables

    Raises:
        EnvGuardValidationError: If environment variables fail validation
    """
```

### `EnvGuardValidationError`

```python
class EnvGuardValidationError(Exception):
    """
    Raised when environment variable validation fails.

    Attributes:
        message (str): Human-readable error message
        errors (Dict[str, Any]): Dictionary of validation errors
    """
```

## Best Practices

1. **Fail Fast**: Validate environment variables at cold start before any other initialization.
2. **Type Safety**: Use appropriate Pydantic field types for strong validation.
3. **Default Values**: Provide sensible defaults for non-critical configuration.
4. **Documentation**: Include examples of required environment variables in your project's README.
5. **Error Handling**: Always catch and handle validation errors appropriately.

## Contributing

Contributions are welcome! Please see the main project [Contributing Guidelines](../../CONTRIBUTING.md).

## License

This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
