envguard

Validate your environment variables before your app crashes

The Problem

Your .env file has a typo. You won't know until your app crashes at 3 AM in production.

DATABSE_URL=...   # typo → app starts → crashes 2 hours later on first DB call
SECRET_KEY=       # empty → auth silently broken
DEBUG=maybe       # not a boolean → who knows what happens

The Solution

pip install envguard-check

Check everything before your app starts:

from envguard import guard

# App won't start until all vars are valid
guard(
    DATABASE_URL="url",
    REDIS_URL="url",
    SECRET_KEY="str",
    DEBUG="bool",
    PORT="int",
)

If anything is wrong, you get a clear error and the app refuses to start:

Environment validation failed:

  ✗ MISSING: DATABASE_URL is required but not set
  ✗ TYPE: PORT='abc' is not a valid integer
  ✗ TYPE: DEBUG='maybe' is not a valid boolean

  3 error(s) found. Fix your .env file and try again.

Features

Type Validation

from envguard import check_env, EnvVar

check_env([
    EnvVar(name="PORT", type="int"),           # must be integer
    EnvVar(name="RATE", type="float"),          # must be float
    EnvVar(name="DEBUG", type="bool"),          # true/false/1/0/yes/no
    EnvVar(name="API_URL", type="url"),         # must start with http(s)://
    EnvVar(name="ADMIN_EMAIL", type="email"),   # must contain @ and domain
])

Choices

check_env([
    EnvVar(name="ENV", choices=["development", "staging", "production"]),
    EnvVar(name="LOG_LEVEL", choices=["DEBUG", "INFO", "WARNING", "ERROR"]),
])

Pattern Matching

check_env([
    EnvVar(name="STRIPE_KEY", pattern=r"^sk_(live|test)_"),
    EnvVar(name="AWS_REGION", pattern=r"^[a-z]{2}-[a-z]+-\d$"),
])

Defaults

check_env([
    EnvVar(name="PORT", type="int", default="8000"),
    EnvVar(name="DEBUG", type="bool", default="false"),
])

Optional Variables

check_env([
    EnvVar(name="SENTRY_DSN", required=False),  # won't fail if missing
])

Minimum Length

check_env([
    EnvVar(name="SECRET_KEY", min_length=32),  # must be at least 32 chars
])

Quick Start with guard()

The guard() function is a one-liner shorthand:

from envguard import guard

guard(
    DATABASE_URL="url",
    REDIS_URL="url",
    SECRET_KEY="str",
    DEBUG="bool",
)

Zero Dependencies

envguard uses only Python standard library. No bloat.

License

MIT