rich.segment

class rich.segment.ControlType(*values)[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

control: Sequence[Tuple[ControlType] | Tuple[ControlType, int | str] | Tuple[ControlType, int, int]] | None

Alias for field number 2

classmethod divide(segments, cuts)[source]

Divides an iterable of segments in to portions.

Parameters:
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.

Parameters:

cut (int) – Offset within the segment to cut.

Returns:

Two segments.

Return type:

Tuple[Segment, Segment]

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]

style: Style | None

Alias for field number 1

text: str

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.