Collections

provide.foundation.parsers.collections

TODO: Add module docstring.

Functions

parse_comma_list

parse_comma_list(value: str) -> list[str]

Parse comma-separated list of strings.

Parameters:

Name	Type	Description	Default
value	str	Comma-separated string	required

Returns:

Type	Description
list[str]	List of trimmed non-empty strings

Source code in provide/foundation/parsers/collections.py

def parse_comma_list(value: str) -> list[str]:
    """Parse comma-separated list of strings.

    Args:
        value: Comma-separated string

    Returns:
        List of trimmed non-empty strings

    """
    if not value or not value.strip():
        return []

    return [item.strip() for item in value.split(",") if item.strip()]

parse_dict

parse_dict(
    value: str | dict[str, str],
    item_separator: str = ",",
    key_separator: str = "=",
    strip: bool = True,
) -> dict[str, str]

Parse a dictionary from a string.

Format: "key1=value1,key2=value2"

Parameters:

Name	Type	Description	Default
value	str | dict[str, str]	String or dict to parse	required
item_separator	str	Separator between items	','
key_separator	str	Separator between key and value	'='
strip	bool	Whether to strip whitespace	True

Returns:

Type	Description
dict[str, str]	Dictionary of string keys and values

Raises:

Type	Description
ValueError	If format is invalid

Source code in provide/foundation/parsers/collections.py

def parse_dict(
    value: str | dict[str, str],
    item_separator: str = ",",
    key_separator: str = "=",
    strip: bool = True,
) -> dict[str, str]:
    """Parse a dictionary from a string.

    Format: "key1=value1,key2=value2"

    Args:
        value: String or dict to parse
        item_separator: Separator between items
        key_separator: Separator between key and value
        strip: Whether to strip whitespace

    Returns:
        Dictionary of string keys and values

    Raises:
        ValueError: If format is invalid

    """
    if isinstance(value, dict):
        return value

    if not value:
        return {}

    result = {}
    items = value.split(item_separator)

    for item in items:
        if not item:
            continue

        if key_separator not in item:
            raise ValueError(f"Invalid dict format: '{item}' missing '{key_separator}'")

        key, val = item.split(key_separator, 1)

        if strip:
            key = key.strip()
            val = val.strip()

        result[key] = val

    return result

parse_list

parse_list(
    value: str | list[str],
    separator: str = ",",
    strip: bool = True,
) -> list[str]

Parse a list from a string.

Parameters:

Name	Type	Description	Default
value	str | list[str]	String or list to parse	required
separator	str	Separator character	','
strip	bool	Whether to strip whitespace from items	True

Returns:

Type	Description
list[str]	List of strings

Source code in provide/foundation/parsers/collections.py

def parse_list(
    value: str | list[str],
    separator: str = ",",
    strip: bool = True,
) -> list[str]:
    """Parse a list from a string.

    Args:
        value: String or list to parse
        separator: Separator character
        strip: Whether to strip whitespace from items

    Returns:
        List of strings

    """
    if isinstance(value, list):
        return value

    if not value:
        return []

    items = value.split(separator)

    if strip:
        items = [item.strip() for item in items]

    return items

parse_set

parse_set(
    value: str | set[str],
    separator: str = ",",
    strip: bool = True,
) -> set[str]

Parse a set from a string.

Parameters:

Name	Type	Description	Default
value	str | set[str]	String or set to parse	required
separator	str	Separator character	','
strip	bool	Whether to strip whitespace from items	True

Returns:

Type	Description
set[str]	Set of strings (duplicates removed)

Source code in provide/foundation/parsers/collections.py

def parse_set(
    value: str | set[str],
    separator: str = ",",
    strip: bool = True,
) -> set[str]:
    """Parse a set from a string.

    Args:
        value: String or set to parse
        separator: Separator character
        strip: Whether to strip whitespace from items

    Returns:
        Set of strings (duplicates removed)

    """
    if isinstance(value, set):
        return value

    # Reuse list parsing logic, then convert to set
    items = parse_list(value, separator=separator, strip=strip)
    return set(items)

parse_tuple

parse_tuple(
    value: str | tuple[str, ...],
    separator: str = ",",
    strip: bool = True,
) -> tuple[str, ...]

Parse a tuple from a string.

Parameters:

Name	Type	Description	Default
value	str | tuple[str, ...]	String or tuple to parse	required
separator	str	Separator character	','
strip	bool	Whether to strip whitespace from items	True

Returns:

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

Source code in provide/foundation/parsers/collections.py

def parse_tuple(
    value: str | tuple[str, ...],
    separator: str = ",",
    strip: bool = True,
) -> tuple[str, ...]:
    """Parse a tuple from a string.

    Args:
        value: String or tuple to parse
        separator: Separator character
        strip: Whether to strip whitespace from items

    Returns:
        Tuple of strings

    """
    if isinstance(value, tuple):
        return value

    # Reuse list parsing logic
    items = parse_list(value, separator=separator, strip=strip)
    return tuple(items)