split() - Splits the input string based on a specified separator while allowing exclusions and optional trimming.

split.py

from typing import Optional


def split(
    input_string: str,
    sep: Optional[str] = None,
    max_split: int = -1,
    exclusions: Optional[list[str]] = None,
    strip_items: bool = False
) -> list[str]:
    """
    Splits the input string based on a specified separator while allowing exclusions and optional trimming.

    Parameters:
    input (str): The string to be split.
    sep (Optional[str]): The delimiter to use for splitting. Defaults to `None` (whitespace splitting).
    max_split (int): The maximum number of splits to perform. Defaults to `-1` (no limit).
    exclusions (Optional[list[str]]): A list of strings to exclude from the final result. Defaults to `None`.
    strip_items (bool): Whether to strip whitespace from each split segment. Defaults to `False`.

    Returns:
    list[str]: A list of split substrings with exclusions applied.
    """
    if exclusions is None:
        exclusions = [""]

    return [
        fixed_item
        for item in input_string.split(sep=sep, maxsplit=max_split)
        if (fixed_item := item.strip() if strip_items else item) not in exclusions
    ]

~examples.py

from split import split

# Basic usage with default whitespace splitting
print(split("apple banana cherry"))
# Output: ['apple', 'banana', 'cherry']

# Using a custom separator
print(split("apple,banana,cherry", sep=","))
# Output: ['apple', 'banana', 'cherry']

# Limiting the number of splits
print(split("apple banana cherry date", sep=" ", max_split=2))
# Output: ['apple', 'banana', 'cherry date']

# Excluding specific words
print(split("apple banana cherry", sep=" ", exclusions=["banana"]))
# Output: ['apple', 'cherry']

# Trimming whitespace from each split item
print(split(" apple , banana , cherry ", sep=",", strip_items=True))
# Output: ['apple', 'banana', 'cherry']

# Combining exclusions and trimming
print(split(" apple , banana , cherry , date ", sep=",", exclusions=["banana", "date"], strip_items=True))
# Output: ['apple', 'cherry']