Registry / devops / env-tools

env-tools

JSON →
library2.4.0pypypi✓ verified 86d ago

Tools for using .env files in Python. This library simplifies loading environment variables from `.env` files and accessing them with optional type casting and default values. As of version 2.4.0, it offers a stable API for managing application configurations, with minor releases for improvements and bug fixes.

pip install env-tools
INSTALL
IMPORT
SIG · ENV-TOOLS
E
env-tools
devopspythonv2.4.0
Install
1.7s avg
Import
15ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.015s · 18.1MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 1.7s · import 0.015s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

load_env
from env_tools import load_env
get_env
from env_tools import get_env
EnvNotFoundError
from env_tools import EnvNotFoundError

This quickstart demonstrates how to load environment variables from a `.env` file using `load_env()` and retrieve them with `get_env()`. It covers basic access, type casting (e.g., to bool or int), providing default values, and handling `EnvNotFoundError` for missing variables. It also highlights how OS environment variables take precedence over those in the `.env` file.

import os from env_tools import load_env, get_env, EnvNotFoundError # --- Example .env file content (assume this is in a file named .env) --- # MY_APP_DEBUG=True # DATABASE_URL=postgresql://user:pass@host:5432/db # API_KEY=abc-123-xyz # WORKERS=4 # ---------------------------------------------------------------------- # Load environment variables from the .env file in the current directory. # By default, load_env doesn't raise an error if the .env file is missing. # Set critical=True to make file loading mandatory. load_env() # Access environment variables with optional type casting and defaults debug_mode = get_env("MY_APP_DEBUG", cast_to_type=bool, default=False) db_url = get_env("DATABASE_URL") api_key = get_env("API_KEY", default="default_api_key_if_not_set") workers = get_env("WORKERS", cast_to_type=int) # No default, will raise EnvNotFoundError if missing print(f"Debug Mode: {debug_mode} (Type: {type(debug_mode)})") print(f"Database URL: {db_url}") print(f"API Key: {api_key}") print(f"Workers: {workers} (Type: {type(workers)})") # Demonstrating a missing variable without a default try: get_env("UNDEFINED_VAR_NO_DEFAULT") except EnvNotFoundError as e: print(f"\nCaught expected error for missing variable: {e}") # OS environment variables take precedence over .env file values os.environ['API_KEY'] = 'overridden_key_from_os' # No need to reload load_env, subsequent get_env calls will check os.environ first print(f"API Key (OS override): {get_env('API_KEY')}") # Clean up the OS environment variable after the example del os.environ['API_KEY']
Debug
Known issues
gotcha`get_env()` always returns a string by default. Remember to use the `cast_to_type` argument (e.g., `cast_to_type=int`, `cast_to_type=bool`) if you expect a non-string type.
fix
Use `get_env('VAR', cast_to_type=int)` or `int(get_env('VAR'))` for explicit type conversion.
affects: >=1.0.0
gotchaSince version 2.0.0, `load_env()` by default does *not* raise an `EnvNotFoundError` if the `.env` file is missing. It will simply proceed without loading variables from the file. If you require the `.env` file to be present, set `critical=True`.
fix
To make `.env` file loading mandatory, use `load_env(critical=True)`. This will raise `EnvNotFoundError` if the file is not found.
affects: >=2.0.0
gotchaEnvironment variables explicitly set in the operating system always take precedence over variables defined in the `.env` file. Be aware that `load_env()` will not override existing OS environment variables.
fix
To ensure `.env` file variables are used, unset any conflicting OS environment variables, or ensure they are not set at all.
affects: >=1.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'env_tools'
The `env-tools` package is not installed in your current Python environment.
fix
Run `pip install env-tools` in your terminal.
env_tools.exceptions.EnvNotFoundError: Environment variable 'MY_VARIABLE' not found and no default provided.
You tried to access an environment variable using `get_env('MY_VARIABLE')` that is neither defined in your `.env` file, nor in your OS environment, and no `default` value was supplied to `get_env()`.
fix
Either define 'MY_VARIABLE' in your `.env` file or OS environment, or provide a default value: `get_env('MY_VARIABLE', default='some_value')`.
ValueError: invalid literal for int() with base 10: 'not_an_int'
You used `cast_to_type=int` (or another type) with `get_env()`, but the value retrieved from the environment variable (e.g., 'not_an_int') could not be successfully converted to the specified type.
fix
Ensure the environment variable's value is compatible with the `cast_to_type` you are using (e.g., '123' for `int`, 'True'/'False' for `bool`). Implement validation or error handling if input might be malformed.
Upgrade
Version history
2.4.0latest on PyPI · released Dec 4, 2024
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources
env-tools — pip install env-tools · libregistry