Merge pull request #4 from Diapolo10/nightly

[0.2.0] Release

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,10 +1,10 @@
 """Main ANSI Escape sequence class"""
 
-from typing import Optional, Iterable
+from typing import Any, Dict, Iterable, Optional
 
-__all__ = ('AnsiEscape',)
+__all__ = ('AnsiEscape', 'escape_format',)
 
-_CLEAR = '\033[0m'
+_CLEAR: str = '\033[0m'
 
 
 class AnsiEscape:
@@ -20,13 +20,60 @@ def __str__(self) -> str:
 
         return ''
 
-    def __or__(self, other):
+    def __or__(self, other: Any) -> 'AnsiEscape':
         if isinstance(other, AnsiEscape):
             self.sequence += other.sequence
             return self
 
         self.string = str(other)
         return self
 
-    def __ror__(self, other):
+    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)

escapyde/colours.py

@@ -61,22 +61,22 @@
     'clear': (0,),
 }
 
-FBLACK = AnsiEscape(sequence_table['fg_black'])
-FRED = AnsiEscape(sequence_table['fg_red'])
-FGREEN = AnsiEscape(sequence_table['fg_green'])
-FYELLOW = AnsiEscape(sequence_table['fg_yellow'])
-FBLUE = AnsiEscape(sequence_table['fg_blue'])
-FMAGENTA = AnsiEscape(sequence_table['fg_magenta'])
-FCYAN = AnsiEscape(sequence_table['fg_cyan'])
-FWHITE = AnsiEscape(sequence_table['fg_white'])
+FBLACK: AnsiEscape = AnsiEscape(sequence_table['fg_black'])
+FRED: AnsiEscape = AnsiEscape(sequence_table['fg_red'])
+FGREEN: AnsiEscape = AnsiEscape(sequence_table['fg_green'])
+FYELLOW: AnsiEscape = AnsiEscape(sequence_table['fg_yellow'])
+FBLUE: AnsiEscape = AnsiEscape(sequence_table['fg_blue'])
+FMAGENTA: AnsiEscape = AnsiEscape(sequence_table['fg_magenta'])
+FCYAN: AnsiEscape = AnsiEscape(sequence_table['fg_cyan'])
+FWHITE: AnsiEscape = AnsiEscape(sequence_table['fg_white'])
 
-BBLACK = AnsiEscape(sequence_table['bg_black'])
-BRED = AnsiEscape(sequence_table['bg_red'])
-BGREEN = AnsiEscape(sequence_table['bg_green'])
-BYELLOW = AnsiEscape(sequence_table['bg_yellow'])
-BBLUE = AnsiEscape(sequence_table['bg_blue'])
-BMAGENTA = AnsiEscape(sequence_table['bg_magenta'])
-BCYAN = AnsiEscape(sequence_table['bg_cyan'])
-BWHITE = AnsiEscape(sequence_table['bg_white'])
+BBLACK: AnsiEscape = AnsiEscape(sequence_table['bg_black'])
+BRED: AnsiEscape = AnsiEscape(sequence_table['bg_red'])
+BGREEN: AnsiEscape = AnsiEscape(sequence_table['bg_green'])
+BYELLOW: AnsiEscape = AnsiEscape(sequence_table['bg_yellow'])
+BBLUE: AnsiEscape = AnsiEscape(sequence_table['bg_blue'])
+BMAGENTA: AnsiEscape = AnsiEscape(sequence_table['bg_magenta'])
+BCYAN: AnsiEscape = AnsiEscape(sequence_table['bg_cyan'])
+BWHITE: AnsiEscape = AnsiEscape(sequence_table['bg_white'])
 
-CLEAR = AnsiEscape(sequence_table['clear'])
+CLEAR: AnsiEscape = AnsiEscape(sequence_table['clear'])

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 <[email protected]>",]