A tiny module to read environment variables and tranform them.
When load_dotenv is available, this is called at import time.
- ✅ Simple, typed API
- ✅ Loads
.envif installed with extradotenv - ✅ Flexible casting via
astype=... - ✅ Propagates errors raised in the
astypecallable - ✅ Zero dependencies required,
python-dotenvoptionally installed
- Python 3.10+ (only 3.13 is tested)
-
Install the package
pip install "envyronment[dotenv]"(the
[dotenv]extra is optional — include it to enable.envfile loading) -
Import and use
import envyronment as env some_value = env.read("SOME_VALUE", 42, astype=int)
import os
import envyronment as env
os.environ.update(
{
"GREENHOUSE_NAME": "dr. greenthumb's greenhouse",
"ENABLE_PHOTOSYNTHESIS": "yes",
"GARDEN_TOOLS": "shovel,rake,watering_can",
"GARDEN_PLAN": '{"flowers": ["rose", "tulip"], "vegetables": ["carrot", "tomato"]}',
"PLANT_LOG": "/var/log/garden/plants.log",
"GREENHOUSE_DIR": "/srv/greenhouse",
"GREENHOUSE_STATE": "open",
}
)
def to_upper(value: str) -> str:
"""Convert a string to an uppercase string."""
return value.upper()
# str, required, no astype provided, so str(value) is used, value="dr. greenthumb's greenhouse"
greenhouse_name = env.read("GREENHOUSE_NAME")
# int, optional, by default 42, value=42
max_plants = env.read("MAX_PLANTS", 42, astype=int)
# bool, optional, by default False, value=True
enable_photosynthesis = env.read("ENABLE_PHOTOSYNTHESIS", default=False, astype=env.to_bool)
# list[str], required, ["shovel", "rake", "watering_can"]
garden_tools = env.read("GARDEN_TOOLS", astype=env.to_list)
# dict (due to input format), required, value={"flowers": ["rose", "tulip"], "vegetables": ["carrot", "tomato"]}
garden_plan = env.read("GARDEN_PLAN", astype=env.to_json)
# Path, optional, parent directories created, no error if it already existed, value=/var/log/garden/plants.log
# ⚠️ Default value is a string because `convert_default=True` to ensure the path is created whether default or the env value is used.
plant_log = env.read("PLANT_LOG", "/tmp/log/garden/plants.log", astype=env.to_filepath, convert_default=True)
# Path, required, parent directories created, no error if it already existed, value=/src/greenhouse
greenhouse = env.read("GREENHOUSE_DIR", astype=env.to_dirpath)
# str, optional, by default CLOSED, uses custom converter defined above, value="OPEN"
greenhouse_state = env.read("GREENHOUSE_STATE", "CLOSED", astype=to_upper)This project is licensed under the MIT License — see the LICENSE file for details.