Metadata-Version: 2.4
Name: paraboloski-dotenv
Version: 1.0.0
Summary: Minimal environment variable helpers with explicit failure semantics.
Author-email: Paraboloski <andreapetracca155@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Andrea Petracca
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# paraboloski-dotenv

Lightweight wrapper around `os.getenv()` inspired by Go: explicit config, fail-fast startup, no silent misconfiguration.

- use `env()` when a value can have a fallback
- use `require()` when the application cannot run without it

---

# Install

```bash
uv add paraboloski-dotenv
pip install paraboloski-dotenv
```

GitHub:

```bash
uv add git+https://github.com/paraboloski/snippet-toolbox/python#subdirectory=snippet/paraboloski-dotenv
```

---

# env() vs require()

| | `env()` | `require()` |
|---|---|---|
| Missing value | fallback or error | immediate crash (`panic`) |
| Use case | optional config | required config |

---

# Usage

```python
from dotenv import env, require

# optional
POOL_SIZE = int(env("POOL_SIZE", "10"))
TIMEOUT = int(env("TIMEOUT", "30"))

# required
DATABASE_URL = require("DATABASE_URL")
JWT_SECRET = require("JWT_SECRET")
```

---

# Production behavior

Missing required variable:

```
[PANIC] Missing environment variable: 'DATABASE_URL'
exit code 1
```

App fails fast instead of starting in a broken state.

---

# Compared to os.getenv()

```python
# fragile
DATABASE_URL = os.getenv("DATABASE_URL")

if not DATABASE_URL:
    raise RuntimeError("missing")
```

vs

```python
# explicit
DATABASE_URL = require("DATABASE_URL")
```

Less boilerplate. Clear intent. Safer startup.

---

---

# Italiano

Wrapper leggero di `os.getenv()` ispirato a alla filosofia di Go: configurazione esplicita e fail-fast.

- Utilizzare `env()` quando un valore può avere un valore di fallback
- Utilizzare `require()` quando l'applicazione non può funzionare senza di esso

---

# Installazione

```bash
uv add paraboloski-dotenv
pip install paraboloski-dotenv
```

GitHub:

```bash
uv add git+https://github.com/paraboloski/snippet-toolbox/python#subdirectory=snippet/paraboloski-dotenv
```

---

# env() vs require()

| | `env()` | `require()` |
|---|---|---|
| Valore mancante | fallback o errore | crash immediato (`panic`) |
| Uso | config opzionale | config obbligatoria |

---

# Utilizzo

```python
from dotenv import env, require

# opzionale
POOL_SIZE = int(env("POOL_SIZE", "10"))
TIMEOUT = int(env("TIMEOUT", "30"))

# obbligatorio
DATABASE_URL = require("DATABASE_URL")
JWT_SECRET = require("JWT_SECRET")
```

---

# Comportamento in produzione

Variabile mancante:

```
[PANIC] Missing environment variable: 'DATABASE_URL'
exit code 1
```

L'app si ferma subito invece di partire in stato incoerente.

---

# Confronto con os.getenv()

```python
# fragile
DATABASE_URL = os.getenv("DATABASE_URL")

if not DATABASE_URL:
    raise RuntimeError("missing")
```

vs

```python
# esplicito
DATABASE_URL = require("DATABASE_URL")
```

Meno boilerplate. Intento chiaro. Avvio più sicuro.