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>.

An empty value like DB_URL= usually means someone forgot to fill it in, so it counts as missing: you get the default, or the error DB_URL: is empty. This is how the shell's ${DB_URL:-default} treats it too. When empty really is a valid value, such as a local database with no password, say so: env.str("DB_PASSWORD", allow_empty=True) returns "".

Switching from os.environ

tidyenv is stricter than hand-written parsing, on purpose. When you switch, check the values your environments actually set:

• Bad values stop the app. A typo in a number, a boolean or a choice is an error at startup instead of a silent fallback. env.choice ignores case, so PROD is fine.
• Booleans accept every common spelling. true, True, yes, on and 1 are all True. Code that only checked == "TRUE" treated the others as False.
• Empty means missing. X= gives the default (or an is empty error), not "", unless you pass allow_empty=True. If your old code used os.getenv("X", "") and relied on getting "", use allow_empty=True for that variable.

.env files

Coming from python-dotenv? Change the import, nothing else:

from tidyenv import load_dotenv  # was: from dotenv import load_dotenv

load_dotenv()

load_dotenv, dotenv_values and find_dotenv take the same arguments and give the same results as python-dotenv 1.2's:

• the same file syntax: export, comments, quotes, values spanning several lines, ${VAR} and ${VAR:-default};
• .env is looked up starting next to the calling file, then in its parents;
• values go into os.environ, and variables that are already set are kept unless override=True, so the first file you load wins;
• PYTHON_DOTENV_DISABLED=1 turns loading off.

The test suite checks this against python-dotenv itself on thousands of generated files. Not included: set_key, unset_key, get_key and the dotenv command.

Then read the values with types. env reads os.environ, so it sees them:

from tidyenv import env, load_dotenv

load_dotenv()
PORT = env.int("PORT", default=8000)

Without touching os.environ. env.read_dotenv() follows the same rules but keeps the values inside env, and a line it can't parse is an error naming the file and line (python-dotenv only logs a warning):

env.read_dotenv()  # ./.env in the current directory, if it exists
env.read_dotenv("config/dev.env", required=True)

Need just the parser? tidyenv.parse_dotenv(text) returns a dict (without ${VAR} expansion).

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. The .env support is adapted from python-dotenv (BSD-3-Clause, see LICENSES/python-dotenv.txt); thanks to its authors. tidyenv is not affiliated with or endorsed by the python-dotenv project.