{"id":3479,"library":"envs","title":"Envs","description":"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.","status":"active","version":"1.4","language":"en","source_language":"en","source_url":"https://github.com/qwigo/envs","tags":["environment variables","configuration","type-conversion","settings"],"install":[{"cmd":"pip install envs","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary way to access environment variables is through the 'env' callable.","symbol":"env","correct":"from envs import env"},{"note":"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.","wrong":"from envs import env as Env (when intending to define a typed env schema)","symbol":"Env","correct":"from envs import Env"}],"quickstart":{"code":"import os\nfrom envs import env, Env\n\nos.environ['APP_DEBUG'] = 'true'\nos.environ['API_KEY'] = 'your_api_key_123'\nos.environ['THRESHOLD'] = '100'\nos.environ['FEATURE_FLAGS'] = 'featureA,featureB'\nos.environ['DB_SETTINGS'] = '{\"host\": \"localhost\", \"port\": 5432}'\n\nclass AppSettings(Env):\n    debug: bool = env('APP_DEBUG', False)\n    api_key: str = env('API_KEY')\n    threshold: int = env('THRESHOLD', 50)\n    feature_flags: list[str] = env('FEATURE_FLAGS', [])\n    db_settings: dict = env('DB_SETTINGS', {})\n\nsettings = AppSettings()\n\nprint(f\"Debug mode: {settings.debug} (type: {type(settings.debug)})\")\nprint(f\"API Key: {settings.api_key} (type: {type(settings.api_key)})\")\nprint(f\"Threshold: {settings.threshold} (type: {type(settings.threshold)})\")\nprint(f\"Feature Flags: {settings.feature_flags} (type: {type(settings.feature_flags)})\")\nprint(f\"DB Settings: {settings.db_settings} (type: {type(settings.db_settings)})\")\n\n# Direct access without a schema\ndirect_api_key = env('API_KEY', '')\nprint(f\"Direct API Key: {direct_api_key} (type: {type(direct_api_key)})\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}