Envs

Warnings

• gotcha When 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.
• gotcha The 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.
• deprecated Older 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.
• gotcha The `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.

Install

• pip install envs Install latest version

Imports

• env

  from envs import env

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

  from envs import Env

  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.

Quickstart

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)})")