Metadata-Version: 2.4
Name: sane-settings
Version: 0.2.9
Summary: Add your description here
Author-email: Nicolas Paris <ni.paris@gmail.com>
Requires-Python: >=3.10
Requires-Dist: loguru
Description-Content-Type: text/markdown

# Sane Settings

Simply Sane Settings

Born of the desire of having app config behaving in an explicit way, to zero in and fix missing config very quickly

## Key Principles

1. **Explicit is better than implicit** - Never silently use defaults when you meant to configure something
2. **Fail fast with clarity** - Missing env vars show you exactly what was expected
3. **Debuggability** - Debug logs highlight when defaults are used, helping catch typos
4. **Security** - Secret values are masked in logs automatically

## Installation

```bash
pip install sane-settings
```

Requires Python 3.10 or higher.

## Quick Start

```python
from dataclasses import dataclass
from sane_settings import EnvConfigBase, env_field, prefix_field, SecretStr

@dataclass
class DatabaseSettings(EnvConfigBase):
    host: str = env_field("HOST", default="localhost")
    port: int = env_field("PORT", default=5432)
    password: SecretStr = env_field("PASSWORD")  # Required - will fail if missing

@dataclass
class AppSettings(EnvConfigBase):
    database: DatabaseSettings = prefix_field("DB")
    debug: bool = env_field("DEBUG", default=False)

# Load from environment
settings = AppSettings.load_from_env(app_prefix="MYAPP")

# Access nested settings
print(settings.database.host)  # Uses MYAPP_DB_HOST
print(settings.password)       # SecretStr('**********')
```

## Design Goals

- Having an extremely explicit settings library that minimise the time spent fighting with settings
- For attributes without defaults, if SaneSettings does not find a env var, it will fail loading and tell you EXACTLY what env var it was expecting.
- Any attributes with default that does NOT get replaced with an env var will be highlighted in logs (use DEBUG log level) which helps you quickly find typos in your Env Vars
- Only supports environment variables to override the defaults 

## Non Goals

- Loading from config files

## Advanced Example


```python
from sane_settings import (
    EnvConfigBase,
    Environments,
    SecretStr,
    env_field,
    prefix_field,
)


@dataclass
class DatabaseSettings(EnvConfigBase):
    """Database connection settings."""

    # Database connection parameters
    host: str = env_field("HOST", default="localhost")                # APP_DB_HOST
    port: int = env_field("PORT", default=5432)                       # APP_DB_PORT
    user: str = env_field("USER", default="postgres")                 # APP_DB_USER
    password: SecretStr = env_field("PASSWORD", default="postgres")   # APP_DB_PASSWORD, will NOT show in logs unless you use DatabaseSettings().password.get_secret_value()
    name: str = env_field("NAME", default="queue_service")            # APP_DB_NAME

    @property
    def uri(self) -> str:
        """Get the PostgreSQL connection URI."""
        return f"postgresql://{self.user}:{self.password.get_secret_value()}@{self.host}:{self.port}/{self.name}?sslmode=allow"


@dataclass
class Settings(EnvConfigBase):
    """Main application settings."""

    # Nested Settings objects
    database: DatabaseSettings = prefix_field("DB")     # Any nested attribute will use APP_DB_{atribute}
    
    # Basic settings
    TRACING_BACKEND: TracingBackends | None = env_field("TRACING_BACKEND")
    ENVIRONMENT: Environments = env_field("ENVIRONMENT")                    # a default enum for your environments


    # defaults at the end
    SERVICE_NAME: str = "my-service"


settings = Settings.load_from_env(app_prefix="APP", pretty_check=True)
```

## Documentation

| Document | Purpose |
|----------|---------|
| [User Guide](./docs/user-guide.md) | Getting started, configuration patterns, type casting, best practices |
| [API Reference](./docs/api-reference.md) | Complete reference for all public classes and functions |
| [Architecture Guide](./docs/architecture.md) | How the library works internally, type system, loading mechanism |
| [Examples](./docs/examples.md) | Real-world usage patterns for common scenarios |

## Development

### Release

(https://github.com/alltuner/uv-version-bumper)
just bump-patch|minor|major
just push-all

uv run pytest -v
