cornsnake.util_list

  1"""
  2Functions for manipulating lists of data. Functions include chunking lists, excluding elements from one list that are present in another, finding the intersection of two lists, and various other list operations.
  3
  4[Documentation](http://docs.mrseanryan.cornsnake.s3-website-eu-west-1.amazonaws.com/cornsnake/util_list.html)
  5"""
  6
  7from typing import Generator, TypeVar
  8
  9T = TypeVar("T")
 10
 11
 12def chunk(
 13    list_a: list, CHUNK_SIZE: int, min_chunk_size: int = 1
 14) -> Generator[list, None, None]:
 15    """
 16    Function to chunk a list into sublists of size n.
 17
 18    Args:
 19    list_a (list): The input list to be chunked.
 20    n (int): The size of each chunk.
 21    min_chunk_size: The minimum size for a chunk. Set to avoid a smaller chunk at the end, instead add its contents to the penultimate chunk.
 22
 23    Yields:
 24    list: Sublists of size n.
 25    """
 26
 27    if min_chunk_size > CHUNK_SIZE:
 28        raise ValueError(
 29            f"min_chunk_size {min_chunk_size} is greater than CHUNK_SIZE {CHUNK_SIZE}"
 30        )
 31
 32    for i in range(0, len(list_a), CHUNK_SIZE):
 33        list_end = i + CHUNK_SIZE
 34        if len(list_a) - list_end < min_chunk_size:
 35            list_end = len(list_a)
 36            yield list_a[i:list_end]
 37            break
 38
 39        yield list_a[i:list_end]
 40
 41
 42def excluding(list1: list, list2: list) -> list:
 43    """
 44    Function to exclude elements from list1 that are present in list2.
 45
 46    Args:
 47    list1 (list): The main list.
 48    list2 (list): The list of elements to exclude.
 49
 50    Returns:
 51    list: List1 with elements excluded.
 52    """
 53    return [x for x in list1 if x not in list2]
 54
 55
 56def intersecting(list1: list, list2: list) -> list:
 57    """
 58    Function to find the intersection of two lists.
 59
 60    Args:
 61    list1 (list): The first list.
 62    list2 (list): The second list.
 63
 64    Returns:
 65    list: Intersection of list1 and list2.
 66    """
 67    return [value for value in list1 if value in list2]
 68
 69
 70def first_or_none(my_list: list[T]) -> T | None:
 71    """Function to return the first element of a list or None if the list is empty."""
 72    if len(my_list) > 0:
 73        return my_list[0]
 74    return None
 75
 76
 77def flatten(my_list: list[list[T]]) -> list[T]:
 78    """Function to flatten a list of lists into a single list."""
 79    return [item for sublist in my_list for item in sublist]
 80
 81
 82def list_with_first_or_empty(my_list: list[T]) -> list[T]:
 83    """Function to return a list containing the first element of the input list, or an empty list if the input list is empty."""
 84    first_or_none_value = first_or_none(my_list)
 85    if first_or_none_value is None:
 86        return []
 87    return [first_or_none_value]
 88
 89
 90def not_none(my_list: list[T]) -> list[T]:
 91    """Function to return a list with non-None elements."""
 92    result: list[T] = []
 93    for item in my_list:
 94        if item is not None:
 95            result.append(item)
 96    return result
 97
 98
 99def not_none_and_unique(my_list: list[T]) -> list[T]:
100    """Function to return a list with unique non-None elements, preserving the order."""
101    seen: list[T] = []
102    result: list[T] = []
103    for item in my_list:
104        if item is not None and item not in seen:
105            seen.append(item)
106            result.append(item)
107    return result
108
109
110def remove_empty_strings(list_of_strings: list[str]) -> list[str]:
111    """Function to remove empty strings from a list of strings."""
112    parts_filtered = []
113    for part in list_of_strings:
114        if part and len(part) > 0:
115            parts_filtered.append(part)
116    return parts_filtered
117
118
119def strip_strings(list_of_strings: list[str]) -> list[str]:
120    """Function to strip leading and trailing whitespace from strings in a list."""
121    parts_stripped = []
122    for part in list_of_strings:
123        parts_stripped.append(part.strip())
124    return parts_stripped
125
126
127def unique(my_list: list[T]) -> list[T]:
128    """Return a list with unique elements from the input list, preserving order."""
129    seen: list[T] = []
130    result: list[T] = []
131    for item in my_list:
132        if item not in seen:
133            seen.append(item)
134            result.append(item)
135    return result