From 6cbff1138326af0b84a5efe273e0732a117cdd76 Mon Sep 17 00:00:00 2001 From: James Smith Date: Tue, 19 Nov 2024 20:49:29 -0700 Subject: [PATCH] Renamed ansi-string to ansi_string; added is_formatting_parsable() and is_formatting_valid() functions --- README.md | 9 +++---- setup.py | 2 +- src/ansi_string/ansi_string.py | 49 +++++++++++++++++++++++++--------- 3 files changed, 42 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 7ee5e69..6d568ba 100644 --- a/README.md +++ b/README.md @@ -274,11 +274,10 @@ The first argument, `s`, is a string to be formatted. If this string contains AN - Integer values which will be parsed in a similar way to above string ANSI directives - The following setting types will be used verbatim as the ANSI graphics code and no exceptions will be thrown (handle with care) - An `AnsiSetting` object generated outside of `AnsiFormat` function calls - - It is advised to check AnsiSetting.valid to ensure settings don't terminate the escape sequence + - It is advised to check `AnsiSetting.valid` to ensure settings don't terminate the escape sequence - A string which starts with the character `"["` plus ANSI directives (ex: `"[38;5;214"`) -Hint: After creation, `is_optimizable()` can be called to determine if all settings are parsable. Call -`simplify()` in order to subsequently force invalid or redundant values to be thrown out. +Hint: After creation, `is_formatting_parsable()` can be called to determine if all settings are parsable. Call `simplify()` in order to force invalid or redundant values to be thrown out. Examples: @@ -359,9 +358,9 @@ ul_colors = [0xFF, 0x63, 0x47] print(f"{ansi_str::rgb({fg_color});bg_rgb({bg_colors});ul_rgb({ul_colors})}") ``` -#### is_optimizable +#### is_formatting_parsable -The methods `AnsiString.is_optimizable()` and `AnsiStr.is_optimizable()` are provided to determine if the provided formatting settings are considered valid and therefore optimizable. +The methods `AnsiString.is_formatting_parsable()` and `AnsiStr.is_formatting_parsable()` are provided to determine if the provided formatting settings are parsable into known ANSI codes. #### simplify diff --git a/setup.py b/setup.py index 919e06f..e80b7e0 100644 --- a/setup.py +++ b/setup.py @@ -4,7 +4,7 @@ long_description = fh.read() setuptools.setup( - name='ansi-string', + name='ansi_string', author='James Smith', author_email='jmsmith86@gmail.com', description='ANSI String Formatter in Python for CLI Color and Style Formatting', diff --git a/src/ansi_string/ansi_string.py b/src/ansi_string/ansi_string.py index c111d6b..cf64a8f 100644 --- a/src/ansi_string/ansi_string.py +++ b/src/ansi_string/ansi_string.py @@ -33,8 +33,8 @@ ) from .ansi_parsing import ParsedAnsiControlSequenceString, parse_graphic_sequence, settings_to_dict -__version__ = '1.1.5' -PACKAGE_NAME = 'ansi-string' +__version__ = '1.1.6' +PACKAGE_NAME = 'ansi_string' # Constant: all characters considered to be whitespaces - this is used in strip functionality WHITESPACE_CHARS = ' \t\n\r\v\f' @@ -176,8 +176,8 @@ def __init__( - It is advised to check AnsiSetting.valid to ensure settings don't terminate the escape sequence - A string which starts with the character "[" plus ANSI directives (ex: "[38;5;214") - Hint: After creation, is_optimizable() can be called to determine if all settings are parsable. Call - simplify() in order to subsequently force invalid or redundant values to be thrown out. + Hint: After creation, is_formatting_parsable() can be called to determine if all settings are parsable. Call + simplify() in order to force invalid or redundant values to be thrown out. ''' # Key is the string index to make a color change at self._fmts:Dict[int,'_AnsiSettingPoint'] = {} @@ -678,19 +678,33 @@ def _apply_string_format(self, string_format:str, settings:Union[AnsiFormat, Ans raise ValueError('Invalid format specifier') - def is_optimizable(self) -> bool: + def is_formatting_valid(self) -> bool: ''' - Returns True iff all of the following are true for this object: - - No verbatim setting strings (strings that starts with "[") were set in formatting - - All parsed settings are considered internally valid + Returns True iff all settings are valid. Validity only means that no settings will prematurely terminate the + escape code. Call is_formatting_parsable() to determine if all settings are meaningful. + ''' + for fmt in self._fmts.values(): + for setting in fmt.add: + if not setting.valid: + return False + return True + + def is_formatting_parsable(self) -> bool: + ''' + Returns True iff all settings are valid and parsable into known ANSI codes. ''' - # Check if optimization is possible for fmt in self._fmts.values(): for setting in fmt.add: if not setting.parsable: return False return True + def is_optimizable(self) -> bool: + ''' + Returns True if optimization of formatting settings can be performed i.e. formatting is parsable. + ''' + return self.is_formatting_parsable() + def to_str(self, __format_spec:str=None, optimize:bool=True) -> str: ''' Returns an ANSI format string with both internal and given formatting spec set. @@ -1823,11 +1837,22 @@ def __iadd__(self, value:Union[str,'AnsiString','AnsiStr']) -> 'AnsiStr': # Can't add in place - always return a new instance return (self + value) + def is_formatting_valid(self) -> bool: + ''' + Returns True iff all settings are valid. Validity only means that no settings will prematurely terminate the + escape code. Call is_formatting_parsable() to determine if all settings are meaningful. + ''' + return self._s.is_formatting_valid() + + def is_formatting_parsable(self) -> bool: + ''' + Returns True iff all settings are valid and parsable into known ANSI codes. + ''' + return self._s.is_formatting_parsable() + def is_optimizable(self) -> bool: ''' - Returns True iff all of the following are true for this object: - - No verbatim setting strings (strings that starts with "[") were set in formatting - - All parsed settings are considered internally valid + Returns True if optimization of formatting settings can be performed i.e. formatting is parsable. ''' return self._s.is_optimizable()