envs

library1.4pypypi✓ verified 24d ago

Envs is a Python library (v1.4) designed for easy and typed access to environment variables. It automatically handles the parsing of environment variable values into various Python types, including strings, booleans, lists, tuples, integers, floats, and dictionaries. The library was last released in December 2021, suggesting a low-to-moderate release cadence, with updates as needed.

auth-security

pip install envs

package ↗

INSTALL

IMPORT

SIG · ENVS

envs

auth-securitypythonv1.4

Install

1.5s avg

Import

11ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.012s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.010s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

env

✓ from envs import env

The primary way to access environment variables is through the 'env' callable.

Env

✓ from envs import Env

✗ from envs import env as Env (when intending to define a typed env schema)

While `env` is the direct callable for variables, `Env` (uppercase) is used to define a structured schema for environment variables, often within a class. Using `env` directly when a structured schema is intended is a common mistake.

This quickstart demonstrates both direct access to environment variables using `env()` and defining a structured settings class with type hints by inheriting from `envs.Env`. It showcases how `envs` automatically casts values to the specified Python types and provides default values for missing variables.

import os from envs import env, Env os.environ['APP_DEBUG'] = 'true' os.environ['API_KEY'] = 'your_api_key_123' os.environ['THRESHOLD'] = '100' os.environ['FEATURE_FLAGS'] = 'featureA,featureB' os.environ['DB_SETTINGS'] = '{"host": "localhost", "port": 5432}' class AppSettings(Env): debug: bool = env('APP_DEBUG', False) api_key: str = env('API_KEY') threshold: int = env('THRESHOLD', 50) feature_flags: list[str] = env('FEATURE_FLAGS', []) db_settings: dict = env('DB_SETTINGS', {}) settings = AppSettings() print(f"Debug mode: {settings.debug} (type: {type(settings.debug)})") print(f"API Key: {settings.api_key} (type: {type(settings.api_key)})") print(f"Threshold: {settings.threshold} (type: {type(settings.threshold)})") print(f"Feature Flags: {settings.feature_flags} (type: {type(settings.feature_flags)})") print(f"DB Settings: {settings.db_settings} (type: {type(settings.db_settings)})") # Direct access without a schema direct_api_key = env('API_KEY', '') print(f"Direct API Key: {direct_api_key} (type: {type(direct_api_key)})")

Debug

Known issues

gotchaWhen defining default values for complex types (lists, dicts), ensure the default is a new instance each time to avoid mutable default argument issues. For example, `some_list: list = env('VAR', [])` is fine for `envs` as `env` will create a new default if not found. However, if manually implementing similar logic, one might fall into this Python common pitfall.

fix

Always pass the default value directly to the `env()` callable. The library handles the instantiation correctly. If building custom wrappers, use `default_factory` or `None` with a check.

affects: All

gotchaThe library parses string representations of booleans, lists, tuples, and dicts. Incorrect string formatting for these types in environment variables will lead to parsing errors or unexpected values. For instance, a non-JSON string for a dict type will fail.

fix

Ensure environment variable values for non-string types adhere to standard Python literal representations (e.g., 'true' or 'false' for booleans, '[item1, item2]' for lists, '{"key":"value"}' for dicts). For lists and tuples, comma-separated values are expected, and for dicts, a valid JSON string is required.

affects: All

deprecatedOlder versions of the library (prior to 1.x) might have different API signatures or less robust type conversion. While the current PyPI version is 1.4, if using a very old, unlisted version, expect potential incompatibilities.

fix

Upgrade to the latest stable version of the `envs` library (`pip install --upgrade envs`) to benefit from improved type handling and the current API.

affects: <1.0

gotchaThe `env` callable raises `KeyError` by default if a required environment variable is not found and no default value is provided. This is intentional for explicitness but can be a surprise if not expected.

fix

Always provide a default value (e.g., `env('VAR', 'default_value')`) or explicitly catch `KeyError` if the absence of a variable is an expected scenario. For required variables without a sensible default, letting `KeyError` propagate is often the correct behavior.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'envs'

The 'envs' library is not installed in your Python environment or the Python interpreter cannot find it.

fix

Install the library using pip: `pip install envs`

KeyError: 'YOUR_ENV_VAR_NAME'

You are trying to access an environment variable using `envs` (which might internally use `os.environ`) that is not set in your environment and no default value was provided.

fix

Set the environment variable 'YOUR_ENV_VAR_NAME' in your operating system's environment, or provide a default value when accessing it, e.g., `env('YOUR_ENV_VAR_NAME', default='some_default')`.

ValueError: invalid literal for int() with base 10: 'not_an_integer_string'

The `envs` library attempted to parse an environment variable's string value into an integer (or another type), but the string format was incompatible with the target type.

fix

Ensure the environment variable's value matches the expected type. For example, if expecting an integer, the variable should contain a string that can be safely converted to an integer: `MY_INT_VAR=123` instead of `MY_INT_VAR=abc`.

Upgrade

Version history

1.4latest on PyPI · released Dec 9, 2021

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packagehttps://pypi.org/project/envs/ ↗