API Reference

An environment variable parser library with type hint and conversion support.

EnvError

Bases: KeyError, ValueError

An environment variable parsing error.

This class inherits from KeyError and ValueError in an attempt to be catchable by more traditional exception handling code.

get(envvar, *, default=UNSET, default_factory=None, dtype=None, deprecated=False, deprecated_msg='', docker_secret=False, item_sep=',', item_dtype=None)

Parse an environment variable into a bool, bytes, float, int, str, list or a tuple.

Rather than using os.environ.get or os.getenv, this function provides a convenient way to parse environment variables into a specific data type with type checking and conversion support.

Valid boolean environment variable values are (case insensitive): - "1", "on", "t", "true", "y", "yes" for True - "", "0", "off", "f", "false", "n", "no" for False

The function also supports parsing lists of values, where the values are separated by a specified separator (default is ","). The list items can be converted to a specific data type using the item_dtype parameter.

Parameters:

Name	Type	Description	Default
envvar	str	The name of the environment variable to parse.	required
default	EnvType | Sentinel | None	The default value to return if the environment variable is not set. If UNSET, a ValueError will be raised if the environment variable is not set.	UNSET
default_factory	Callable[[], EnvType] | None	A callable that returns the default value if the environment variable is not set. If None, this will be ignored. This cannot be used alongside default. This should be used instead of default when the expected return type is a list.	None
dtype	type[bool | bytes | float | int | str | list | tuple] | None	The data type to convert the environment variable to. If None, the value will be returned as a string. Supported types are bool, bytes, float, int, str, list, and tuple.	None
deprecated	bool	If True, and the environment variable is set, a DeprecationWarning will be raised.	False
deprecated_msg	str	A custom message to include in the DeprecationWarning if deprecated is True.	""
docker_secret	bool | str	If True, the function will attempt to read the environment variable value from a Docker secret file. Attempted file names are /run/secrets/{envvar} and /run/secrets/{envvar.lower()}. If a string is provided, it will be used as the file name instead of the environment variable name. If False, the function will not check for Docker secrets.	False
item_dtype	type[bool | bytes | float | int | str] | None	The data type to convert the items in the list to. If None, the items will be returned as strings. Supported types are bool, bytes, float, int, and str.	None
item_sep	str	The separator used to split the list of values in the environment variable. Only used if dtype is list. The default is ",".	","

Returns:

Type	Description
bool | bytes | float | int | str | list | tuple | None	The parsed value of the environment variable, converted to the specified type. If the environment variable is not set and no default is provided, a ValueError will be raised. If the environment variable is set but cannot be converted to the specified type, a ValueError will be raised.

Raises:

Type	Description
TypeError	If the dtype is not one of (bool, bytes, float, int, str, list, tuple). If the default value is not of the specified dtype. If the item_dtype is not one of (bool, bytes, float, int, str).
EnvError	If the environment variable is not set and no default is provided. If both default and default_factory are provided. If the environment variable cannot be converted to the specified dtype.

Notes

Only "simple" data types are supported by this library as environment variables shouldn't be used to store complex data types.

Examples:

Environment variable parsing can be done by importing enve:

>>> import os
>>> import enve

Parsing an environment variable as a string:

>>> os.environ["ENV_VAR"] = "test"
>>> enve.get("ENV_VAR")
'test'
>>> enve.get("ENV_VAR", dtype=str)
'test'

Parsing an environment variable as a boolean:

>>> os.environ["ENV_VAR"] = "true"
>>> enve.get("ENV_VAR", dtype=bool)
True

Parsing an environment variable as bytes:

>>> os.environ["ENV_VAR"] = "random_bytes"
>>> enve.get("ENV_VAR", dtype=bytes)
b'random_bytes'

Parsing an environment variable as a float:

>>> os.environ["ENV_VAR"] = "3.14"
>>> enve.get("ENV_VAR", dtype=float)
3.14

Parsing an environment variable as an integer:

>>> os.environ["ENV_VAR"] = "42"
>>> enve.get("ENV_VAR", dtype=int)
42

Parsing an unset environment variable:

>>> _ = os.environ.pop("ENV_VAR", None)
>>> enve.get("ENV_VAR")
Traceback (most recent call last):
    ...
enve.parser.EnvError: Environment variable 'ENV_VAR' is not set and no default or default_factory is provided.

Parsing an unset environment variable with a default value:

>>> _ = os.environ.pop("ENV_VAR", None)
>>> enve.get("ENV_VAR", default="default_value")
'default_value'

Parsing an environment variable as a list:

>>> os.environ["ENV_VAR"] = "1,2,3"
>>> enve.get("ENV_VAR", dtype=list)
['1', '2', '3']

Parsing an environment variable as a list of integers:

>>> os.environ["ENV_VAR"] = "1,2,3"
>>> enve.get("ENV_VAR", dtype=list, item_dtype=int)
[1, 2, 3]

Parsing an environment variable as a tuple of integers:

>>> os.environ["ENV_VAR"] = "1,2,3"
>>> enve.get("ENV_VAR", dtype=tuple, item_dtype=int)
(1, 2, 3)