lib.content

  1import re
  2import drawBot
  3import random
  4from typing import Literal, TypeAlias, Union
  5from itertools import cycle, islice, dropwhile
  6from string import capwords
  7import regex
  8from caseconverter import camelcase, kebabcase, snakecase, pascalcase
  9from loguru import logger
 10from icecream import ic
 11
 12from lib import helpers, layout, fonts
 13
 14WordShape: TypeAlias = Literal["descender", "ascender", "caps"]
 15"""Categories to filter words by their shape.
 16
 17See `classes.c32_pool.KPool.getItemByWidth` for usage.
 18"""
 19
 20TextCase: TypeAlias = Literal["UPPER", "lower", "Title", "Caps"]
 21"""Defines the supported text casing styles for conversion.
 22
 23- `UPPER`: Converts all letters to uppercase: `hi ibm` → `HI IBM`
 24- `lower`: Converts all letters to lowercase: `HI IBM` → `hi ibm`
 25- `Title`: Capitalizes the first letter of each word, lowercases the rest: `hi ibm` → `Hi Ibm`
 26- `Caps`: Like Title, but preserves acronyms in uppercase: `hi ibm USA` → `Hi Ibm USA`
 27"""
 28
 29CharacterToken: TypeAlias = Literal["word", "nonword"]
 30"""Type alias for character token types.
 31
 32See `filterByTokens` for usage.
 33"""
 34
 35
 36# ? Common words that should be lowercased in title case (unless at the start/end)
 37commonWords: list[str] = [
 38    "a",
 39    "an",
 40    "the",
 41    "as",
 42    "is",
 43    "are",
 44    "and",
 45    "but",
 46    "at",
 47    "in",
 48    "on",
 49    "of",
 50    "for",
 51    "by",
 52    "to",
 53]
 54"""List of common words to be lowercased in title case (unless at start/end)."""
 55
 56
 57def toPascalCase(input: str, space: bool = True) -> str:
 58    """Convert string to PascalCase, optionally inserting spaces between words and numbers.
 59
 60    Args:
 61        input: The input string.
 62        space: If True, insert spaces between (default: True).
 63
 64    Example:
 65        `One123Four` => `One 123 Four`
 66    """
 67    # ? Not using caseconverter.pascalcase() because it alters allcaps words
 68    separator = " " if space else ""
 69    # A Aa, a A, A 0
 70    expressions = ["([A-Z0-9])([A-Z][a-z])", "([a-z])([A-Z])", "([A-Za-z])([0-9])"]
 71    for exp in expressions:
 72        input = re.sub(rf"{exp}", rf"\1{separator}\2", input)
 73    return input[:1].upper() + input[1:]
 74
 75
 76def toCamelCase(input: str):
 77    """Convert string to camelCase.
 78
 79    Example:
 80        `Hello World` => `helloWorld`
 81    """
 82    return camelcase(input)
 83
 84
 85def toKebabCase(input: str) -> str:
 86    """Convert string to kebab-case.
 87
 88    Example:
 89        `Hello World` => `hello-world`
 90    """
 91    return kebabcase(input)
 92
 93
 94def toSnakeCase(input: str) -> str:
 95    """Convert string to snake_case.
 96
 97    Example:
 98        `Hello World` => `hello_world`
 99    """
100    return snakecase(input)
101
102
103def toTitleCase(input: str, retainUpper: bool = True) -> str:
104    """
105    Convert string to title case, handling special cases and acronyms.
106
107    Args:
108        input: The input string.
109        retainUpper: If True, retain uppercase acronyms: `True` USA, `False` Usa
110
111    Returns:
112        Title-cased string.
113
114    Example:
115        `sON Of The USA` => `Son of the USA`
116    """
117    specialChars: list[str] = ["-", "/"]
118
119    def _hasSpecialChars(word: str) -> bool:
120        """Returns True if word contains special characters."""
121        return any(char in word for char in specialChars)
122
123    def _handleSpecialChars(word: str) -> str:
124        """Apply title case to each part of a word split by special characters."""
125        for char in specialChars:
126            if char in word:
127                # ? Split by special char and apply title case to each part
128                parts = word.split(char)
129                return char.join([capwords(part) for part in parts])
130
131    def _processWord(word: str) -> str:
132        """Process a single word for title casing."""
133        # ? Always lowercase common words in continuous text
134        isOnEitherSide = helpers.isFirst(words, word) or helpers.isLast(words, word)
135        isCommon = word.casefold() in commonWords
136        if isCommon and not isOnEitherSide:
137            return word.lower()
138
139        # ? Handle special characters
140        if _hasSpecialChars(word):
141            return _handleSpecialChars(word)
142
143        # Uppercase and punctuation 2+ times
144        isCaps = regex.match(r"[\p{Lu}|\p{P}]{2,}", word)
145
146        # capwords() better .title() => retains lowercase ’s
147        return word if isCaps and retainUpper else capwords(word)
148
149    words = input.split(" ")
150    words = [_processWord(word) for word in words]
151    return " ".join(words)
152
153
154def changeCase(
155    input: list[str] | str,
156    case: TextCase = "Title",
157) -> list[str] | str:
158    """
159    Change the case of a string or list of strings.
160
161    Args:
162        input: String or list of strings to change case.
163        case: Desired case ("upper", "lower", "Title", "Caps").
164
165    Returns:
166        String or list of strings with changed case.
167
168    Example:
169        `the USA`
170        - `upper` => `THE USA`
171        - `lower` => `the usa`
172        - `Title` => `The Usa`
173        - `Caps`  => `The USA`
174    """
175
176    def _change(item):
177        if case.casefold() == "upper":
178            return item.upper()
179        elif case.casefold() == "lower":
180            return item.lower()
181        elif case.casefold() == "title":
182            return toTitleCase(item, False)
183        elif case.casefold() == "caps":
184            return toTitleCase(item)
185        else:
186            logger.warning("Unable to change case: {}", case)
187
188    if not case:
189        return input  # Pass through unchanged
190
191    if isinstance(input, list):
192        return [_change(item) for item in input]
193    else:
194        return _change(input)
195
196
197def isTitleCase(input: str) -> bool:
198    """Returns True if all words in the string are title case."""
199    return all([regex.match(r"^[\p{Lu}][\p{Ll}]+$", part) for part in input.split(" ")])
200
201
202def prettifyText(text: str) -> str:
203    """
204    Removes Wikipedia formatting tokens, extra whitespace and dumb quotes.
205
206    Args:
207        text: The input text.
208
209    Returns:
210        Prettified text.
211    """
212    removals = [
213        # Hair space
214        r" ",
215        # Remove citation references
216        r"\[[A-Za-z\d]+\](?::?\d+(?:[-–]\d+)?)?",
217        # Remove [citation needed]
218        r"\[citation needed\]",
219        r"\[clarification needed\]",
220        r"\[note [\d+]]",
221        r"\[NB [\d+]]",
222    ]
223    for removal in removals:
224        text = re.sub(rf"{removal}", "", text)
225
226    replacements = [
227        # Multiple spaces to single space
228        (r"[ ]{2,}", " "),
229        # Replace dumb single quotes
230        (r"\'([A-Za-z]+)\'", r"‘\1’"),
231        # Replace dumb single quotes used as contractions: it's => it’s
232        (r"([A-Za-z])\'([A-Za-z])?", r"\1’\2"),
233        # Replace dumb double quotes
234        (r"(\s?|^)\"([^\"]+)\"", r"\1“\2”"),
235        # Add missing space before ( { [ in text
236        (r"(\w)(\(|\[|\{)", r"\1 \2"),
237        # Add missing space after ) } ] in text
238        (r"(\)|\]|\})(\w)", r"\1 \2"),
239    ]
240
241    for before, after in replacements:
242        text = re.sub(before, after, text)
243
244    return text.strip()
245
246
247def omitMissing(
248    input: str | list[str],
249    font: str = None,
250    mode: Literal["glyphs", "words", "lines"] = "words",
251    debug=False,
252):
253    """
254    Omit missing characters from text or list of text blocks.
255
256    Args:
257        input: A single string or a list of strings to check for missing glyphs.
258        font: Font to use for checking glyphs (optional).
259        mode: Determines the omission granularity:
260            - `glyphs`: Omit only the missing characters, preserving the rest of the text.
261            - `words`: Omit entire words that contain missing glyphs.
262            - `lines`: Omit entire lines that contain missing glyphs.
263        debug: If True, log omitted units.
264
265    Returns:
266        Filtered text or list of text blocks with missing data omitted, depending on mode.
267    """
268    if font:
269        drawBot.font(font)
270
271    isInputString = isinstance(input, str)
272    match (mode):
273        case "glyphs":
274            glue = ""
275        case "words":
276            glue = " "
277        case "lines":
278            glue = "\n"
279    blocks = [input] if isInputString else input
280
281    output = []
282    for block in blocks:
283        units = list(block) if mode == "glyphs" else block.split(glue)
284        filtered = [unit for unit in units if drawBot.fontContainsCharacters(unit)]
285
286        if debug:
287            # Log omitted fontName if available
288            logMessage = lambda unit: (
289                ("[Omitted] {} for {}", unit, fonts.getFontName(font))
290                if font
291                else ("[Omitted] {}", unit)
292            )
293            [
294                logger.trace(*logMessage(unit))
295                for unit in units
296                if not drawBot.fontContainsCharacters(unit)
297            ]
298
299        # Do not add empty list
300        if filtered:
301            output.append(glue.join(filtered))
302
303    return glue.join(output) if isInputString else output
304
305
306def splitStringToSentences(input: str) -> list[str]:
307    """
308    Split running text into a list of sentences.
309
310    Args:
311        input: The input text.
312
313    Example:
314        `I am a sentence. I am another one.` => `["I am a sentence.", "I am another one."]`
315    """
316    replacements = [
317        # Newlines with spaces
318        (r"\n", " "),
319        # Multiple spaces to single space
320        (r"\s{2,}", " "),
321    ]
322    for [before, after] in replacements:
323        input = re.sub(rf"{before}", after, input)
324
325    # Skip abbreviations: (F. Elastica), Ficus var. elastica
326    sentenceExp = r"(?<!\w\.\w.)(?<![A-Z][a-z]\.)(?<![A-Z]\.)(?<=\.|\?)\s(?![a-z])"
327    return re.split(sentenceExp, input)
328
329
330def rotateList(input: list) -> list:
331    """
332    Rotate a list to produce all cyclic permutations.
333
334    Args:
335        input: The input list.
336
337    Example:
338        `[A, B, C]` => `[[A, B, C], [B, C, A], [C, A, B]]`
339    """
340    output = []
341
342    for item in input:
343        cycled = cycle(input)
344        skipped = dropwhile(lambda x: x != item, cycled)
345        sliced = islice(skipped, None, len(input))
346
347        output.append(list(sliced))
348
349    return output
350
351
352def chopSequence(input: str | list[str], limit: int = None, glue=" ", split=" "):
353    """
354    Split input into meaningful parts, optionally limiting the number of words: `A B C` => `A, AB, ABC`.
355
356    Args:
357        input: String or list of strings to chop.
358        limit: Limit to `n` words.
359        glue: String to join parts.
360        split: String to split input.
361
362    Example:
363    - input: single sentence
364        - `"I was late."` => `["I", "I was", "I was late."]`
365    - input: list of sentences
366        - `["For me.", "Right?"]` => `["For me.", "For me. Right?"]`
367    - limit: 2
368        - `["I", "I was"]`
369    """
370    if split and isinstance(input, str):
371        input = input.split(split)
372
373    inputLen = len(input)
374    # Limit size if provided
375    stop = min(limit, inputLen) if limit else inputLen
376
377    return [glue.join(input[:i]) for i in range(1, stop + 1)]
378
379
380def chopList(
381    input: list[str],
382    clamp: int = None,
383    mode: Literal["separate", "connected"] = "separate",
384    shuffle=False,
385) -> list[str]:
386    """
387    Chop a list of sentences into smaller parts, optionally connecting or shuffling them.
388
389    Args:
390        input: List of sentences.
391        clamp: Limit to n words per iteration.
392        mode: "separate" to chop individually, "connected" to connect chopped sentences.
393        shuffle: If True, shuffle input before chopping.
394
395    Example:
396        `["Hello there.", "Hi you."]` =>
397        - (separate) `["Hello", "Hello there.", "Hi", "Hi you."]`
398        - (connected) `["Hello", "Hello there.", "Hello there. Hi", ...]`
399    """
400    if shuffle:
401        random.shuffle(input)
402
403    if mode == "connected":
404        input = [" ".join(item) for item in rotateList(input)]
405
406    return helpers.flatten([chopSequence(item, clamp) for item in input])
407
408
409def permutate(input: list, clamp=20, shuffle=True) -> list:
410    """
411    Permutate and chop a list of sentences into connected sequences.
412
413    Args:
414        input: List of sentences.
415        clamp: Limit to `n` words per sequence.
416        shuffle: If True, shuffle input before permutation.
417
418    Example:
419        - `["Hi Tim", "Foo bar"]` => list of
420        - `["Hi", "Hi Tim", "Hi Tim Foo", ...], ["Foo", "Foo bar", "Foo bar Hi", ...]`
421    """
422    return chopList(input, clamp, "connected", shuffle)
423
424
425def fillTextOver(container: tuple, content: list, shuffle: bool = True) -> str:
426    """
427    Returns a string that fills the container up to overflow.
428
429    - Font properties need to be already set
430
431    Args:
432        container: Tuple specifying container dimensions.
433        content: List of possible sentences/items.
434        shuffle: If True, shuffle content before filling.
435    """
436    containerW, containerH = layout.toDimensions(container)
437
438    if shuffle:
439        content = helpers.shuffleAtRandomSegment(content)
440
441    strings = []
442
443    for string in content:
444        strings.append(string)
445        stream = " ".join(strings)
446        _, textH = drawBot.textSize(stream, width=containerW)
447        if textH >= containerH:
448            break
449
450    return stream
451
452
453def getStringForWidth(pool: list, width: int, threshold: float = 0.995) -> str:
454    """
455    Get a string from the pool that fits within the specified width.
456
457    - Font properties need to be set already
458
459    Args:
460        pool: List of candidate strings.
461        width: Target width.
462        threshold: Minimum width threshold.
463    """
464
465    def _isWidthAppropriate(candidateWidth: int):
466        return minWidth <= candidateWidth <= maxWidth
467
468    minWidth, maxWidth = width * threshold, width
469
470    candidateWidths = []
471    match = None
472
473    for candidate in pool:
474        candidateWidth, _ = drawBot.textSize(candidate)
475        candidateWidths.append(candidateWidth)
476
477        if _isWidthAppropriate(candidateWidth):
478            match = candidate
479            break
480
481    if match:
482        return match
483    else:
484        closestWidth = helpers.findClosestValue(
485            candidateWidths, width, discardLarger=True
486        )
487        i = (
488            candidateWidths.index(closestWidth)
489            if closestWidth in candidateWidths
490            else 0
491        )
492        return pool[i]
493
494
495def filterByShape(items: list[str], shape: WordShape | list[WordShape]) -> list[str]:
496    """
497    Filter words by descender, ascender, or caps shape.
498
499    Args:
500        items: List of words.
501        shape: Shape(s) to filter by.
502
503    Returns:
504        List of words matching the shape criteria.
505
506    Example:
507        - `["hi", "hey"], "descender"` => `["hi"]`
508    """
509
510    def _isNotShaped(pattern: str, item: str):
511        return not bool(re.search(pattern, item))
512
513    def _checkShape(shape):
514        wordShape = wordShapes.get(shape)
515        return filter(lambda item: _isNotShaped(wordShape, item), items)
516
517    wordShapes = dict(caps="[A-Z0-9]", ascender="[bdfihklt]", descender="[Qgjqpy/,]")
518    shapeSubsets = [_checkShape(shape) for shape in helpers.coerceList(shape)]
519    return helpers.intersect(shapeSubsets, retainOrder=False)
520
521
522def filterByTokens(
523    items: list[str], tokens: list[CharacterToken] = ["word", "nonword"]
524) -> list[str]:
525    """
526    Filter items by Unicode character token.
527
528    Args:
529        items: List of strings to filter.
530        tokens: List of token types to filter by.
531
532    Returns:
533        List of items matching the token criteria.
534
535    Example:
536        - `word`, `nonword` => `["A4", "R&B"]`
537    """
538
539    possiblePatterns = dict(
540        word=r"\p{Letter}", nonword=r"\p{Symbol}|\p{Number}|\p{Punctuation}"
541    )
542    patterns = [possiblePatterns.get(m) for m in tokens]
543
544    def _filterSingleToken(items: list[str], pattern: str):
545        return [item for item in items if bool(regex.search(pattern, item))]
546
547    individual = [_filterSingleToken(items, p) for p in patterns]
548
549    return helpers.intersect(individual)
550
551
552def isRagPretty(
553    content: Union[str, drawBot.drawBotDrawingTools.FormattedString], coords: tuple
554) -> tuple[bool, bool]:
555    """
556    Evaluate if a paragraph is nicely typeset.
557
558    Args:
559        content: Text content or `FormattedString`.
560        coords: Tuple specifying text box coordinates.
561
562    Returns:
563        Tuple of booleans (isGreat, isOkay).
564        - `isGreat`: All quite long, some very long
565        - `isOkay`: All quite long
566    """
567
568    def _calcLineWidths():
569        """Returns widths for all lines except last and for last line."""
570        textBounds = drawBot.textBoxCharacterBounds(content, coords)
571        linesByY = dict()
572
573        for segment in textBounds:
574            bounds, _, _ = segment
575            _, y, w, _ = bounds
576
577            if not linesByY.get(y):
578                linesByY[y] = 0
579
580            linesByY[y] += w
581
582        last = linesByY.pop(list(linesByY)[-1])
583        return linesByY.values(), last
584
585    try:
586        _, _, width, _ = coords
587        bodyWidths, lastWidth = _calcLineWidths()
588        # All lines are quite long
589        areAllGood = all([w >= width * 0.9 for w in bodyWidths])
590        # A portion of lines are very long
591        areSomeGreat = (
592            len([True for w in bodyWidths if w >= width * 0.95]) >= len(bodyWidths) / 3
593        )
594        # Last line is not longest and not an widow
595        isLastGood = max(bodyWidths) >= lastWidth >= width * 2 / 3
596
597        isOkay = areAllGood and isLastGood
598        # isGreat, isOkay
599        return (isOkay and areSomeGreat), isOkay
600    except Exception as e:
601        logger.warning("Failed isRagPretty: {}", e)
602        return False
603
604
605def filterForbidden(input: list[str]) -> list[str]:
606    """
607    Filter out explicit content using a prohibited terms list (found in `forbidden-....txt`).
608
609    Args:
610        input: List of strings to filter.
611
612    Returns:
613        Filtered list with inappropriate content removed.
614    """
615    with open(
616        "/Users/christianjansky/Library/CloudStorage/Dropbox/KOMETA-Draw/01 Content/forbidden-any.txt",
617        encoding="utf-8",
618    ) as f:
619        prohibited_terms = f.read().splitlines()
620    clean = []
621
622    for item in input:
623        is_clean = True
624        item_lower = item.lower()
625
626        for term in prohibited_terms:
627            if term.lower().strip() and term.lower() in item_lower:
628                is_clean = False
629                break
630
631        if is_clean:
632            clean.append(item)
633
634    return clean