specenv

Zero-dependency typed environment variable loader for Python

The Problem

Reading environment variables in plain Python is verbose, fragile, and produces cryptic errors at runtime:

import os

PORT    = int(os.environ.get("PORT", "8080"))
DEBUG   = os.environ.get("DEBUG", "false").lower() in ("1", "true", "yes")
TIMEOUT = float(os.environ.get("TIMEOUT", "30.0"))
HOSTS   = [h.strip() for h in os.environ.get("ALLOWED_HOSTS", "").split(",") if h.strip()]

# If PORT is "abc" you get:
# ValueError: invalid literal for int() with base 10: 'abc'
# — no variable name, no hint on how to fix it.

The Solution

import specenv

PORT    = specenv.get("PORT",           default=8080,  cast=int)
DEBUG   = specenv.get("DEBUG",          default=False, cast=bool)
TIMEOUT = specenv.get("TIMEOUT",        default=30.0,  cast=float)
HOSTS   = specenv.get("ALLOWED_HOSTS",  default=[],    cast=list)

# If PORT is "abc" you get:
# EnvCastError: Cannot cast PORT="abc" to int.
#     → Set PORT to a valid integer (e.g. PORT=8080)

Install

pip install specenv

Python 3.10+ required. No runtime dependencies.

Usage

Simple get

import specenv

PORT    = specenv.get("PORT",    default=8080,  cast=int)
DEBUG   = specenv.get("DEBUG",   default=False, cast=bool)
TIMEOUT = specenv.get("TIMEOUT", default=30.0,  cast=float)
HOSTS   = specenv.get("ALLOWED_HOSTS", default=[], cast=list)        # list[str]
PORTS   = specenv.get("PORTS",   default=[8080],  cast=list[int])    # list[int]

When default is omitted and the variable is not set, EnvCastError is raised immediately.

Bool casting

Matching is case-insensitive (TRUE, Yes, ON all work).

Schema-based loading

Group all variables into a single class for easier testing and injection:

from specenv import Schema, Var

class AppConfig(Schema):
    PORT        = Var(int,      default=8080)
    DEBUG       = Var(bool,     default=False)
    DB_URL      = Var(str,      required=True)
    TIMEOUT     = Var(float,    default=30.0)
    ALLOWED_IPS = Var(list[str], default=[])

config = AppConfig.load()
print(config.PORT)   # 8080 (or whatever PORT is set to)

Pass a plain dict to load() in tests to avoid touching the real environment:

cfg = AppConfig.load(env={"DB_URL": "sqlite:///test.db"})

Validation

PORT = specenv.get(
    "PORT",
    cast=int,
    validate=lambda v: 1 <= v <= 65535,
)

Or inside a Schema:

class Config(Schema):
    PORT = Var(int, default=8080, validate=lambda v: 1 <= v <= 65535)

Namespace / prefix

db    = specenv.namespace("DB_")
HOST  = db.get("HOST", default="localhost")      # reads DB_HOST
PORT  = db.get("PORT", default=5432, cast=int)   # reads DB_PORT

cache = specenv.namespace("CACHE_")
URL   = cache.get("URL", default="redis://localhost:6379")  # reads CACHE_URL

Error Messages

Every error is designed to tell you what went wrong and how to fix it.

EnvCastError: Cannot cast PORT="abc" to int.
    → Set PORT to a valid integer (e.g. PORT=8080)

EnvCastError: Required variable DB_URL is not set.
    → Add DB_URL to your environment or .env file.

EnvValidationError: PORT=99999 failed validation (must satisfy the provided lambda).

API Reference

Supported cast types: int, float, bool, str, list, list[int], list[float], list[str], pathlib.Path, and any list[T] where T is one of the above.

Contributing

Bug reports and pull requests are welcome on the GitHub issues page. Please open an issue before starting large changes so we can discuss the approach first.

License

MIT — see LICENSE.