span

Module introducing Span abstractions. The key difference beetween them and Sequences is that sequence can open text style and also close, or terminate it. As for Spans – they always do both; typical use-case of Span is to wrap some text in opening SGR and closing one.

Name of any format preset in this module can be used as a string argument in build() and autocomplete() methods:

autocomplete('red', 'bold')
class pytermor.span.Span(opening_seq: Optional[SequenceSGR] = None, closing_seq: Optional[SequenceSGR] = None, hard_reset_after: bool = False)

Wrapper class that contains starter, or opening sequence and (optionally) closing sequence.

Note that closing_seq gets overwritten with sequence.RESET if hard_reset_after is True.

Parameters

  • opening_seq – Starter sequence, in general determening how Span will actually look like.

  • closing_seq – Finisher SGR sequence.

  • hard_reset_after – Set closing_seq to a hard reset sequence.

wrap(text: Optional[Any] = None) → str

Wrap given text with Span’s SGRs – opening_seq to the left, closing_seq to the right. str(text) will be invoked for all argument types with the exception of None, which will be replaced with empty string.

Parameters

text – String to wrap.

Returns

Resulting string; input argument enclosed to Span’s SGRs, if any.

property opening_str: str

Return opening SGR sequence encoded.

property opening_seq: SequenceSGR

Return opening SGR sequence instance.

property closing_str: str

Return closing SGR sequence encoded.

property closing_seq: SequenceSGR

Return closing SGR sequence instance.

pytermor.span.autocomplete(*args: str | int | SequenceSGR) → Span

Create new Span with specified control sequence(s) as an opening sequence and automatically compose closing sequence that will terminate attributes defined in the first one while keeping the others (soft reset).

Resulting sequence param order is same as an argument order.

Each sequence param can be specified as:

  • string key (see span)

  • integer param value (see intcode)

  • existing SequenceSGR instance (params will be extracted).

pytermor.span.noop = Span[SGR[], SGR[]]

Special Span in cases where you have to select one or another Span, but do not want anything to be actually printed.

  • noop(string) or noop.wrap(string) returns string without any modifications;

  • noop.opening_str and noop.closing_str are empty strings;

  • noop.opening_seq and noop.closing_seq both returns sequence.NOOP.

pytermor.span.bold = Span[SGR[1], SGR[22]]
pytermor.span.dim = Span[SGR[2], SGR[22]]
pytermor.span.italic = Span[SGR[3], SGR[23]]
pytermor.span.underlined = Span[SGR[4], SGR[24]]
pytermor.span.inversed = Span[SGR[7], SGR[27]]
pytermor.span.overlined = Span[SGR[53], SGR[55]]
pytermor.span.red = Span[SGR[31], SGR[39]]
pytermor.span.green = Span[SGR[32], SGR[39]]
pytermor.span.yellow = Span[SGR[33], SGR[39]]
pytermor.span.blue = Span[SGR[34], SGR[39]]
pytermor.span.magenta = Span[SGR[35], SGR[39]]
pytermor.span.cyan = Span[SGR[36], SGR[39]]
pytermor.span.gray = Span[SGR[90], SGR[39]]
pytermor.span.bg_black = Span[SGR[40], SGR[49]]
pytermor.span.bg_red = Span[SGR[41], SGR[49]]
pytermor.span.bg_green = Span[SGR[42], SGR[49]]
pytermor.span.bg_yellow = Span[SGR[43], SGR[49]]
pytermor.span.bg_blue = Span[SGR[44], SGR[49]]
pytermor.span.bg_magenta = Span[SGR[45], SGR[49]]
pytermor.span.bg_cyan = Span[SGR[46], SGR[49]]
pytermor.span.bg_gray = Span[SGR[100], SGR[49]]