paraboloski-dotenv 1.0.0

Minimal environment variable helpers with explicit failure semantics.

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

uv add paraboloski-dotenv
pip install paraboloski-dotenv

GitHub:

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

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()

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

if not DATABASE_URL:
    raise RuntimeError("missing")

vs

# 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

uv add paraboloski-dotenv
pip install paraboloski-dotenv

GitHub:

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

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()

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

if not DATABASE_URL:
    raise RuntimeError("missing")

vs

# esplicito
DATABASE_URL = require("DATABASE_URL")

Meno boilerplate. Intento chiaro. Avvio più sicuro.