classes.c32_pool

  1import random
  2import colorama
  3import regex
  4from inspect import cleandoc
  5from loguru import logger
  6from icecream import ic
  7
  8from lib import helpers, content
  9
 10DEBUG = False
 11
 12
 13class KPool:
 14    """
 15    A pool of items with optional shuffling and case transformation utilities.
 16    """
 17
 18    def __init__(
 19        self, items: list[str], shuffle=True, defaultCase: content.TextCase = None
 20    ) -> None:
 21        """
 22        Initialize the KPool instance.
 23
 24        Args:
 25            items: List of items to pool.
 26            shuffle: Randomize items on initialization. Defaults to True.
 27            defaultCase: Default `content.TextCase` for items. If None, no case change is applied.
 28        """
 29        if shuffle:
 30            random.shuffle(items)
 31
 32        self._shuffle: bool = shuffle
 33
 34        self._items = items
 35        """Internal copy of items without case change"""
 36
 37        self.items = content.changeCase(items, defaultCase)
 38        """Items with case possibly changed (upon initialization)"""
 39
 40    def __str__(self) -> str:
 41        """Returns a human-readable string representation of the KPool."""
 42        return cleandoc(
 43            f"""
 44            {colorama.Fore.BLACK}{colorama.Back.LIGHTCYAN_EX}KPool{colorama.Style.RESET_ALL} {helpers.truncateList(self.items)}
 45            """
 46        )
 47
 48    def __len__(self) -> int:
 49        """Returns the number of items in the pool."""
 50        return len(self.items)
 51
 52    def __getitem__(self, index):
 53        """
 54        Make subscriptable. Allows access to items using square brackets.
 55
 56        Args:
 57            index: Index of the item.
 58
 59        Returns:
 60            Item at the given index.
 61        """
 62        return self.items[index]
 63
 64    def getItemByWidth(
 65        self,
 66        width: int,
 67        alterCase: content.TextCase = None,
 68        avoidShape: content.WordShape = None,
 69    ) -> str:
 70        """
 71        Get an item matching the specified width, with optional case and shape filtering.
 72
 73        Args:
 74            width: Target width for the item.
 75            alterCase: Change text case for a single phrase.
 76            avoidShape: Exclude items with this shape.
 77
 78        Returns:
 79            Item matching the criteria, or `Blank` if none found.
 80        """
 81        if isinstance(alterCase, str):
 82            items = content.changeCase(self.items, alterCase)
 83        else:
 84            items = self.items
 85
 86        if avoidShape:
 87            items = content.filterByShape(items, avoidShape)
 88
 89        if not items:
 90            return "Blank"
 91
 92        if self._shuffle:
 93            random.shuffle(items)  # Shuffle on each run
 94
 95        match = content.getStringForWidth(items, width)
 96
 97        self._removeItem(match)
 98        return match
 99
100    def setCase(self, case: content.TextCase):
101        """
102        Change the text case of all items at the instance level.
103
104        Args:
105            case: Desired text case.
106
107        Returns:
108            The modified KPool instance.
109        """
110        self.items = content.changeCase(self.items, case)
111        return self
112
113    def filterPrefix(self, pattern: str | list[str], mode: helpers.Strategy = "pick"):
114        """
115        Return a filtered instance with items (not) starting with the given pattern(s).
116
117        Args:
118            pattern: Single string or multiple patterns.
119            mode: Which filtering strategy to use:
120                - `pick`: include items of pattern only
121                - `omit`: remove pattern from items
122
123        Returns:
124            Filtered KPool instance.
125        """
126
127        def _process(string: str):
128            def _isMatch(item: str) -> bool:
129                found = item.startswith(string)
130                return found if mode == "pick" else not found
131
132            return [
133                item for item in self.items if _isMatch(item)
134            ]  # Process items to preserve textCase
135
136        intersected = helpers.intersect(
137            [_process(p) for p in helpers.coerceList(pattern)]
138        )
139        return KPool(
140            intersected,
141            shuffle=self._shuffle,
142        )
143
144    def filterTokens(self, tokens: list[content.CharacterToken] = ["word", "nonword"]):
145        """
146        Return a filtered instance with items of certain Unicode tokens. See `lib.content.filterByTokens`.
147
148        Args:
149            tokens: Tokens to filter by.
150
151        Returns:
152            Filtered KPool instance.
153        """
154        return KPool(
155            content.filterByTokens(self.items, tokens), shuffle=self._shuffle
156        )  # Process items to preserve textCase
157
158    def filterWithRegex(self, pattern: str):
159        """
160        Return a filtered KPool instance with items matching the given regex pattern.
161
162        Examples:
163            - `[^bdfhkl]+` => filter ascenders
164            - `[^Qgjpqy]+` => filter descenders
165
166        Args:
167            pattern: Regex pattern to match.
168
169        Returns:
170            Filtered KPool instance.
171        """
172        return KPool(
173            list(filter(lambda item: regex.search(f"^{pattern}$", item), self.items)),
174            shuffle=self._shuffle,
175        )  # Process items to preserve textCase
176
177    def shuffle(self) -> "KPool":
178        """Shuffle the items in place and return self."""
179        random.shuffle(self.items)
180        return self
181
182    def stripChars(self, chars: str = ".,:;-+−'’") -> None:
183        """
184        Remove specified characters from all items.
185
186        Args:
187            chars: Characters to strip. Defaults to commonly used symbols and punctuation.
188        """
189        self.items = [item.strip(chars) for item in self.items]
190
191    def _removeItem(self, match: str):
192        """
193        Remove an item by value (case-insensitive).
194
195        Args:
196            match: Item to remove.
197
198        Returns:
199            The modified KPool instance.
200        """
201        poolLen = f"{len(self.items)}\t"
202        try:
203            if DEBUG:
204                logger.debug("[{} About to remove]\t{}", poolLen, match)
205            matchInsensitive = match.casefold()
206            itemsInsensitive = [item.casefold() for item in self.items]
207            index = itemsInsensitive.index(matchInsensitive)
208            value = self.items[index]
209            if DEBUG:
210                logger.debug("[{} Removing]\t{}", poolLen, value)
211            self.items.pop(index)
212        except:
213            logger.warning("[{} Error removing item]\t{}", poolLen, match)
214        return self