envyronment

A tiny module to read environment variables and tranform them.

When load_dotenv is available, this is called at import time.

Features

• ✅ Simple, typed API
• ✅ Loads .env if installed with extra dotenv
• ✅ Flexible casting via astype=...
• ✅ Propagates errors raised in the astype callable
• ✅ Zero dependencies required, python-dotenv optionally installed

Requirements

• Python 3.10+ (only 3.13 is tested)

Quick start

1. Install the package

   pip install "envyronment[dotenv]"
   

   (the [dotenv] extra is optional — include it to enable .env file loading)

2. Import and use

   import envyronment as env
   
   some_value = env.read("SOME_VALUE", 42, astype=int)
   

Example usage

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)

License

This project is licensed under the MIT License — see the LICENSE file for details.