Getters

provide.foundation.utils.environment.getters

TODO: Add module docstring.

Classes

Functions

get_bool

get_bool(
    name: str, default: bool | None = None
) -> bool | None

Get boolean environment variable.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
default	bool | None	Default value if not set	None

Returns:

Type	Description
bool | None	Boolean value, None (if set but empty), or default (if unset)

Note

Empty string is treated as ambiguous and returns None with a warning. Unset variable returns the default value.

Examples:

>>> os.environ['DEBUG'] = 'true'
>>> get_bool('DEBUG')
True
>>> get_bool('MISSING', False)
False

Source code in provide/foundation/utils/environment/getters.py

def get_bool(name: str, default: bool | None = None) -> bool | None:
    """Get boolean environment variable.

    Args:
        name: Environment variable name
        default: Default value if not set

    Returns:
        Boolean value, None (if set but empty), or default (if unset)

    Note:
        Empty string is treated as ambiguous and returns None with a warning.
        Unset variable returns the default value.

    Examples:
        >>> os.environ['DEBUG'] = 'true'
        >>> get_bool('DEBUG')
        True
        >>> get_bool('MISSING', False)
        False

    """
    from provide.foundation.logger import get_logger

    value = os.environ.get(name)
    if value is None:
        return default

    # Handle empty/whitespace-only strings as ambiguous
    if not value.strip():
        logger = get_logger(__name__)
        logger.warning(
            f"Environment variable {name} is set but empty - treating as None. "
            f"Either provide a value or unset the variable to use default."
        )
        return None

    try:
        return parse_bool(value)
    except ValueError as e:
        raise ValidationError(
            f"Invalid boolean value for {name}: {value}",
            field=name,
            value=value,
            rule="boolean",
        ) from e

get_dict

get_dict(
    name: str,
    default: dict[str, str] | None = None,
    item_separator: str = ",",
    key_value_separator: str = "=",
) -> dict[str, str]

Get dictionary from environment variable.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
default	dict[str, str] | None	Default dict if not set	None
item_separator	str	Separator between items	','
key_value_separator	str	Separator between key and value	'='

Returns:

Type	Description
dict[str, str]	Dictionary of string key-value pairs

Examples:

>>> os.environ['CONFIG'] = 'key1=val1,key2=val2'
>>> get_dict('CONFIG')
{'key1': 'val1', 'key2': 'val2'}

Source code in provide/foundation/utils/environment/getters.py

def get_dict(
    name: str,
    default: dict[str, str] | None = None,
    item_separator: str = ",",
    key_value_separator: str = "=",
) -> dict[str, str]:
    """Get dictionary from environment variable.

    Args:
        name: Environment variable name
        default: Default dict if not set
        item_separator: Separator between items
        key_value_separator: Separator between key and value

    Returns:
        Dictionary of string key-value pairs

    Examples:
        >>> os.environ['CONFIG'] = 'key1=val1,key2=val2'
        >>> get_dict('CONFIG')
        {'key1': 'val1', 'key2': 'val2'}

    """
    value = os.environ.get(name)
    if value is None:
        return default or {}

    try:
        return parse_dict(
            value,
            item_separator=item_separator,
            key_separator=key_value_separator,
            strip=True,
        )
    except ValueError as e:
        # parse_dict raises on invalid format, log warning and return partial result
        _get_logger().warning(
            "Invalid dictionary format in environment variable",
            var=name,
            value=value,
            error=str(e),
        )
        # Try to parse what we can, skipping invalid items
        result = {}
        items = value.split(item_separator)
        for item in items:
            item = item.strip()
            if not item:
                continue
            if key_value_separator not in item:
                continue
            key, val = item.split(key_value_separator, 1)
            result[key.strip()] = val.strip()
        return result

get_float

get_float(
    name: str, default: float | None = None
) -> float | None

Get float environment variable.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
default	float | None	Default value if not set	None

Returns:

Type	Description
float | None	Float value or default

Raises:

Type	Description
ValidationError	If value cannot be parsed as float

Source code in provide/foundation/utils/environment/getters.py

def get_float(name: str, default: float | None = None) -> float | None:
    """Get float environment variable.

    Args:
        name: Environment variable name
        default: Default value if not set

    Returns:
        Float value or default

    Raises:
        ValidationError: If value cannot be parsed as float

    """
    value = os.environ.get(name)
    if value is None:
        return default

    try:
        return float(value)
    except ValueError as e:
        raise ValidationError(
            f"Invalid float value for {name}: {value}",
            field=name,
            value=value,
            rule="float",
        ) from e

get_int

get_int(
    name: str, default: int | None = None
) -> int | None

Get integer environment variable.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
default	int | None	Default value if not set	None

Returns:

Type	Description
int | None	Integer value or default

Raises:

Type	Description
ValidationError	If value cannot be parsed as integer

Source code in provide/foundation/utils/environment/getters.py

def get_int(name: str, default: int | None = None) -> int | None:
    """Get integer environment variable.

    Args:
        name: Environment variable name
        default: Default value if not set

    Returns:
        Integer value or default

    Raises:
        ValidationError: If value cannot be parsed as integer

    """
    value = os.environ.get(name)
    if value is None:
        return default

    try:
        return int(value)
    except ValueError as e:
        raise ValidationError(
            f"Invalid integer value for {name}: {value}",
            field=name,
            value=value,
            rule="integer",
        ) from e

get_list

get_list(
    name: str,
    default: list[str] | None = None,
    separator: str = ",",
) -> list[str]

Get list from environment variable.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
default	list[str] | None	Default list if not set	None
separator	str	String separator (default: comma)	','

Returns:

Type	Description
list[str]	List of strings

Examples:

>>> os.environ['ITEMS'] = 'a,b,c'
>>> get_list('ITEMS')
['a', 'b', 'c']

Source code in provide/foundation/utils/environment/getters.py

def get_list(name: str, default: list[str] | None = None, separator: str = ",") -> list[str]:
    """Get list from environment variable.

    Args:
        name: Environment variable name
        default: Default list if not set
        separator: String separator (default: comma)

    Returns:
        List of strings

    Examples:
        >>> os.environ['ITEMS'] = 'a,b,c'
        >>> get_list('ITEMS')
        ['a', 'b', 'c']

    """
    value = os.environ.get(name)
    if value is None:
        return default or []

    # Use existing parse_list which handles empty strings and stripping
    items = parse_list(value, separator=separator, strip=True)
    # Filter empty strings (parse_list doesn't do this by default)
    return [item for item in items if item]

get_path

get_path(
    name: str, default: Path | str | None = None
) -> Path | None

Get path environment variable.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
default	Path | str | None	Default path if not set	None

Returns:

Type	Description
Path | None	Path object or None

Source code in provide/foundation/utils/environment/getters.py

def get_path(name: str, default: Path | str | None = None) -> Path | None:
    """Get path environment variable.

    Args:
        name: Environment variable name
        default: Default path if not set

    Returns:
        Path object or None

    """
    value = os.environ.get(name)
    if value is None:
        if default is None:
            return None
        return Path(default) if not isinstance(default, Path) else default

    # Expand user and environment variables
    expanded = os.path.expandvars(value)
    return Path(expanded).expanduser()

get_set

get_set(
    name: str,
    default: set[str] | None = None,
    separator: str = ",",
) -> set[str]

Get set from environment variable (duplicates removed).

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
default	set[str] | None	Default set if not set	None
separator	str	String separator (default: comma)	','

Returns:

Type	Description
set[str]	Set of strings

Examples:

>>> os.environ['TAGS'] = 'dev,test,dev,prod'
>>> get_set('TAGS')
{'dev', 'test', 'prod'}

Source code in provide/foundation/utils/environment/getters.py

def get_set(name: str, default: set[str] | None = None, separator: str = ",") -> set[str]:
    """Get set from environment variable (duplicates removed).

    Args:
        name: Environment variable name
        default: Default set if not set
        separator: String separator (default: comma)

    Returns:
        Set of strings

    Examples:
        >>> os.environ['TAGS'] = 'dev,test,dev,prod'
        >>> get_set('TAGS')
        {'dev', 'test', 'prod'}

    """
    value = os.environ.get(name)
    if value is None:
        return default or set()

    items = parse_set(value, separator=separator, strip=True)
    return {item for item in items if item}

get_str

get_str(
    name: str, default: str | None = None
) -> str | None

Get string environment variable.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
default	str | None	Default value if not set	None

Returns:

Type	Description
str | None	String value or default

Source code in provide/foundation/utils/environment/getters.py

def get_str(name: str, default: str | None = None) -> str | None:
    """Get string environment variable.

    Args:
        name: Environment variable name
        default: Default value if not set

    Returns:
        String value or default

    """
    return os.environ.get(name, default)

get_tuple

get_tuple(
    name: str,
    default: tuple[str, ...] | None = None,
    separator: str = ",",
) -> tuple[str, ...]

Get tuple from environment variable.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
default	tuple[str, ...] | None	Default tuple if not set	None
separator	str	String separator (default: comma)	','

Returns:

Type	Description
tuple[str, ...]	Tuple of strings

Examples:

>>> os.environ['COORDINATES'] = '1.0,2.0,3.0'
>>> get_tuple('COORDINATES')
('1.0', '2.0', '3.0')

Source code in provide/foundation/utils/environment/getters.py

def get_tuple(name: str, default: tuple[str, ...] | None = None, separator: str = ",") -> tuple[str, ...]:
    """Get tuple from environment variable.

    Args:
        name: Environment variable name
        default: Default tuple if not set
        separator: String separator (default: comma)

    Returns:
        Tuple of strings

    Examples:
        >>> os.environ['COORDINATES'] = '1.0,2.0,3.0'
        >>> get_tuple('COORDINATES')
        ('1.0', '2.0', '3.0')

    """
    value = os.environ.get(name)
    if value is None:
        return default or ()

    items = parse_tuple(value, separator=separator, strip=True)
    return tuple(item for item in items if item)

require

require(name: str, type_hint: type[T] | None = None) -> Any

Require an environment variable to be set.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name	required
type_hint	type[T] | None	Optional type hint for parsing	None

Returns:

Type	Description
Any	Parsed value

Raises:

Type	Description
ValidationError	If variable is not set

Source code in provide/foundation/utils/environment/getters.py

def require(name: str, type_hint: type[T] | None = None) -> Any:
    """Require an environment variable to be set.

    Args:
        name: Environment variable name
        type_hint: Optional type hint for parsing

    Returns:
        Parsed value

    Raises:
        ValidationError: If variable is not set

    """
    if name not in os.environ:
        raise ValidationError(
            f"Required environment variable not set: {name}",
            field=name,
            rule="required",
        )

    if type_hint is None:
        return os.environ[name]

    # Parse based on type hint
    origin = get_origin(type_hint)
    if origin is None:
        return _parse_simple_type(name, type_hint)
    else:
        return _parse_complex_type(name, origin)