rich.text

class rich.text.Text(text: str = '', style: Union[str, rich.style.Style] = '', *, justify: JustifyMethod = None, overflow: OverflowMethod = None, no_wrap: bool = None, end: str = '\n', tab_size: Optional[int] = 8, spans: List[rich.text.Span] = None)[source]

Text with color / style.

Parameters
  • text (str, optional) – Default unstyled text. Defaults to “”.

  • style (Union[str, Style], optional) – Base style for text. Defaults to “”.

  • justify (str, optional) – Justify method: “left”, “center”, “full”, “right”. Defaults to None.

  • overflow (str, optional) – Overflow method: “crop”, “fold”, “ellipsis”. Defaults to None.

  • no_wrap (bool, optional) – Disable text wrapping, or None for default. Defaults to None.

  • end (str, optional) – Character to end text with. Defaults to “n”.

  • tab_size (int) – Number of spaces per tab, or None to use console.tab_size. Defaults to 8.

  • spans (List[Span], optional) –

align(align: typing_extensions.Literal[left, center, right], width: int, character: str = ' ') → None[source]

Align text to a given width.

Parameters
  • align (AlignValues) – One of “left”, “center”, or “right”.

  • width (int) – Desired width.

  • character (str, optional) – Character to pad with. Defaults to ” “.

append(text: Union[Text, str], style: Union[str, Style] = None)rich.text.Text[source]

Add text with an optional style.

Parameters
  • text (Union[Text, str]) – A str or Text to append.

  • style (str, optional) – A style name. Defaults to None.

Returns

Returns self for chaining.

Return type

Text

append_text(text: rich.text.Text)rich.text.Text[source]

Append another Text instance. This method is more performant that Text.append, but only works for Text.

Returns

Returns self for chaining.

Return type

Text

append_tokens(tokens: Iterable[Tuple[str, Union[str, Style]]])[source]

Append iterable of str and style. Style may be a Style instance or a str style definition.

Parameters

pairs (Iterable[Tuple[str, StyleType]]) – An iterable of tuples containing str content and style.

Returns

Returns self for chaining.

Return type

Text

classmethod assemble(*parts: Union[str, Text, Tuple[str, Union[str, Style]]], style: Union[str, rich.style.Style] = '', justify: JustifyMethod = None, overflow: OverflowMethod = None, no_wrap: bool = None, end: str = '\n', tab_size: int = 8)Text[source]

Construct a text instance by combining a sequence of strings with optional styles. The positional arguments should be either strings, or a tuple of string + style.

Parameters
  • style (Union[str, Style], optional) – Base style for text. Defaults to “”.

  • justify (str, optional) – Justify method: “left”, “center”, “full”, “right”. Defaults to None.

  • overflow (str, optional) – Overflow method: “crop”, “fold”, “ellipsis”. Defaults to None.

  • end (str, optional) – Character to end text with. Defaults to “n”.

  • tab_size (int) – Number of spaces per tab, or None to use console.tab_size. Defaults to 8.

Returns

A new text instance.

Return type

Text

blank_copy()rich.text.Text[source]

Return a new Text instance with copied meta data (but not the string or spans).

property cell_len

Get the number of cells required to render this text.

copy()rich.text.Text[source]

Return a copy of this instance.

copy_styles(text: rich.text.Text) → None[source]

Copy styles from another Text instance.

Parameters

text (Text) – A Text instance to copy styles from, must be the same length.

divide(offsets: Iterable[int]) → rich.containers.Lines[source]

Divide text in to a number of lines at given offsets.

Parameters

offsets (Iterable[int]) – Offsets used to divide text.

Returns

New RichText instances between offsets.

Return type

Lines

expand_tabs(tab_size: int = None) → None[source]

Converts tabs to spaces.

Parameters

tab_size (int, optional) – Size of tabs. Defaults to 8.

fit(width: int) → rich.containers.Lines[source]

Fit the text in to given width by chopping in to lines.

Parameters

width (int) – Maximum characters in a line.

Returns

List of lines.

Return type

Lines

classmethod from_markup(text: str, *, style: Union[str, rich.style.Style] = '', emoji: bool = True, justify: JustifyMethod = None, overflow: OverflowMethod = None)Text[source]

Create Text instance from markup.

Parameters
  • text (str) – A string containing console markup.

  • emoji (bool, optional) – Also render emoji code. Defaults to True.

  • justify (str, optional) – Justify method: “left”, “center”, “full”, “right”. Defaults to None.

  • overflow (str, optional) – Overflow method: “crop”, “fold”, “ellipsis”. Defaults to None.

Returns

A Text instance with markup rendered.

Return type

Text

get_style_at_offset(console: Console, offset: int)rich.style.Style[source]

Get the style of a character at give offset.

Parameters
  • console (~Console) – Console where text will be rendered.

  • offset (int) – Offset in to text (negative indexing supported)

Returns

A Style instance.

Return type

Style

highlight_regex(re_highlight: str, style: Union[Callable[[str], Optional[Union[str, Style]]], str, Style] = None, *, style_prefix: str = '') → int[source]

Highlight text with a regular expression, where group names are translated to styles.

Parameters
  • re_highlight (str) – A regular expression.

  • style (Union[GetStyleCallable, StyleType]) – Optional style to apply to whole match, or a callable which accepts the matched text and returns a style. Defaults to None.

  • style_prefix (str, optional) – Optional prefix to add to style group names.

Returns

Number of regex matches

Return type

int

highlight_words(words: Iterable[str], style: Union[str, rich.style.Style], *, case_sensitive: bool = True) → int[source]

Highlight words with a style.

Parameters
  • words (Iterable[str]) – Worlds to highlight.

  • style (Union[str, Style]) – Style to apply.

  • case_sensitive (bool, optional) – Enable case sensitive matchings. Defaults to True.

Returns

Number of words highlighted.

Return type

int

join(lines: Iterable[Text])rich.text.Text[source]

Join text together with this instance as the separator.

Parameters

lines (Iterable[Text]) – An iterable of Text instances to join.

Returns

A new text instance containing join text.

Return type

Text

pad(count: int, character: str = ' ') → None[source]

Pad left and right with a given number of characters.

Parameters

count (int) – Width of padding.

pad_left(count: int, character: str = ' ') → None[source]

Pad the left with a given character.

Parameters
  • count (int) – Number of characters to pad.

  • character (str, optional) – Character to pad with. Defaults to ” “.

pad_right(count: int, character: str = ' ') → None[source]

Pad the right with a given character.

Parameters
  • count (int) – Number of characters to pad.

  • character (str, optional) – Character to pad with. Defaults to ” “.

property plain

Get the text as a single string.

remove_suffix(suffix: str) → None[source]

Remove a suffix if it exists.

Parameters

suffix (str) – Suffix to remove.

render(console: Console, end: str = '') → Iterable[Segment][source]

Render the text as Segments.

Parameters
  • console (Console) – Console instance.

  • end (Optional[str], optional) – Optional end character.

Returns

Result of render that may be written to the console.

Return type

Iterable[Segment]

right_crop(amount: int = 1) → None[source]

Remove a number of characters from the end of the text.

rstrip() → None[source]

Strip whitespace from end of text.

rstrip_end(size: int) → None[source]

Remove whitespace beyond a certain width at the end of the text.

Parameters

size (int) – The desired size of the text.

set_length(new_length: int) → None[source]

Set new length of the text, clipping or padding is required.

property spans

Get a reference to the internal list of spans.

split(separator='\n', *, include_separator: bool = False, allow_blank: bool = False) → rich.containers.Lines[source]

Split rich text in to lines, preserving styles.

Parameters
  • separator (str, optional) – String to split on. Defaults to “n”.

  • include_separator (bool, optional) – Include the separator in the lines. Defaults to False.

  • allow_blank (bool, optional) – Return a blank line if the text ends with a separator. Defaults to False.

Returns

A list of rich text, one per line of the original.

Return type

List[RichText]

classmethod styled(text: str, style: Union[str, Style] = '', *, justify: JustifyMethod = None, overflow: OverflowMethod = None)Text[source]

Construct a Text instance with a pre-applied styled. A style applied in this way won’t be used to pad the text when it is justified.

Parameters
  • text (str) – A string containing console markup.

  • style (Union[str, Style]) – Style to apply to the text. Defaults to “”.

  • justify (str, optional) – Justify method: “left”, “center”, “full”, “right”. Defaults to None.

  • overflow (str, optional) – Overflow method: “crop”, “fold”, “ellipsis”. Defaults to None.

Returns

A text instance with a style applied to the entire string.

Return type

Text

stylize(style: Union[str, rich.style.Style], start: int = 0, end: Optional[int] = None) → None[source]

Apply a style to the text, or a portion of the text.

Parameters
  • style (Union[str, Style]) – Style instance or style definition to apply.

  • start (int) – Start offset (negative indexing is supported). Defaults to 0.

  • end (Optional[int], optional) – End offset (negative indexing is supported), or None for end of text. Defaults to None.

truncate(max_width: int, *, overflow: Optional[OverflowMethod] = None, pad: bool = False) → None[source]

Truncate text if it is longer that a given width.

Parameters
  • max_width (int) – Maximum number of characters in text.

  • overflow (str, optional) – Overflow method: “crop”, “fold”, or “ellipsis”. Defaults to None, to use self.overflow.

  • pad (bool, optional) – Pad with spaces if the length is less than max_width. Defaults to False.

wrap(console: Console, width: int, *, justify: JustifyMethod = None, overflow: OverflowMethod = None, tab_size: int = 8, no_wrap: bool = None) → rich.containers.Lines[source]

Word wrap the text.

Parameters
  • console (Console) – Console instance.

  • width (int) – Number of characters per line.

  • emoji (bool, optional) – Also render emoji code. Defaults to True.

  • justify (str, optional) – Justify method: “default”, “left”, “center”, “full”, “right”. Defaults to “default”.

  • overflow (str, optional) – Overflow method: “crop”, “fold”, or “ellipsis”. Defaults to None.

  • tab_size (int, optional) – Default tab size. Defaults to 8.

  • no_wrap (bool, optional) – Disable wrapping, Defaults to False.

Returns

Number of lines.

Return type

Lines