rich.segment

class rich.segment.ControlType(value)[source]

Non-printable control codes which typically translate to ANSI codes.

class rich.segment.Segment(text, style=None, control=None)[source]

A piece of text with associated style. Segments are produced by the Console render process and are ultimately converted in to strings to be written to the terminal.

Parameters

  • text (str) – A piece of text.

  • style (Style, optional) – An optional style to apply to the text.

  • control (Tuple[ControlCode], optional) – Optional sequence of control codes.

cell_length

The cell length of this Segment.

Type

int

classmethod adjust_line_length(line, length, style=None, pad=True)[source]

Adjust a line to a given width (cropping or padding as required).

Parameters

  • segments (Iterable[Segment]) – A list of segments in a single line.

  • length (int) – The desired width of the line.

  • style (Style, optional) – The style of padding if used (space on the end). Defaults to None.

  • pad (bool, optional) – Pad lines with spaces if they are shorter than length. Defaults to True.

  • line (List[Segment]) –

Returns

A line of segments with the desired length.

Return type

List[Segment]

classmethod align_bottom(lines, width, height, style, new_lines=False)[source]

Aligns render to bottom (adds extra lines above as required).

Args:

lines (List[List[Segment]]): A list of lines. width (int): Desired width. height (int, optional): Desired height or None for no change. style (Style): Style of any padding added. Defaults to None. new_lines (bool, optional): Padded lines should include “

“. Defaults to False.

Returns:

List[List[Segment]]: New list of lines.

Parameters
Return type

List[List[Segment]]

classmethod align_middle(lines, width, height, style, new_lines=False)[source]

Aligns lines to middle (adds extra lines to above and below as required).

Args:

lines (List[List[Segment]]): A list of lines. width (int): Desired width. height (int, optional): Desired height or None for no change. style (Style): Style of any padding added. new_lines (bool, optional): Padded lines should include “

“. Defaults to False.

Returns:

List[List[Segment]]: New list of lines.

Parameters
Return type

List[List[Segment]]

classmethod align_top(lines, width, height, style, new_lines=False)[source]

Aligns lines to top (adds extra lines to bottom as required).

Args:

lines (List[List[Segment]]): A list of lines. width (int): Desired width. height (int, optional): Desired height or None for no change. style (Style): Style of any padding added. new_lines (bool, optional): Padded lines should include “

“. Defaults to False.

Returns:

List[List[Segment]]: New list of lines.

Parameters
Return type

List[List[Segment]]

classmethod apply_style(segments, style=None, post_style=None)[source]

Apply style(s) to an iterable of segments.

Returns an iterable of segments where the style is replaced by style + segment.style + post_style.

Parameters

  • segments (Iterable[Segment]) – Segments to process.

  • style (Style, optional) – Base style. Defaults to None.

  • post_style (Style, optional) – Style to apply on top of segment style. Defaults to None.

Returns

A new iterable of segments (possibly the same iterable).

Return type

Iterable[Segments]

property cell_length: int

The number of terminal cells required to display self.text.

Returns

A number of cells.

Return type

int

property control

Alias for field number 2

classmethod divide(segments, cuts)[source]

Divides an iterable of segments in to portions.

Parameters

  • cuts (Iterable[int]) – Cell positions where to divide.

  • segments (Iterable[Segment]) –

Yields

[Iterable[List[Segment]]] – An iterable of Segments in List.

Return type

Iterable[List[Segment]]

classmethod filter_control(segments, is_control=False)[source]

Filter segments by is_control attribute.

Parameters

  • segments (Iterable[Segment]) – An iterable of Segment instances.

  • is_control (bool, optional) – is_control flag to match in search.

Returns

And iterable of Segment instances.

Return type

Iterable[Segment]

classmethod get_line_length(line)[source]

Get the length of list of segments.

Parameters

line (List[Segment]) – A line encoded as a list of Segments (assumes no ‘\n’ characters),

Returns

The length of the line.

Return type

int

classmethod get_shape(lines)[source]

Get the shape (enclosing rectangle) of a list of lines.

Parameters

lines (List[List[Segment]]) – A list of lines (no ‘\n’ characters).

Returns

Width and height in characters.

Return type

Tuple[int, int]

property is_control: bool

Check if the segment contains control codes.

classmethod line()[source]

Make a new line segment.

Return type

Segment

classmethod remove_color(segments)[source]

Remove all color from an iterable of segments.

Parameters

segments (Iterable[Segment]) – An iterable segments.

Yields

Segment – Segments with colorless style.

Return type

Iterable[Segment]

classmethod set_shape(lines, width, height=None, style=None, new_lines=False)[source]

Set the shape of a list of lines (enclosing rectangle).

Args:

lines (List[List[Segment]]): A list of lines. width (int): Desired width. height (int, optional): Desired height or None for no change. style (Style, optional): Style of any padding added. new_lines (bool, optional): Padded lines should include “

“. Defaults to False.

Returns:

List[List[Segment]]: New list of lines.

Parameters
Return type

List[List[Segment]]

classmethod simplify(segments)[source]

Simplify an iterable of segments by combining contiguous segments with the same style.

Parameters

segments (Iterable[Segment]) – An iterable of segments.

Returns

A possibly smaller iterable of segments that will render the same way.

Return type

Iterable[Segment]

classmethod split_and_crop_lines(segments, length, style=None, pad=True, include_new_lines=True)[source]

Split segments in to lines, and crop lines greater than a given length.

Parameters

  • segments (Iterable[Segment]) – An iterable of segments, probably generated from console.render.

  • length (int) – Desired line length.

  • style (Style, optional) – Style to use for any padding.

  • pad (bool) – Enable padding of lines that are less than length.

  • include_new_lines (bool) –

Returns

An iterable of lines of segments.

Return type

Iterable[List[Segment]]

split_cells(cut)[source]

Split segment in to two segments at the specified column.

If the cut point falls in the middle of a 2-cell wide character then it is replaced by two spaces, to preserve the display width of the parent segment.

Returns

Two segments.

Return type

Tuple[Segment, Segment]

Parameters

cut (int) –

classmethod split_lines(segments)[source]

Split a sequence of segments in to a list of lines.

Parameters

segments (Iterable[Segment]) – Segments potentially containing line feeds.

Yields

Iterable[List[Segment]] – Iterable of segment lists, one per line.

Return type

Iterable[List[Segment]]

Remove all links from an iterable of styles.

Parameters

segments (Iterable[Segment]) – An iterable segments.

Yields

Segment – Segments with link removed.

Return type

Iterable[Segment]

classmethod strip_styles(segments)[source]

Remove all styles from an iterable of segments.

Parameters

segments (Iterable[Segment]) – An iterable segments.

Yields

Segment – Segments with styles replace with None

Return type

Iterable[Segment]

property style

Alias for field number 1

property text

Alias for field number 0

class rich.segment.Segments(segments, new_lines=False)[source]

A simple renderable to render an iterable of segments. This class may be useful if you want to print segments outside of a __rich_console__ method.

Parameters

  • segments (Iterable[Segment]) – An iterable of segments.

  • new_lines (bool, optional) – Add new lines between segments. Defaults to False.