tidyenv

Typed environment variables with friendly errors. Built-in .env support. Zero dependencies.

from tidyenv import env

PORT = env.int("PORT", default=8000)
DEBUG = env.bool("DEBUG", default=False)
HOSTS = env.list("ALLOWED_HOSTS", default=["localhost"])
DATABASE_URL = env.str("DATABASE_URL")

Each line converts the type, applies the default, and if something is wrong, says exactly what:

tidyenv.EnvError: 1 environment problem:
  - PORT: expected an integer (got 'eighty')

Why

One line per variable, and every error names the variable and says what is wrong with it.

Install

pip install tidyenv

Python 3.9+.

Usage

Every reader takes an optional default. Without one, a missing or empty variable is an error. With one, the default is returned instead, and type checkers know the result is int | <type of default>.

.env files

No need for python-dotenv:

env.read_dotenv()  # reads ./.env if it exists
env.read_dotenv("config/dev.env", required=True)

Real environment variables always win over the file, and nothing is written to os.environ. When you read several files, later ones override earlier ones. Supported syntax: KEY=value, export KEY=value, # comments, 'single quotes' (literal) and "double quotes" (with \n, \t, \" escapes). Each value must fit on one line; for a multi-line value such as a PEM key, write \n inside double quotes. Need just the parser? tidyenv.parse_dotenv(text) returns a dict.

All errors at once (optional)

By default the first bad variable raises EnvError. If you'd rather see every problem in one go, wrap your reads in env.collect():

with env.collect():
    PORT = env.int("PORT", default=8000)
    DATABASE_URL = env.str("DATABASE_URL")
    API_KEY = env.str("API_KEY", secret=True)

tidyenv.EnvError: 3 environment problems:
  - PORT: expected an integer (got 'eighty')
  - DATABASE_URL: is not set
  - API_KEY: is not set

Failed reads return None inside the block, so only use the values after it exits.

More

Secrets. Pass secret=True and the raw value is shown as *** in error messages, including errors about single env.list items.

Prefixes and custom sources. Build your own reader:

from tidyenv import Env

env = Env(prefix="MYAPP_")  # reads MYAPP_PORT for env.int("PORT")
test_env = Env(environ={"PORT": "1"})  # any mapping, handy in tests

Handling errors. EnvError.problems is a list of Problem(name, message), so you can print them your own way.

License

MIT