Skip to content

shifqu/envyronment

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

21 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

envyronment

A tiny module to read environment variables and tranform them.

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


Code style: Ruff Typing: Pyright Linting: Pylint License CI Validation


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.

About

A tiny module to read environment variables and tranform them.

Resources

License

Stars

Watchers

Forks

Sponsor this project

Packages

No packages published

Languages