euporie.core.ft.utils

Utilitie for manipulating formatted text.

Functions

`add_border`(ft[, width, style, border_grid, ...])	Add a border around formatted text.
`align`(ft[, how, width, style, placeholder, ...])	Align formatted text at a given width.
`apply_reverse_overwrites`(ft)	Write fragments tagged with "[ReverseOverwrite]" over text to their left.
`apply_style`(ft, style)	Apply a style to formatted text.
`cast`(typ, val)	Cast a value to a type.
`concat`(ft_a, ft_b[, baseline_a, baseline_b, ...])	Concatenate two blocks of formatted text, aligning at a given baseline.
`explode_text_fragments`(fragments)	Turn a list of (style_str, text) tuples into another list where each string is exactly one character.
`fragment_list_to_text`(fragments)	Concatenate all the text parts again.
`fragment_list_to_words`(fragments[, sep])	Split formatted text into a list of word fragments which form words.
`fragment_list_width`(fragments)	Return the character width of this text fragment list.
`get_cwidth`(string)	Return width of a string.
`get_lexer_by_name`(_alias, **options)	Return an instance of a Lexer subclass that has alias in its aliases list.
`indent`(ft[, margin, style, skip_first])	Indent formatted text with a given margin.
`join_lines`(fragments)	Join a list of lines of formatted text.
`last_char`(ft)	Retrieve the last character of formatted text.
`last_line_length`(ft[, rows])	Calculate the length of the last line in formatted text.
`lex`(ft, lexer_name)	Format formatted text using a named `pygments` lexer.
`max_line_width`(ft)	Calculate the length of the longest line in formatted text.
`pad`(ft[, width, char, style])	Fill space at the end of lines.
`paste`(ft_top, ft_bottom[, row, col, transparent])	Pate formatted text on top of other formatted text.
`split_lines`(fragments)	Take a single list of (style_str, text) tuples and yield one such list for each line.
`strip`(ft[, left, right, chars, only_unstyled])	Strip whitespace (or a given character) from the ends of formatted text.
`strip_one_trailing_newline`(ft)	Remove up to one trailing new-line character from formatted text.
`substring`(ft[, start, end])	Extract a substring from formatted text.
`to_plain_text`(value)	Turn any kind of formatted text back into plain text.
`truncate`(ft, width[, style, placeholder, ...])	Truncate all lines at a given length.
`valign`(ft[, how, height, style])	Align formatted text vertically.
`wrap`(ft, width[, style, placeholder, left, ...])	Wrap formatted text at a given width.

Classes

`DiBool`([top, right, bottom, left])	A tuple of four bools with directions.
`DiInt`([top, right, bottom, left])	A tuple of four integers with directions.
`DiStr`([top, right, bottom, left])	A tuple of four strings with directions.
`Enum`(value[, names, module, qualname, type, ...])	Create a collection of name/value pairs.
`FormattedTextAlign`(value[, names, module, ...])	Alignment of formatted text.
`FormattedTextVerticalAlign`(value[, names, ...])	Vertical alignment of formatted text.
`GridStyle`(line_style, mask)	A collection of characters which can be used to draw a grid.

Exceptions

ClassNotFound

Raised if one of the lookup functions didn't find a matching class.

class euporie.core.ft.utils.FormattedTextAlign(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.Enum

Alignment of formatted text.

CENTER = 'center'

LEFT = 'left'

RIGHT = 'right'

class euporie.core.ft.utils.FormattedTextVerticalAlign(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.Enum

Vertical alignment of formatted text.

BOTTOM = 'bottom'

MIDDLE = 'middle'

TOP = 'top'

euporie.core.ft.utils.add_border(ft: StyleAndTextTuples, width: int | None = None, style: str = '', border_grid: GridStyle = ┌─┬┐ │ ││ ├─┼┤ └─┴┘, border_visibility: DiBool | bool = True, border_style: DiStr | str = '', padding: DiInt | int = 0, padding_style: DiStr | str = '') → StyleAndTextTuples

Add a border around formatted text.

Parameters

ft – The formatted text to enclose with a border
width – The target width including the border and padding
style – The style to apply to the content background
border_grid – The grid style to use for the border
border_visibility – Determines which edges should receive a border
border_style – The style to apply to the border
padding – The width of spacing to apply between the content and the border
padding_style – The style to apply to the border

Returns

The indented formatted text

euporie.core.ft.utils.align(ft: StyleAndTextTuples, how: FormattedTextAlign = FormattedTextAlign.LEFT, width: int | None = None, style: str = '', placeholder: str = '…', ignore_whitespace: bool = False) → StyleAndTextTuples

Align formatted text at a given width.

Parameters

how – The alignment direction
ft – The formatted text to strip
width – The width to which the output should be padded. If None, the length of the longest line is used
style – The style to apply to the padding
placeholder – The string that will appear at the end of a truncated line
ignore_whitespace – If True, whitespace will be ignored

Returns

The aligned formatted text

euporie.core.ft.utils.apply_reverse_overwrites(ft: StyleAndTextTuples) → StyleAndTextTuples: Write fragments tagged with “[ReverseOverwrite]” over text to their left.

euporie.core.ft.utils.apply_style(ft: StyleAndTextTuples, style: str) → StyleAndTextTuples: Apply a style to formatted text.

euporie.core.ft.utils.concat(ft_a: StyleAndTextTuples, ft_b: StyleAndTextTuples, baseline_a: int = 0, baseline_b: int = 0, style: str = '') → tuple[StyleAndTextTuples, int]

Concatenate two blocks of formatted text, aligning at a given baseline.

Parameters

ft_a – The first block of formatted text to combine
ft_b – The second block of formatted text to combine
baseline_a – The row to use to align the first block of formatted text with the second, counted in lines down from the top of the block
baseline_b – The row to use to align the second block of formatted text with the second, counted in lines down from the top of the block
style – The style to use for any extra lines added

Returns

A tuple containing the combined formatted text and the new baseline position

euporie.core.ft.utils.fragment_list_to_words(fragments: StyleAndTextTuples, sep: str = ' ') → Iterable[StyleAndTextTuples]: Split formatted text into a list of word fragments which form words.

euporie.core.ft.utils.fragment_list_width(fragments: StyleAndTextTuples) → int

Return the character width of this text fragment list.

Takes double width characters into account, and ignore special fragments: * ZeroWidthEscape * ReverseOverwrite

Parameters: fragments – List of (style_str, text) or (style_str, text, mouse_handler) tuples.
Returns: The width of the fragment list

euporie.core.ft.utils.indent(ft: StyleAndTextTuples, margin: str = ' ', style: str = '', skip_first: bool = False) → StyleAndTextTuples

Indent formatted text with a given margin.

Parameters

ft – The formatted text to strip
margin – The margin string to add
style – The style to apply to the margin
skip_first – If True, the first line is skipped

Returns

The indented formatted text

euporie.core.ft.utils.join_lines(fragments: list[StyleAndTextTuples]) → StyleAndTextTuples: Join a list of lines of formatted text.

euporie.core.ft.utils.last_char(ft: StyleAndTextTuples) → str | None: Retrieve the last character of formatted text.

euporie.core.ft.utils.last_line_length(ft: StyleAndTextTuples, rows: int = 1) → int: Calculate the length of the last line in formatted text.

euporie.core.ft.utils.lex(ft: StyleAndTextTuples, lexer_name: str) → StyleAndTextTuples: Format formatted text using a named pygments lexer.

euporie.core.ft.utils.max_line_width(ft: StyleAndTextTuples) → int: Calculate the length of the longest line in formatted text.

euporie.core.ft.utils.pad(ft: StyleAndTextTuples, width: int | None = None, char: str = ' ', style: str = '') → StyleAndTextTuples: Fill space at the end of lines.

euporie.core.ft.utils.paste(ft_top: StyleAndTextTuples, ft_bottom: StyleAndTextTuples, row: int = 0, col: int = 0, transparent: bool = False) → StyleAndTextTuples: Pate formatted text on top of other formatted text.

euporie.core.ft.utils.strip(ft: StyleAndTextTuples, left: bool = True, right: bool = True, chars: str | None = None, only_unstyled: bool = False) → StyleAndTextTuples

Strip whitespace (or a given character) from the ends of formatted text.

Parameters

ft – The formatted text to strip
left – If True, strip from the left side of the input
right – If True, strip from the right side of the input
chars – The character to strip. If None, strips whitespace
only_unstyled – If True, only strip unstyled fragments

Returns

The stripped formatted text

euporie.core.ft.utils.strip_one_trailing_newline(ft: StyleAndTextTuples) → StyleAndTextTuples: Remove up to one trailing new-line character from formatted text.

euporie.core.ft.utils.substring(ft: StyleAndTextTuples, start: int | None = None, end: int | None = None) → StyleAndTextTuples: Extract a substring from formatted text.

euporie.core.ft.utils.truncate(ft: StyleAndTextTuples, width: int, style: str = '', placeholder: str = '…', ignore_whitespace: bool = False) → StyleAndTextTuples

Truncate all lines at a given length.

Parameters

ft – The formatted text to truncate
width – The width at which to truncate the text
style – The style to apply to the truncation placeholder. The style of the truncated text will be used if not provided
placeholder – The string that will appear at the end of a truncated line
ignore_whitespace – Do not use placeholder when truncating whitespace

Returns

The truncated formatted text

euporie.core.ft.utils.valign(ft: StyleAndTextTuples, how: FormattedTextVerticalAlign = FormattedTextVerticalAlign.MIDDLE, height: int | None = None, style: str = '') → StyleAndTextTuples: Align formatted text vertically.

euporie.core.ft.utils.wrap(ft: StyleAndTextTuples, width: int, style: str = '', placeholder: str = '…', left: int = 0, truncate_long_words: bool = True, strip_trailing_ws: bool = False) → StyleAndTextTuples

Wrap formatted text at a given width.

If words are longer than the given line they will be truncated

Parameters

ft – The formatted text to wrap
width – The width at which to wrap the text
style – The style to apply to the truncation placeholder
placeholder – The string that will appear at the end of a truncated line
left – The starting position within the first line
truncate_long_words – If True words longer than a line will be truncated
strip_trailing_ws – If True, trailing whitespace will be removed from the ends of lines

Returns

The wrapped formatted text