env-proxy

env-proxy reads environment variables with type hints, type conversion, and a declarative configuration layer. Define your env-driven config once as a typed class, then access fields like any other attribute — with eager validation, optional freezing for performance, and sample .env generation included.

Install

# Using pip
pip install env-proxy

# Using Poetry
poetry add env-proxy

Supports Python 3.10+.

Quickstart

import os
from env_proxy import EnvConfig, Field

os.environ["MYAPP_DEBUG"] = "true"
os.environ["MYAPP_DATABASE_URL"] = "sqlite:///data.db"
os.environ["MYAPP_CACHE_BACKENDS"] = "redis,memcached"

class MyConfig(EnvConfig):
    env_prefix: str = "MYAPP"
    debug: bool = Field(description="Enable debug mode", default=False)
    database_url: str = Field(description="Database connection URL")
    cache_backends: list[str] = Field(description="Cache backends", type_hint="list")

config = MyConfig()
config.validate()   # fail fast on missing/bad env values
config.freeze()     # optional: turn reads into a dict lookup

print(config.debug)              # True
print(config.database_url)       # "sqlite:///data.db"
print(config.cache_backends)     # ["redis", "memcached"]

For one-off lookups without a full config class, the lower-level EnvProxy exposes typed getters (get_str, get_int, get_bool, get_list, get_json, …):

from env_proxy import EnvProxy

proxy = EnvProxy(prefix="MYAPP")
proxy.get_int("port", default=8080)

Documentation

Full documentation — tutorial, how-to guides, reference, and the auto-generated API — lives at https://tomasvotava.github.io/env-proxy/.

Quick links:

• Getting started
• How-to guides — recipes for the common tasks
• Reference — Field options, type hints, exceptions
• API reference — auto-generated from docstrings

Contributing

make ci runs every check that CI runs (ruff format --check, ruff check, mypy, pytest). make docs-serve previews the docs at http://127.0.0.1:8000.

Commit messages follow Conventional Commits; the pre-commit commit-msg hook enforces this locally.

Releasing

Releases are driven by commitizen. From master:

poetry run cz bump      # bumps pyproject.toml, appends to CHANGELOG.md, commits, tags
git push --follow-tags  # pushes the bump commit and the new tag together

Pushing the tag triggers .github/workflows/release.yml, which builds the distribution, creates a GitHub Release whose body is the matching CHANGELOG.md section, and publishes to PyPI.

License

env-proxy is open-source under the MIT License. See LICENSE.md.