Core functions and classes

Functions

pytermor.build(*args: str | int | SequenceSGR) → SequenceSGR

Create new SequenceSGR with specified args as params.

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.color_indexed(color: int, bg: bool = False) → SequenceSGR

Wrapper for creation of SequenceSGR that sets foreground (or background) to one of 256-color pallete value.

Parameters

  • color – Index of the color in the pallete, 0 – 255.

  • bg – Set to true to change the background color (default is foreground).

Returns

SequenceSGR with required params.

pytermor.color_rgb(r: int, g: int, b: int, bg: bool = False) → SequenceSGR

Wrapper for creation of SequenceSGR operating in True Color mode (16M). Valid values for r, g and b are in range [0; 255]. This range linearly translates into [0x00; 0xFF] for each channel. The result value is composed as #RRGGBB. For example, sequence with color of #FF3300 can be created with:

color_rgb(255, 51, 0)
Parameters

  • r – Red channel value, 0 – 255.

  • g – Blue channel value, 0 – 255.

  • b – Green channel value, 0 – 255.

  • bg – Set to true to change the background color (default is foreground).

Returns

SequenceSGR with required params.

pytermor.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).

Classes

class pytermor.SequenceSGR(*params: int)

Class representing SGR-type escape sequence with varying amount of parameters.

SequenceSGR with zero params was specifically implemented to translate into empty string and not into \e[m, which would have made sense, but also would be very entangling, as this sequence is equivalent of \e[0m – hard reset sequence. The empty-string-sequence is predefined as NOOP.

It’s possible to add of one SGR sequence to another:

SequenceSGR(31) + SequenceSGR(1)

which is equivalent to:

SequenceSGR(31, 1)
print() → str

Build up actual byte sequence and return as an ASCII-encoded string.

class pytermor.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.

property closing_seq: SequenceSGR

Return closing SGR sequence instance.

property closing_str: str

Return closing SGR sequence encoded.

property opening_seq: SequenceSGR

Return opening SGR sequence instance.

property opening_str: str

Return opening SGR sequence encoded.

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.