envgate

A minimal Python library to validate environment variables at startup. Zero dependencies.

Why?

Instead of your app crashing at runtime because DATABASE_URL is missing, envgate validates everything at startup and tells you exactly what's wrong.

Installation

pip install envgate

Quick Start

from envgate import get_env, validate

# Get a single variable with type coercion
port = get_env("PORT", type="int", default=8000)
debug = get_env("DEBUG", type="bool", default=False)

# Explicitly mark a variable as required
api_key = get_env("API_KEY", required=True)

# Parse comma-separated lists (or use a custom separator)
hosts = get_env("ALLOWED_HOSTS", type="list")            # ["a", "b", "c"]
ports = get_env("PORTS", type="list[int]", sep=":")      # [8000, 8001]

# Or validate multiple variables at once
config = validate({
    "DATABASE_URL": {"type": "str"},
    "REDIS_URL": {"type": "str"},
    "PORT": {"type": "int", "default": 8000},
    "DEBUG": {"type": "bool", "default": False},
})

If DATABASE_URL and REDIS_URL are missing and PORT is invalid, you get all errors at once:

envgate.exceptions.ValidationError: Environment validation failed:
    - Environment variable 'DATABASE_URL' is not set.
    - Environment variable 'REDIS_URL' is not set.
    - Environment variable 'PORT' has invalid value 'abc' (expected int).

Custom validators

Type coercion checks that PORT is an integer. A validator checks that the value also makes sense — e.g. that the port is in a usable range, or that a log level is one of a fixed set:

def in_port_range(p):
    if not (1024 <= p <= 65535):
        raise ValueError("must be in [1024, 65535]")

def is_known_level(level):
    if level not in {"debug", "info", "warning", "error"}:
        raise ValueError("must be one of debug|info|warning|error")

config = validate({
    "PORT": {"type": "int", "validator": in_port_range},
    "LOG_LEVEL": {"type": "str", "default": "info", "validator": is_known_level},
})

A validator signals failure by raising any exception — its message is captured and joined into the same collective ValidationError as missing and invalid-type errors:

envgate.exceptions.ValidationError: Environment validation failed:
    - Environment variable 'PORT' has invalid value '80': must be in [1024, 65535]
    - Environment variable 'LOG_LEVEL' has invalid value 'verbose': must be one of debug|info|warning|error

Supported Types

Type	Example values
str	Any string (default)
int	"42", "-7", "0"
float	"3.14", "42", "-2.5"
bool	"true", "1", "yes", "on" / "false", "0", "no", "off"
list, list[str], list[int], list[float], list[bool]	Comma-separated values — e.g. "a,b,c" → ["a", "b", "c"]. Pass sep=":" (or any character) to override the separator.

Contributing

Contributions are welcome! Check out the CONTRIBUTING.md for guidelines.

License

MIT