TextTools

module texttools

• Collection of console text and ansi manipulation tools
• Add/create text colors for console
• Includes limited html formatting
• Adds a custom color template to user app folder that is loaded on import
• Some consoles may not accept all available attributes
• Ansi and AnsiList for working with strings containing ansi escapes

Ansi

texttools.ansitools.Ansi

Work with strings containing ansi escape codes

    - Reports accurate (printed) string length
    - Built in method to convert to an html `<span>` string
        - wrapper for TextTools classmethod `esc2html`
    - Provides a 'clean' (escapes removed) version of the string
    - Will not throw an 'IndexError' with __getitem__, instead will return an empty string
    - Overloaded Constructor
        - If multiple strings are passed to Ansi(), an [AnsiList](#ansilist) is returned
    - Tries to always return an Ansi object when standard strings are inserted/added
        - This won't work when using an Ansi object in an f-string

class Ansi(str):
    """
        Holds a string object with escapes while still reporting an accurate
      length. also provides a cleaned version (no escapes).

        Using f-strings will 're-class' the object to a standard str() object.
      It is recommended to use the '+' operator to join standard string objects
      with Ansi objects so that they remain Ansi types.
    """
    def __init__(self, string = '', **kwargs):
        """
        Create an Ansi string
        ========================================================================
        **kwargs:
            'last_esc_on_slices': add last ansi escape to end of string if
                                    slice leaves it out
                                    - DEFAULT = False
            'reset_on_slice'    : add ansi text reset to end of slices
                                    - overrides 'last_esc_on_slices' if True
                                    - DEFAULT = False
            'strsep'            : passed to AnsiList if split is used

            * Also will look for environment variables 'LAST_ESC_ON_SLICES' and
                'RESET_ON_SLICES' in os.environ. Boolean values are expected.
                Anything other than 'false', '0', or 'no' will set these values
                to True.
        """

Ansi is a subclass of str, made to facilitate the formatting and printing of strings containing ansi escape codes. Because escape codes, on terminals that accept escapes, don't use any columns when printed, it makes it hard to do print formatting and text coloring. This attempts to account for that by manipulating the character count. This greatly changes iteration, indexing, and slicing of an Ansi object.

It can be confusing to use getitem and iter methods. Iterating through 'string' will separate the escapes as single characters. In the case of 'string', the last yielded item is '\x1b[0m', yet string[-1] returns '!\x1b[0m', prepending the last non escaped character to the ansi escape. This is by design because the Ansi and AnsiList classes are specifically made to assist in printing and print formatting with strings containing ansi escapes. The attributes clean and string are provided in Ansi() as native str objects for more complicated uses. Another attribute escapes will list all the escapes in the string. This was the best I could come up with for handling iteration, indexing, and slicing.

Because of the complications of iteration and slicing, it will never throw an IndexError when using getitem. Instead, an empty string '' will be returned.

Here is showing some characteristics of Ansi objects:

>>> from texttools import Ansi
>>> string = Ansi( '\x1b[38;2;51;153;255mHello\x1b[38;2;102;255;102m World!\x1b[0m' )

# Actual length
>>> string.rlen()
53

# Normal reported length
>>> len(string)
12

# Iteration
>>> string_list = list(string)
>>> string_list
['\x1b[38;2;51;153;255m',
 'H',
 'e',
 'l',
 'l',
 'o',
 '\x1b[38;2;102;255;102m',
 ' ',
 'W',
 'o',
 'r',
 'l',
 'd',
 '!',
 '\x1b[0m']
>>> len(string_list)
15

# indexing and slicing
>>> string[-1]
'!\x1b[0m'

>>> string[:5]
'\x1b[38;2;51;153;255mHello'

>>> string[:6]
'\x1b[38;2;51;153;255mHello\x1b[38;2;102;255;102m '
    # notice the space after the escape code

>>> string[:7]
'\x1b[38;2;51;153;255mHello\x1b[38;2;102;255;102m W'

Because of the characteristics of Ansi strings, splitting is also a bit different. Ansi.split() with no arguments will split the string using the value in Ansi.strsep and return an AnsiList containing the same strsep value. This works vice-versa as well when using the added list method join in AnsiList.

>>> from texttools import Ansi

>>> string = Ansi( '\x1b[38;2;51;153;255mHello\x1b[38;2;102;255;102m World!\x1b[0m' )
>>> string.split()
[ '\x1b[38;2;51;153;255mHello\x1b[38;2;102;255;102m',
  'World!\x1b[0m' ]

# let's try setting the 'strsep' kwarg to 'l'
>>> string = Ansi( '\x1b[38;2;51;153;255mHello\x1b[38;2;102;255;102m World!\x1b[0m', strsep = 'l' )
>>> split_string = string.split()
>>> split_string
[ '\x1b[38;2;51;153;255mHe',
  '',
  'o\x1b[38;2;102;255;102m Wor',
  'd!\x1b[0m' ]

>>> type(split_string)
texttools.ansitools.AnsiList

return to contents

texttools.ansitools.AnsiList

    def iterclean(self):
        """
        A generator of this list with all ansi escapes removed
        """

    def join(self, s = None, **kwargs):
        """
        Join items in the list with the character in self.strsep
            - returns an Ansi object
        """

    def strip(self, item = None, *, strip_none = False ):
        """
        Removes any list items matching 'item'
            - returns a new AnsiList object
        """

texttools.TextTools

class TextTools:
    """
    Tools for getting and printing colorized/styled text
    """

      # All functions in this class are classmethods

texttools.TextTools.ansi2rgb

@classmethod
def ansi2rgb(cls, ansi, *, fg_color = True, bg_color = True):
    """
    ansi2rgb( ansi, *, fg_color = True, bg_color = True ) >>> tuple()

        Returns a 5 or 10 part tuple from a string containing ansi escapes
          *args
            'ansi': string containing ansi escape patterns

          **kwargs
            'fg_color': include foreground tuple in results
                         - default = True
            'bg_color': include background color in results
                         - default = True

            Foreground color is always at the beginning of the tuple if both
          'fg_color' and 'bg_color' are True and both values are found
    """

texttools.TextTools.blockTxt

    @classmethod
    def blockTxt( cls, txt, *,
                  fill_indent = False,
                  fill_width = False,
                  indent = 0,
                  indent_first = 0,
                  keep_newlines = False,
                  line_break = ' ',
                  push = 0,
                  push_first = False,
                  split_escapes = True,
                  start_column = 0,
                  width = 0,
                  width_includes_indent = True ):
        """
        Indents text for neater printing
          *args:
            'indent'   : amount of indenting to use after 1st line
                          - 'txt' is split by newlines and 'line_break' value
                          - if 'keep_newlines' == True, only 'line_break' value is
                            used to split 'txt'
                          - default = 0
            'push'     : push all indent values (does not include width)
                         to the right [n] amount of columns
                          - default = 0
            'txt'      : full text string
            'width'    : total width of text block
                          - if negative, subtract from the width found
                            using os.get_terminal_size
                          - does not include indent if width_includes_indent == False

          **kwargs:
            'indent_first'         : Amount of columns to indent to first line
                                      - 'indent' to matches the indent value
                                      - a negative value subtracts from indent value
                                        ( minumum value will be 0 )
                                      - default = 0
            'width_includes_indent': If True (default), includes indent in total width,
                                     otherwise total width = width + indent
            'start_column'         : Column that first line starts on
                                      - use 'indent' to match the indent value
                                      - default = 0
            'split_escapes'        : Resets text at end of lines and uses escapes from
                                     the previous line to reset it.
                                      - default = True
            'keep_newlines'        : Doesn't remove newlines from provided text
                                      - might have double newlines in result
            'line_break'           : Provide a string pattern to try to break lines on
                                      - default = ' '
            'push_first'           : Include the first line when using 'push' argument
                                      - default = False
           ** use fill options to make sure background colors, if used, will cover before
                and/or after the text characters

            'fill_width'           : Fill the remaining width in each line with a space
                                      - default = False
            'fill_indent'          : Insert escape code before the indent spaces when using
                                     'split_escapes'
                                      - default = False
        """

texttools.TextTools.hex2rgb

    @classmethod
    def hex2rgb(cls, HEX):
        """
        Returns an RGB tuple from a hexidecimal code
            'HEX': hexidecimal value representing a color
        """

texttools.TextTools.rgb2ansi

    @classmethod
    def rgb2ansi(cls, R = 0, G = 0, B = 0, *, bg = False):
        """
        Returns an ansi escape string from RGB values
            'R': integer for Red    [0-255]
            'G': integer for Green  [0-255]
            'B': integer for Blue   [0-255]

          * default values are set to Black - (0,0,0)
        """

texttools.TextTools.rgb2hex

    @classmethod
    def rgb2hex(cls, RGB):
        """
        Returns a hexidecimal code from an rgb code
            'RGB': tuple|list of 3 integers
        """

texttools.TextTools.rgbString

    @classmethod
    def rgbString(cls, value):
        """
        Create an rgb string
            'value': hex, string of integers, list|tuple, or FG_Color|BG_Color
        """

texttools.TextTools.money_fmt

    @classmethod
    def money_fmt(cls, n, *, color_type = 'term'):
        """
        Return formatted number to money string
            accepted color_type:
                'term', 'term_reverse', 'html', or 'html_reverse'
        """

texttools.TextTools.t2a

    @classmethod
    def t2a(cls, t: tuple|list, *, end = 'm'):
        """
        Tuple to ansi escape
            - provide a tuple or list of ansi escape integers
            - returns an ansi escape string
        """

texttools.TextTools.from16

    @classmethod
    def from16(cls, color, *, return_data = False):
        """
        16 color tuple to rgb tuple
            - if len(tup) == 1, assumes 0 for first value
        """

texttools.TextTools.to16color

    @classmethod
    def to16color(cls, rgb, *, bg = False, color_dict = False, diff_key = COLORS_RGB_DIFF_KEY, all_results = False ):
        """
        Rgb to 16 color tuple
            - rgb length can be 3 or 5
            - if rgb doesn't match color, tries to find the closest match
            - if len(rgb) != 5, a fg color is returned by default

            'bg'         : True to force or set to return a bg color
            'data'       : True to return a dict
            'diff_key'   : key to sort matches by
                            [ 'mean'||'median'||'max'||'min'||'min_max_avg' ]
            'all_results': return a list of all result data
                            - assumes 'data' == True
        """

texttools.TextTools.help

    @classmethod
    def help(cls, *, return_list = False):
        """
        TextTools help message
            - prints detailed list of available colors

          'return_list': return as a list instead of printing
                          - default = False
        """

    Ansi style: Blink
      - Set text to blinking

    Attribute Name:   Bl|blink
    Ansi Code:        (5,)

    Ansi style: Remove Blink
      - Remove the blinking text escape

    Attribute Name:   Bl_|remove_blink
    Ansi Code:        (25,)

    Ansi style: Bold
      - Set text to bold

    Attribute Name:   B|bold
    Ansi Code:        (1,)

    Ansi style: Remove Bold
      - Remove the bold text option

    Attribute Name:   B_|remove_bold
    Ansi Code:        (21,)

    Ansi style: Italic
      - Set text to italic

    Attribute Name:   I|italic
    Ansi Code:        (3,)

    Ansi style: Remove Italic
      - Remove the italic text option

    Attribute Name:   I_|remove_italic
    Ansi Code:        (23,)

    Ansi style: Strikethrough
      - Set strikethrough decoration to text

    Attribute Name:   S|strikethrough
    Ansi Code:        (9,)

    Ansi style: Remove Strikethrough
      - Remove the strike-through text option

    Attribute Name:   S_|remove_strikethrough
    Ansi Code:        (29,)

    Ansi style: Underline
      - Set underline decoration to text

    Attribute Name:   U|underline
    Ansi Code:        (4,)

    Ansi style: Remove Underline
      - Remove the underline text option

    Attribute Name:   U_|remove_underline
    Ansi Code:        (24,)

    Ansi style: Reset
      - Reset all ansi styles and colors

    Attribute Name:   _|reset
    Ansi Code:        (0,)

>>> from texttools import FG
>>> FG.help()
"""
  Colors:

    Attributes can be 'stacked' using the BITAND '&' to create an AnsiCombo
      Example:
        FG.white & BG.charcoal & S.Bold

      You can only have a Reset object at the beginning of an AnsiCombo
        S._ & FG.red

      Only one of each color type or Style type is accepted when combining. If 2
    or more objects of the same type are detected, a ValueError will be raised. If a Reset
    object is added anywhere except the beginning of the combo, a TypeError is raised

      NOTE: all color groups share a Reset ('\x1b[0m') object

  Colors in class:
                    ...
"""

# Import colors

>>> from texttools import ( FG as c,
>>>                         BG as bg,
>>>                         Styles as S )

# Get colors by full name or 'code' name

>>> color = c.charcoal
>>> color
AnsiColor(< Charcoal (Fg) >)

>>> color = c.ch
>>> color
AnsiColor(< Charcoal (Fg) >)

>>> str(color)
'\x1b[38;2;26;26;26m'

# AnsiColor attributes

>>> color.rgb       # RGB tuple
(26, 26, 26)
>>> ch.name         # object name
'Charcoal (Fg)'
>>> ch.hex          # hexidecimal value
'#1a1a1a'

texttools.types.Brightened

>>> gray = c.dark_gray
>>> gray.rgb
(56, 56, 56)

>>> gray_brightened = color.bright(20)
>>> gray_brightened
'Brightened(< Dark Gray (Fg) - %20 >)'

>>> gray_brightened.rgb
(96, 96, 96)

# You can also use the '+' operator to add the default (15%) bright value
>>> +gray
'Brightened(< Dark Gray (Fg) - %15 >)'

# Doing this more than once will exponentially brighten the object
>>> (+gray).rgb
(86, 86, 86)

>>> (+++gray).rgb
(133, 133, 133)

# NOTE when using operators like this in AnsiCombo creation, the expressions
#   need to be wrapped in parentheses.

texttools.types.Dimmed

>>> blue = c.light_blue
>>> blue.rgb
(51, 153, 255)

>>> blue_dimmed = blue.dim(20)
>>> blue_dimmed
'Dimmed(< Light Blue (Fg) - %20 >)'

>>> blue_dimmed.rgb
(41, 122, 204)

# You can also use the '-' operator to subtract the default (15%) dim value
>>> (-blue).rgb
(43, 130, 217)

# Doing this more than once will exponentially dim the object
>>> (---blue).rgb
(31, 94, 156)

texttools.types.Inverted

>>> blue = c.light_blue
>>> blue.rgb
(51, 153, 255)

>>> blue_inverted = blue.invert()
>>> blue_inverted
'Inverted(< Light Blue (Fg) >)'

>>> blue_inverted.rgb
(204, 102, 0)

# You can also use the '~' operator to invert
>>> (~blue).rgb
(204, 102, 0)

# Doing this more than once or using invert() on the inverted object
# will just revert back to the original AnsiColor

>>> blue_inverted.invert()
AnsiColor(< Light Blue (Fg) >)

texttools.types.Blended

>>> white = c.white
>>> white.rgb
(255, 255, 255)

>>> orange = c.orange
>>> orange.rgb
(255, 128, 0)

>>> white_orange_blend = white.blend( orange, 40 )
>>> white_orange_blend
'Blended(< White||Orange- %40 >)'

>>> white_orange_blend.rgb
(255, 204, 153)

# AnsiColors can also be blended using the BITOR '|' operator
#  - this uses the default 15% blend value

>>> white_orange = white|orange
>>> white_orange
'Blended(< White||Orange- %15 >)'

texttools.types.AnsiCombo

>>> from texttools import FG, BG, Styles as S

>>> combo = FG.yellow & BG.blue
>>> combo
"AnsiCombo(< Yellow (Fg) + Bg Blue (Bg) >)"

    # here, FG._ is actually a Reset object, not an FG_Color
>>> combo = FG._ & FG.gold & BG.dark_gray & S.italic
>>> combo
"AnsiCombo(< Reset + Gold (Fg) + Bg Silver (Bg) + Italic >)"

    # trying to add a Reset in the middle of Combo
>>> combo = FG.gold & FG._ & BG.dark_gray & S.italic
"TypeError: Can't add 'Reset' type to another attribute"

    # adding 2 conflicting objects
>>> combo = FG.gold & S.remove_italic & BG.dark_gray & S.italic
"ValueError: 'AnsiCombo' already contains 'italic' attributes"

texttools.cursorcontrols.CursorControls

>>> from texttools import Cursor

>>> Cursor.Clear.__doc__
        """
        Clear screen or line
          - alias = 'Cursor.clr'
          - clear entire screen (2J)

            Clear.line
              - clear current line (2K)
                L: clear line left of cursor (1K)
                R: clear line right of cursor (0K)

            Clear.screen
              - clear entire screen (2J)
                up: clear screen above cursor (1J)
                dn: clear screen below cursor (0J)
        """

>>> Cursor.L.__doc__
        """
        Cursor Left
          'n': Number of columns
        """

>>> Cursor.R.__doc__
        """
        Cursor Right
          'n': Number of columns
        """

>>> Cursor.col.__doc__
        """
        Cursor To Column
          'n': column number
        """

>>> Cursor.dn.__doc__
        """
        Cursor Down
          'n': Number of lines
        """

>>> Cursor.getpos.__doc__
        """
        Get cursor position
            - returns tuple( [line], [column] )
        """

>>> Cursor.help.__doc__
        """ Help message """

>>> Cursor.hide.__doc__
        """ Cursor Invisible """

>>> Cursor.pos.__doc__
        """
        Set cursor position
            - PositionCursor( [line], [column] )
        """

>>> Cursor.show.__doc__
        """ Cursor Visible """

>>> Cursor.up.__doc__
        """
        Cursor Up
          'n': Number of lines
        """