sequences.py

Module providing ‘sequence awareness’.

class Sequence(sequence_text: str, term: Terminal)[source]

A “sequence-aware” version of the base str class.

This unicode-derived class understands the effect of escape sequences of printable length, allowing a properly implemented rjust(), ljust(), center(), and length().

Note

that other than Sequence.padd(), this is just a thin layer over wcwidth, kept by name for API compatibility.

Class constructor.

Parameters:

sequence_text (str) – A string that may contain sequences.
term (blessed.Terminal) – Terminal instance.

ljust(width: SupportsIndex, fillchar: str = ' ') → str[source]

Return string containing sequences, left-adjusted.

Parameters:

width (int) – Total width given to left-adjust text.
fillchar (str) – String for padding right-of text.

Returns:

String of text, left-aligned by width.

Return type:

str

rjust(width: SupportsIndex, fillchar: str = ' ') → str[source]

Return string containing sequences, right-adjusted.

Parameters:

width (int) – Total width given to right-adjust text.
fillchar (str) – String for padding left-of text.

Returns:

String of text, right-aligned by width.

Return type:

str

center(width: SupportsIndex, fillchar: str = ' ') → str[source]

Return string containing sequences, centered.

Parameters:

width (int) – Total width given to center text.
fillchar (str) – String for padding left and right-of text.

Returns:

String of text, centered by width.

Return type:

str

truncate(width: SupportsIndex) → str[source]

Truncate a string in a sequence-aware manner.

Any printable characters beyond width are removed, while all sequences remain in place. Horizontal sequences are first expanded by padd().

Wide characters (such as CJK or emoji) that would partially exceed width are replaced with space padding to maintain exact width.

SGR (terminal styling) sequences are propagated: the result begins with any active style at the start position and ends with a reset sequence if styles were active.

Parameters:: width (int) – The printable width to truncate the string to.
Return type:: str
Returns:: String truncated to exactly width printable characters.

length() → int[source]

Return the printable length of string containing sequences.

Returns the maximum horizontal cursor extent reached while processing the string. Backspace and cursor-left movements do not reduce the length below the maximum position reached.

Some characters may consume more than one cell, mainly CJK (Chinese, Japanese, Korean) and Emojis and some kinds of symbols.

For example:

>>> from blessed import Terminal
>>> from blessed.sequences import Sequence
>>> term = Terminal()
>>> msg = term.clear + term.red('コンニチハ')
>>> Sequence(msg, term).length()
10

Note

Although accounted for, strings containing sequences such as term.clear will not give accurate returns, it is not considered lengthy (a length of 0).

strip(chars: str | None = None) → str[source]

Return string of sequences, leading and trailing whitespace removed.

Parameters:: chars (str) – Remove characters in chars instead of whitespace.
Return type:: str
Returns:: string of sequences with leading and trailing whitespace removed.

lstrip(chars: str | None = None) → str[source]

Return string of all sequences and leading whitespace removed.

Parameters:: chars (str) – Remove characters in chars instead of whitespace.
Return type:: str
Returns:: string of sequences with leading removed.

rstrip(chars: str | None = None) → str[source]

Return string of all sequences and trailing whitespace removed.

Parameters:: chars (str) – Remove characters in chars instead of whitespace.
Return type:: str
Returns:: string of sequences with trailing removed.

strip_seqs() → str[source]

Return text stripped of only its terminal sequences.

Return type:: str
Returns:: Text with terminal sequences removed

padd(strip: bool = False) → str[source]

Return non-destructive horizontal movement as destructive spacing.

Parameters:: strip (bool) – Strip terminal sequences
Return type:: str
Returns:: Text adjusted for horizontal movement

iter_parse(term: Terminal, text: str) → Iterator[Tuple[str, Termcap | None]][source]

Generator yields (text, capability) for characters of text.

value for capability may be None, where text is str of length 1. Otherwise, text is a full matching sequence of given capability.

Note

Previously used by SequenceTextWrapper, sequence-aware text wrapping now exists in wcwidth as wcwidth.wrap(). This function is kept for API compatibility and used by measure_length().

measure_length(text: str, term: Terminal) → int[source]

Kept for API compatibility.

Return type:: int
Returns:: Length of the first sequence in the string

Deprecated since version 1.30.0.