Env

provide.foundation.serialization.env

TODO: Add module docstring.

Functions

env_dumps

env_dumps(
    obj: dict[str, str], *, quote_values: bool = True
) -> str

Serialize dictionary to .env file format string.

Parameters:

Name	Type	Description	Default
obj	dict[str, str]	Dictionary of environment variables	required
quote_values	bool	Whether to quote string values	True

Returns:

Type	Description
str	.env format string

Raises:

Type	Description
ValidationError	If object cannot be serialized

Example

env_dumps({"KEY": "value"}) 'KEY="value"\n' env_dumps({"KEY": "value"}, quote_values=False) 'KEY=value\n'

Source code in provide/foundation/serialization/env.py

def env_dumps(obj: dict[str, str], *, quote_values: bool = True) -> str:
    """Serialize dictionary to .env file format string.

    Args:
        obj: Dictionary of environment variables
        quote_values: Whether to quote string values

    Returns:
        .env format string

    Raises:
        ValidationError: If object cannot be serialized

    Example:
        >>> env_dumps({"KEY": "value"})
        'KEY="value"\\n'
        >>> env_dumps({"KEY": "value"}, quote_values=False)
        'KEY=value\\n'

    """
    from provide.foundation.errors import ValidationError

    if not isinstance(obj, dict):
        raise ValidationError("ENV serialization requires a dictionary")

    lines: list[str] = []

    try:
        for key, value in obj.items():
            # Ensure key is valid
            if not isinstance(key, str) or not key:
                raise ValidationError(f"Invalid environment variable name: {key}")

            value_str = str(value)

            # Quote if requested and contains spaces
            if quote_values and (" " in value_str or "\t" in value_str):
                value_str = f'"{value_str}"'

            lines.append(f"{key}={value_str}")

        return "\n".join(lines) + "\n"
    except Exception as e:
        raise ValidationError(f"Cannot serialize object to ENV format: {e}") from e

env_loads

env_loads(
    s: str, *, use_cache: bool = True
) -> dict[str, str]

Deserialize .env file format string to dictionary.

Parameters:

Name	Type	Description	Default
s	str	.env format string to deserialize	required
use_cache	bool	Whether to use caching for this operation	True

Returns:

Type	Description
dict[str, str]	Dictionary of environment variables

Raises:

Type	Description
ValidationError	If string is not valid .env format

Example

env_loads('KEY=value') {'KEY': 'value'} env_loads('KEY="value"')

Source code in provide/foundation/serialization/env.py

def env_loads(s: str, *, use_cache: bool = True) -> dict[str, str]:
    """Deserialize .env file format string to dictionary.

    Args:
        s: .env format string to deserialize
        use_cache: Whether to use caching for this operation

    Returns:
        Dictionary of environment variables

    Raises:
        ValidationError: If string is not valid .env format

    Example:
        >>> env_loads('KEY=value')
        {'KEY': 'value'}
        >>> env_loads('KEY="value"')
        {'KEY': 'value'}

    """
    from provide.foundation.errors import ValidationError

    if not isinstance(s, str):
        raise ValidationError("Input must be a string")

    # Check cache first if enabled
    if use_cache and get_cache_enabled():
        cache_key = get_cache_key(s, "env")
        cached = get_serialization_cache().get(cache_key)
        if cached is not None:
            return cached

    result: dict[str, str] = {}

    try:
        for line_num, line in enumerate(s.splitlines(), 1):
            parsed = _parse_env_line(line, line_num)
            if parsed is not None:
                key, value = parsed
                result[key] = value
    except ValidationError:
        raise
    except Exception as e:
        raise ValidationError(f"Invalid .env format string: {e}") from e

    # Cache result
    if use_cache and get_cache_enabled():
        cache_key = get_cache_key(s, "env")
        get_serialization_cache().set(cache_key, result)

    return result