TTkString

TTkString🌶️

class TTkString(text: str | TTkString = '', color: TTkColor | None = None)[source]🌶️

Bases: object

TermTk String Helper

The TTkString constructor creates a terminal String object.

Parameters:

text (str, optional) – text of the string, defaults to “”
color (TTkColor, optional) – the color of the string, defaults to TTkColor.RST

Example:

# No params Constructor
str1 = TTkString() + "test 1"
str2 = TTkString() + TTkColor.BOLD + "test 2"

# Indexed params constructor
str3 = TTkString("test 3")
str4 = TTkString("test 4", TTkColor.ITALIC)

# Named params constructor
str5 = TTkString(text="test 5")
str6 = TTkString(text="test 6", color=TTkColor.ITALIC+TTkColor.bg("000044"))

# Combination of constructors (Highly Unrecommended)
str7 = TTkString("test 7", color=TTkColor.fg('#FF0000'))

Methods🌶️

align(width: int = 0, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>, alignment: ~TermTk.TTkCore.constant.TTkConstant.Alignment = Alignment.NONE) → TTkString[source]🌶️

Align the string

Parameters:

width (int, optional) – the new width
color (TTkColor, optional) – the color of the padding, defaults to TTkColor.RST
alignment (TTkK.Alignment, optional) – text alignment within the requested width

Returns:

aligned string with preserved styling

Return type:

TTkString

charAt(pos: int) → str[source]🌶️

Return the character at the given position.

Parameters:: pos (int) – character index
Returns:: character at pos
Return type:: str

colorAt(pos: int) → TTkColor[source]🌶️

Return the color assigned to the character at pos.

Parameters:: pos (int) – character index
Returns:: color at pos or TTkColor.RST when out of range
Return type:: TTkColor

completeColor(color: TTkColor, match: str | None = None, posFrom: int | None = None, posTo: int | None = None) → TTkString[source]🌶️

Complete the color of the entire string or a slice of it

The Fg and/or Bg of the string is replaced with the selected Fg/Bg color only if missing

If only the color is specified, the entire string is colorized

Parameters:

color (TTkColor) – the color to be used, defaults to TTkColor.RST
match (str, optional) – the match to colorize
posFrom (int, optional) – the initial position of the color
posTo (int, optional) – the final position of the color

Returns:

recolored string

Return type:

TTkString

extractShortcuts() → Tuple[TTkString, List[str]][source]🌶️

Extract & shortcuts and underline the mnemonic characters.

Returns:: tuple of processed string and extracted shortcut characters
Return type:: tuple[TTkString, list[str]]

find(*args, **kwargs) → int[source]🌶️

Return the first index of a substring using str.find semantics.

Returns:: start index of the first match, or -1 if not found
Return type:: int

findall(regexp: str, ignoreCase: bool = False) → List[Any][source]🌶️

FindAll the regexp matches in the string

Parameters:

regexp (str) – the regular expression to be matched
ignoreCase (bool) – Ignore case, defaults to False

Returns:

list of all matches

Return type:

list[str] | list[tuple]

getData() → Tuple[Tuple[str, ...] | List[str], List[TTkColor]][source]🌶️

Return text and color data in terminal-rendered form.

Returns:: tuple of characters and colors
Return type:: tuple

getIndexes(char: str) → List[int][source]🌶️

Return indexes where char appears.

Parameters:: char (str) – target character
Returns:: matching character positions
Return type:: list[int]

isPlainText() → bool[source]🌶️

Return True if the string has no color/style information.

Returns:: True when all chars use TTkColor.RST
Return type:: bool

isdigit() → bool[source]🌶️

Check whether the string contains only digit characters.

Returns:: True if all characters are digits and the string is non-empty
Return type:: bool

join(strings: GeneratorType[TTkStringType, None, None] | List[TTkStringType] | List[TTkString] | List[str]) → TTkString[source]🌶️

Join the input strings using the current as separator

Parameters:: strings (list) – the list of strings to be joined
Returns:: joined string
Return type:: TTkString

lstrip(ch: str) → TTkString[source]🌶️

Return a copy with leading characters removed.

Parameters:: ch (str) – characters to strip from the left side
Returns:: left-stripped string preserving color alignment
Return type:: TTkString

nextPos(pos: int) → int[source]🌶️

Return next editable character position.

Parameters:: pos (int) – current position
Returns:: next non-combining character index
Return type:: int

prevPos(pos: int) → int[source]🌶️

Return previous editable character position.

Parameters:: pos (int) – current position
Returns:: previous non-combining character index
Return type:: int

replace(*args, **kwargs) → TTkString[source]🌶️

replace (old, new, count)

Replace “old” match with “new” string for “count” times

Parameters:

old (str) – substring to be replaced
new (str, optional) – replacement substring
count (int, optional) – maximum number of replacements

Returns:

updated string preserving color spans

Return type:

TTkString

sameAs(other: str | TTkString) → bool[source]🌶️

Check whether text and per-character colors are identical.

Parameters:: other (TTkString | str) – string to compare against
Returns:: True when text and colors match exactly
Return type:: bool

search(regexp: str, ignoreCase: bool = False) → Match[str] | None[source]🌶️

Return the re.match of the regexp

Parameters:

regexp (str) – the regular expression to be matched
ignoreCase (bool) – Ignore case, defaults to False

Returns:

first regular-expression match or None

Return type:

re.Match | None

setCharAt(pos: int, char: str) → TTkString[source]🌶️

Return a copy with one character replaced.

Parameters:

pos (int) – character index to replace
char (str) – replacement character

Returns:

updated string

Return type:

TTkString

Raises:

IndexError – if pos is out of range

setColor(color: TTkColor, match: str | None = None, posFrom: int | None = None, posTo: int | None = None) → TTkString[source]🌶️

Set the color of the entire string or a slice of it

If only the color is specified, the entire string is colorized

Parameters:

color (TTkColor) – the color to be used, defaults to TTkColor.RST
match (str, optional) – the match to colorize
posFrom (int, optional) – the initial position of the color
posTo (int, optional) – the final position of the color

Returns:

recolored string

Return type:

TTkString

setColorAt(pos: int, color: TTkColor) → TTkString[source]🌶️

Return a copy with one character color replaced.

Parameters:

pos (int) – character index to recolor
color (TTkColor) – replacement color

Returns:

recolored string

Return type:

TTkString

Raises:

IndexError – if pos is out of range

split(separator: str) → list[TTkString][source]🌶️

Split the string using a separator

Note

Only a one char separator is currently supported

Parameters:: separator (str) – the “char” separator to be used
Returns:: list of split chunks
Return type:: list[TTkString]

substring(fr: int | None = None, to: int | None = None) → TTkString[source]🌶️

Return the substring

Parameters:

fr (int, optional) – the starting of the slice, defaults to 0
to (int, optional) – the ending of the slice, defaults to the end of the string

Returns:

sliced string

Return type:

TTkString

tab2spaces(tabSpaces: int = 4) → TTkString[source]🌶️

Expand tab characters into aligned spaces.

Parameters:: tabSpaces (int) – tab stop size
Returns:: string with tabs replaced by spaces
Return type:: TTkString

tabCharPos(pos: int, tabSpaces: int = 4, alignTabRight: bool = False) → int[source]🌶️

Map a rendered column position to the internal character index.

Tabs and variable-width characters are resolved against the visual terminal representation.

Parameters:

pos (int) – target visual column
tabSpaces (int) – tab stop size
alignTabRight (bool) – map positions inside a tab to the tab right edge

Returns:

character index in _text

Return type:

int

i.e.

pos                   X = 11
tab2Spaces |----------|---------------------|
Tabs             |-|  |  |-|     |-|   |
_text      L😁rem   ipsum   dolor   sit amet,
chars      .. ...t  .....t  .....t  ...t.....
ret                   x = 7 (tab is a char)

termWidth() → int[source]🌶️

Return the rendered terminal width of this string.

Returns:: rendered width accounting for tabs and wide/combining chars
Return type:: int

toAnsi(strip: bool = False) → str[source]🌶️

Return the ANSI escaped representation of the string.

Parameters:: strip (bool) – remove leading/trailing reset sequences
Returns:: ANSI escaped text
Return type:: str

toAscii() → str[source]🌶️

Return the plain-text content.

Returns:: raw text without terminal escapes
Return type:: str

TTkString Attributes🌶️

`mnemonicColor`
`unicodeWideOverflowColor`

TTkString

Contents

TTkString🌶️

Methods🌶️

TTkString Attributes🌶️