[MINOR] Added the escape_format function

Author: Diapolo10

CHANGELOG.md

@@ -68,9 +68,29 @@ First official documentation.
 
 _______________________________________________________________________________
 
+## [0.2.0] - 2022-01-16
+
+This release adds a new function, `escapyde.escape_format`, which can be used
+to format known substrings in a string with ANSI escape sequences. In addition
+the codebase now uses type hints thorought.
+
+The new feature was inspired by [this Reddit thread][Reddit escape format].
+
+### Added
+
+- Added `escapyde.escape_format`
+- Added more type hints for better typing coverage
+
+### Changed
+
+- Updated the localisation files
+
+_______________________________________________________________________________
+
 ## [0.1.2] - 2021-12-01
 
-This release adds support for arbitrary types; previously `AnsiEscape` only supported strings.
+This release adds support for arbitrary types; previously `AnsiEscape` only
+supported strings.
 
 ### Changed
 
@@ -81,7 +101,8 @@ _______________________________________________________________________________
 
 ## [0.1.1] - 2021-12-01
 
-A hotfix release that fixes a problem in the README example code, and adds a screenshot of the code running.
+A hotfix release that fixes a problem in the README example code, and adds a
+screenshot of the code running.
 
 ### Added
 
@@ -127,6 +148,8 @@ the initial commit.
 - Fixed an oversight related to chaining ANSI escape sequences
 - Fixed linter issues
 
+[Reddit escape format]: https://www.reddit.com/r/learnpython/comments/rvcg0l/print_colour_in_terminal/hr73v3f/
+
 <!-- markdownlint-configure-file {
     "MD022": false,
     "MD024": false,

escapyde/ansi.py

@@ -1,8 +1,8 @@
 """Main ANSI Escape sequence class"""
 
-from typing import Any, Iterable, Optional
+from typing import Any, Dict, Iterable, Optional
 
-__all__ = ('AnsiEscape',)
+__all__ = ('AnsiEscape', 'escape_format',)
 
 _CLEAR: str = '\033[0m'
 
@@ -30,3 +30,50 @@ def __or__(self, other: Any) -> 'AnsiEscape':
 
     def __ror__(self, other: Any) -> 'AnsiEscape':
         return self.__or__(other)
+
+
+def escape_format(string: str, escape_map: Dict[str, AnsiEscape], case_sensitive: bool=False) -> str:
+    """
+    Maps a dictionary of substrings => escape sequences to the given string,
+    returning a new string with the sequences applied to all
+    found substrings.
+
+    Example:
+
+    COLOURS = {
+        'red': esc.FRED,
+        'green': esc.FGREEN,
+        'yellow': esc.FYELLOW,
+        'blue': esc.FBLUE,
+        'magenta': esc.FMAGENTA,
+        'cyan': esc.FCYAN,
+        'white': esc.FWHITE,
+        'black': esc.FBLACK,
+    }
+
+    text = \"\"\"Hello, red world! The sun is bright yellow, and the sky cyan blue.
+    Green, lush fields are all around us.\"\"\"
+
+    print(escape_format(text, COLOURS))  # Would print all mapped words in their respective colours
+
+    Inspired by: https://www.reddit.com/r/learnpython/comments/rvcg0l/print_colour_in_terminal/hr73v3f/
+    """
+
+    lines = string.splitlines()
+    for line_idx, line in enumerate(lines):
+
+        words = line.split(' ')
+        for substring, escape in escape_map.items():
+
+            for idx, word in enumerate(words):
+
+                if not case_sensitive:
+                    substring = substring.lower()
+                    word = word.lower()
+
+                if word.startswith(substring):
+                    words[idx] = f'{escape | word[:len(substring)]}{word[len(substring):]}'
+
+        lines[line_idx] = ' '.join(words)
+
+    return '\n'.join(lines)

pyproject.toml

@@ -17,7 +17,7 @@ __init__.py:F401,F403,F405\
 
 [tool.poetry]
 name = 'escapyde'
-version = '0.1.2'
+version = '0.2.0'
 description = "Yet another ANSI escape sequence library for Python - now modernised!"
 
 authors = ["Lari Liuhamo <lari.liuhamo+pypi@gmail.com>",]