X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=string_utils.py;h=a2f46332156e0c5fc41f3db8a8228a149272651c;hb=47ece7bceb442d70ddcc3c728533c4d4d2bccde4;hp=3c97ff7991726012ff091dc7aa042abb88000bf6;hpb=334f806094fa220bd6518b8b30b9d0f9d50daee2;p=python_utils.git

diff --git a/string_utils.py b/string_utils.py
index 3c97ff7..a2f4633 100644
--- a/string_utils.py
+++ b/string_utils.py
@@ -40,7 +40,17 @@ import string
 import unicodedata
 import warnings
 from itertools import zip_longest
-from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Literal,
+    Optional,
+    Sequence,
+    Tuple,
+)
 from uuid import uuid4
 
 import list_utils
@@ -847,6 +857,10 @@ def words_count(in_str: str) -> int:
     return len(WORDS_COUNT_RE.findall(in_str))
 
 
+def word_count(in_str: str) -> int:
+    return words_count(in_str)
+
+
 def generate_uuid(omit_dashes: bool = False) -> str:
     """
     Generated an UUID string (using `uuid.uuid4()`).
@@ -866,7 +880,9 @@ def generate_random_alphanumeric_string(size: int) -> str:
     Returns a string of the specified size containing random
     characters (uppercase/lowercase ascii letters and digits).
 
-    random_string(9) # possible output: "cx3QQbzYg"
+    >>> random.seed(22)
+    >>> generate_random_alphanumeric_string(9)
+    '96ipbNClS'
 
     """
     if size < 1:
@@ -961,6 +977,10 @@ def shuffle(in_str: str) -> str:
     return from_char_list(chars)
 
 
+def scramble(in_str: str) -> str:
+    return shuffle(in_str)
+
+
 def strip_html(in_str: str, keep_tag_content: bool = False) -> str:
     """
     Remove html code contained into the given string.
@@ -1091,7 +1111,6 @@ def valid_date(in_str: str) -> bool:
     """
     True if the string represents a valid date.
     """
-    import dateparse
     import dateparse.dateparse_utils as dp
 
     try:
@@ -1113,7 +1132,7 @@ def to_datetime(in_str: str) -> Optional[datetime.datetime]:
     try:
         d = dp.DateParser()  # type: ignore
         dt = d.parse(in_str)
-        if type(dt) == datetime.datetime:
+        if isinstance(dt, datetime.datetime):
             return dt
     except ValueError:
         msg = f'Unable to parse datetime {in_str}.'
@@ -1209,7 +1228,23 @@ def sprintf(*args, **kwargs) -> str:
     return ret
 
 
-class SprintfStdout(object):
+def strip_ansi_sequences(in_str: str) -> str:
+    """Strips ANSI sequences out of strings.
+
+    >>> import ansi as a
+    >>> s = a.fg('blue') + 'blue!' + a.reset()
+    >>> len(s)   # '\x1b[38;5;21mblue!\x1b[m'
+    18
+    >>> len(strip_ansi_sequences(s))
+    5
+    >>> strip_ansi_sequences(s)
+    'blue!'
+
+    """
+    return re.sub(r'\x1b\[[\d+;]*[a-z]', '', in_str)
+
+
+class SprintfStdout(contextlib.AbstractContextManager):
     """
     A context manager that captures outputs to stdout.
 
@@ -1229,10 +1264,10 @@ class SprintfStdout(object):
         self.recorder.__enter__()
         return lambda: self.destination.getvalue()
 
-    def __exit__(self, *args) -> None:
+    def __exit__(self, *args) -> Literal[False]:
         self.recorder.__exit__(*args)
         self.destination.seek(0)
-        return None  # don't suppress exceptions
+        return False
 
 
 def capitalize_first_letter(txt: str) -> str:
@@ -1372,7 +1407,7 @@ def make_contractions(txt: str) -> str:
             for second in second_list:
                 # Disallow there're/where're.  They're valid English
                 # but sound weird.
-                if (first == 'there' or first == 'where') and second == 'a(re)':
+                if (first in ('there', 'where')) and second == 'a(re)':
                     continue
 
                 pattern = fr'\b({first})\s+{second}\b'
@@ -1458,11 +1493,11 @@ def shuffle_columns_into_list(
     # Column specs map input lines' columns into outputs.
     # [col1, col2...]
     for spec in column_specs:
-        chunk = ''
+        hunk = ''
         for n in spec:
-            chunk = chunk + delim + input_lines[n]
-        chunk = chunk.strip(delim)
-        out.append(chunk)
+            hunk = hunk + delim + input_lines[n]
+        hunk = hunk.strip(delim)
+        out.append(hunk)
     return out
 
 
@@ -1488,11 +1523,11 @@ def shuffle_columns_into_dict(
     # Column specs map input lines' columns into outputs.
     # "key", [col1, col2...]
     for spec in column_specs:
-        chunk = ''
+        hunk = ''
         for n in spec[1]:
-            chunk = chunk + delim + input_lines[n]
-        chunk = chunk.strip(delim)
-        out[spec[0]] = chunk
+            hunk = hunk + delim + input_lines[n]
+        hunk = hunk.strip(delim)
+        out[spec[0]] = hunk
     return out
 
 
@@ -1517,9 +1552,9 @@ def to_ascii(x: str):
     b'1, 2, 3'
 
     """
-    if type(x) is str:
+    if isinstance(x, str):
         return x.encode('ascii')
-    if type(x) is bytes:
+    if isinstance(x, bytes):
         return x
     raise Exception('to_ascii works with strings and bytes')
 
@@ -1640,7 +1675,7 @@ def ip_v4_sort_key(txt: str) -> Optional[Tuple[int, ...]]:
     if not is_ip_v4(txt):
         print(f"not IP: {txt}")
         return None
-    return tuple([int(x) for x in txt.split('.')])
+    return tuple(int(x) for x in txt.split('.'))
 
 
 def path_ancestors_before_descendants_sort_key(volume: str) -> Tuple[str, ...]:
@@ -1655,7 +1690,7 @@ def path_ancestors_before_descendants_sort_key(volume: str) -> Tuple[str, ...]:
     ['/usr', '/usr/local', '/usr/local/bin']
 
     """
-    return tuple([x for x in volume.split('/') if len(x) > 0])
+    return tuple(x for x in volume.split('/') if len(x) > 0)
 
 
 def replace_all(in_str: str, replace_set: str, replacement: str) -> str:
@@ -1671,6 +1706,20 @@ def replace_all(in_str: str, replace_set: str, replacement: str) -> str:
     return in_str
 
 
+def replace_nth(in_str: str, source: str, target: str, nth: int):
+    """Replaces the nth occurrance of a substring within a string.
+
+    >>> replace_nth('this is a test', ' ', '-', 3)
+    'this is a-test'
+
+    """
+    where = [m.start() for m in re.finditer(source, in_str)][nth - 1]
+    before = in_str[:where]
+    after = in_str[where:]
+    after = after.replace(source, target, 1)
+    return before + after
+
+
 if __name__ == '__main__':
     import doctest