terminal.py<a class="headerlink" href="#module-blessed.terminal" title="Link to this heading">

Returns:

foreground color as tuple in form of (r, g, b). When a timeout is specified, always ensure the return value is checked for (-1, -1, -1).

Raises:

ValueError – When bits is not 8 or 16.

The foreground color is determined by emitting an OSC 10 color query.

See also get_bgcolor() for querying the background color.

Note

The default return value is 16-bit, matching the XParseColor specification of the underlying protocol. For most uses, 8-bit values are preferred:

rgb = term.get_fgcolor(bits=8)
term.color_rgb(*rgb)  # reset foreground to default

get_bgcolor(timeout: float = 1.0, bits: int = 16) → Tuple[int, int, int][source]

Return tuple (r, g, b) of default background color.

This returns the terminal’s default background color, not any currently active color set by escape sequences.

When is_a_tty is False, no sequences are transmitted or response awaited, and the value (-1, -1, -1) is returned without inquiry.

Parameters:

timeout (float) – Return after time elapsed in seconds with value (-1, -1, -1) indicating that the remote end did not respond.
bits (int) – Bits per channel: 16 (default, 0-65535, 48-bit total) or 8 (0-255, 24-bit total).

Return type:

Returns:

background color as tuple in form of (r, g, b). When a timeout is specified, always ensure the return value is checked for (-1, -1, -1).

Raises:

ValueError – If bits is not 8 or 16.

The background color is determined by emitting an OSC 11 color query.

See also get_fgcolor() for querying the foreground color.

Note

The default return value is 16-bit, matching the XParseColor specification of the underlying protocol. For most uses, 8-bit values are preferred:

rgb = term.get_bgcolor(bits=8)
term.on_color_rgb(*rgb)  # reset background to default

get_fgcolor_hex(timeout: float = 1.0, maybe_short: bool = False) → str[source]

Return default foreground color as hex string.

Parameters:

timeout (float) – Return after time elapsed in seconds with empty string if the remote end did not respond.
maybe_short (bool) – If True, return #RGB when possible.

Returns:

Hex color string (#RRGGBB or #RGB), or empty string on timeout or when is_a_tty is False.

Convenience wrapper combining get_fgcolor() and rgb_to_hex().

get_bgcolor_hex(timeout: float = 1.0, maybe_short: bool = False) → str[source]

Return default background color as hex string.

Parameters:

timeout (float) – Return after time elapsed in seconds with empty string if the remote end did not respond.
maybe_short (bool) – If True, return #RGB when possible.

Returns:

Hex color string (#RRGGBB or #RGB), or empty string on timeout or when is_a_tty is False.

Convenience wrapper combining get_bgcolor() and rgb_to_hex().

get_device_attributes(timeout: float | None = 1.0, force: bool = False) → DeviceAttribute | None[source]

Query the terminal’s Device Attributes (DA1).

When is_a_tty is False, no sequences are transmitted or response awaited, and None is returned without inquiry.

If a Device Attributes query fails to respond within the timeout specified, None is returned. If this was the first query for device attributes, all subsequent queries return None unless force=True is set (sticky failure).

Responses are cached indefinitely unless force=True is specified.

Note

A timeout value should be set to avoid blocking when the terminal does not respond to DA1 queries, which may happen with some kinds of “dumb” terminals.

Parameters:

timeout (float) – Timeout in seconds to await terminal response
force (bool) – Force active terminal inquiry even if cached result exists or previous query failed

Return type:

DeviceAttribute or None

Returns:

DeviceAttribute instance with terminal capabilities, or None if unsupported/timeout

term = Terminal()

# Query device attributes
da = term.get_device_attributes(timeout=TERMINAL_QUERY_TIMEOUT_SECONDS)
if da is not None:
    print(f"Service class: {da.service_class}")
    print(f"Supports sixel: {da.supports_sixel}")
    print(f"Extensions: {sorted(da.extensions)}")

get_software_version(timeout: float | None = 1.0, force: bool = False) → SoftwareVersion | None[source]

Query the terminal’s software name and version using XTVERSION.

Sends an XTVERSION query to the terminal and returns a SoftwareVersion instance with the terminal’s name and version.

If an XTVERSION query fails to respond within the timeout specified, falls back to the TERM_PROGRAM and TERM_PROGRAM_VERSION environment variables. Returns None only if both methods fail.

Successful responses are cached indefinitely unless force=True is specified. Unlike other query methods, there is no sticky failure mechanism - each failed query can be retried.

Note

A timeout value should be set to avoid blocking when the terminal does not respond to XTVERSION queries, which may happen with some kinds of “dumb” terminals.

Parameters:

timeout (float) – Timeout in seconds to await terminal response
force (bool) – Force active terminal inquiry even if cached result exists

Return type:

SoftwareVersion or None

Returns:

SoftwareVersion instance with terminal name and version, or None if unsupported/timeout

term = Terminal()

# Query software version
sv = term.get_software_version(timeout=TERMINAL_QUERY_TIMEOUT_SECONDS)
if sv is not None:
    print(f"Terminal: {sv.name} {sv.version}")

does_sixel(timeout: float | None = 1.0, force: bool = False) → bool[source]

Query whether the terminal supports sixel graphics.

Sixel is a bitmap graphics format supported by some modern terminal emulators, allowing applications to display inline images.

When is_a_tty is False, no sequences are transmitted or response awaited, and False is returned without inquiry.

This method calls get_device_attributes() to query the terminal’s capabilities and checks for sixel support (extension 4 in the DA1 response). Results are cached, so subsequent calls are fast.

Parameters:

timeout (float) – Timeout in seconds to await terminal response. When None (default), the query may block indefinitely.
force (bool) – Bypass cache and re-query the terminal

Return type:

Returns:

True if terminal supports sixel graphics, False otherwise

detect_ambiguous_width(timeout: float = 1.0, fallback: int = 1) → int[source]

Detect whether terminal renders ambiguous width characters as width 1 or 2.

East Asian ambiguous width characters can be rendered as either single (1) or double width (2), depending on terminal settings. This method measures the actual rendered width by printing a test character and querying the cursor position. The character is drawn and erased at the current cursor position. The test character used is U+00A7 (SECTION SIGN), an early Unicode character with East Asian Width property “Ambiguous”.

When is_a_tty is False, no sequences are transmitted or response awaited, and fallback is returned without inquiry.

Parameters:

timeout (float) – Timeout in seconds for any single cursor position response.
fallback (int) – Value to return on timeout, invalid measurement, or not a tty.

Return type:

int

Returns:

1 for “Ambiguous width as narrow”, 2 is “Ambiguous width as wide”

Example usage:

>>> term = Terminal()
>>> width = term.detect_ambiguous_width()
>>> if width == 2:
...     # Terminal uses double-width for ambiguous characters
...     pass

get_dec_mode(mode: int | DecPrivateMode, timeout: float = 1.0, force: bool = False) → DecModeResponse[source]

Query the state of a DEC Private Mode (DECRQM).

Sends a DECRQM query to the terminal and returns a DecModeResponse instance. Use the helper methods like DecModeResponse.is_supported() or DecModeResponse.is_enabled() and others to interpret the result.

When is_a_tty is False, no sequences are transmitted or response awaited, and the DecModeResponse value returned is always DecModeResponse.NOT_QUERIED.

In some cases a timeout value should be set, as it is possible for a terminal that succeeds is_a_tty to fail to respond to DEC Private Modes, such as in a CI Build Service or other “dumb” terminal, even a few popular modern ones such as Konsole.

If a DEC Private mode query fails to respond within the timeout specified, the DecModeResponse value returned is DecModeResponse.NO_RESPONSE. If this was the first DEC Private mode query, all subsequent queries return a DecModeResponse value of DecModeResponse.NOT_QUERIED unless force=True is set.

Repeat queries return the (cached) known state immediately without re-inquiry unless force=True. Although there are special cases where a user may re-configure their terminal settings after the state was requested by an application, the application is generally restarted to recognize the new settings rather than to repeatedly re-inquire about their latest value!

Parameters:

mode – DEC Private Mode to query
timeout (float) – Timeout in seconds to await terminal response
force (bool) – Force active terminal inquery in all cases

Return type:

DecModeResponse

Returns:

DecModeResponse instance

Raises:

TypeError – If mode is not DecPrivateMode or int

term = Terminal()

# Query synchronized output support
response = term.get_dec_mode(DecPrivateMode.SYNCHRONIZED_OUTPUT)
if response.supported:
    print("Synchronized output is available")

dec_modes_enabled(*modes: int | DecPrivateMode, timeout: float | None = 1.0) → Generator[None, None, None][source]

Context manager for temporarily enabling DEC Private Modes.

On entry, queries each mode’s current state using get_dec_mode().

For modes that are supported but currently disabled, enables them and tracks them for restoration. On exit, disables all modes that were enabled by this context manager, restoring original state.

Unsupported modes are silently ignored.

Parameters:

modes – One or more DEC Private Mode numbers or enum members
timeout (float) – Timeout in seconds for get_dec_mode calls

Raises:

TypeError – If mode is not DecPrivateMode or int

term = Terminal()

# Enable synchronized output temporarily
with term.dec_modes_enabled(DecPrivateMode.SYNCHRONIZED_OUTPUT):
    # All output will be atomic
    print("Frame 1")
    print("Frame 2")

dec_modes_disabled(*modes: int | DecPrivateMode, timeout: float | None = 1.0) → Generator[None, None, None][source]

Context manager for temporarily disabling DEC Private Modes.

Uses the same logic as dec_modes_enabled but inverted: disables supported modes that are currently enabled on entry, then restores them on exit.

Parameters:

modes – One or more DEC Private Mode numbers or enum members
timeout (float) – Timeout in seconds for get_dec_mode calls

Raises:

TypeError – If mode is not DecPrivateMode or int

does_mouse(*, clicks: bool = True, report_pixels: bool = False, report_drag: bool = False, report_motion: bool = False, timeout: float = 1.0) → bool[source]

Check if the terminal supports the specified mouse tracking features.

This method queries terminal support for the same DEC modes that mouse_enabled() would enable with the given parameters.

Parameters:

clicks (bool) – Check for basic click reporting (default True)
report_pixels (bool) – Check for pixel coordinate reporting
report_drag (bool) – Check for drag reporting
report_motion (bool) – Check for motion reporting
timeout (float) – Timeout for mode queries (default 1.0s)

Returns:

True if all required modes are supported

Return type:

Example:

if term.does_mouse(report_drag=True, report_pixels=True):
    with term.mouse_enabled(report_drag=True, report_pixels=True):
        # Use mouse tracking with drag and pixel support
        pass

does_inband_resize(timeout: float = 1.0) → bool[source]

Check if the terminal supports in-band window resize notifications.

This method queries whether the terminal supports DEC mode 2048 (IN_BAND_WINDOW_RESIZE), which allows receiving resize events as in-band sequences through inkey() instead of relying on SIGWINCH signals.

Parameters:: timeout (float) – Timeout for mode query (default 1.0s)
Returns:: True if in-band resize notifications are supported
Return type:: bool

Example:

if term.does_inband_resize():
    with term.notify_on_resize():
        # Use in-band resize events
        pass
else:
    # Fall back to SIGWINCH or other methods
    pass

does_bracketed_paste(timeout: float = 1.0) → bool[source]

Check if the terminal supports bracketed paste mode.

Bracketed paste mode (DEC mode 2004) wraps pasted text in special sequences so applications can distinguish pasted text from typed input.

Parameters:: timeout (float) – Timeout for mode query (default 1.0s).
Returns:: True if bracketed paste mode is supported.
Return type:: bool

does_synchronized_output(timeout: float = 1.0) → bool[source]

Check if the terminal supports synchronized output.

Synchronized output (DEC mode 2026) allows applications to batch screen updates, preventing tearing during rapid redraws.

Parameters:: timeout (float) – Timeout for mode query (default 1.0s).
Returns:: True if synchronized output is supported.
Return type:: bool

does_grapheme_clustering(timeout: float = 1.0) → bool[source]

Check if the terminal supports grapheme clustering.

Grapheme clustering (DEC mode 2027) enables Unicode grapheme cluster aware cursor movement and display.

Parameters:: timeout (float) – Timeout for mode query (default 1.0s).
Returns:: True if grapheme clustering is supported.
Return type:: bool

does_focus_events(timeout: float = 1.0) → bool[source]

Check if the terminal supports focus in/out event reporting.

Focus event reporting (DEC mode 1004) sends escape sequences when the terminal window gains or loses focus.

Parameters:: timeout (float) – Timeout for mode query (default 1.0s).
Returns:: True if focus event reporting is supported.
Return type:: bool

get_xtgettcap(timeout: float | None = 1.0, force: bool = False, caps: Iterable[str] | None = None) → TermcapResponse | None[source]

Query terminal capabilities via XTGETTCAP (DCS +q).

When caps is specified, only those capabilities are returned. When unspecified, all known XTGETTCAP capabilities are queried and returned. All results from XTGETTCAP are memoized permanently, unlike DECRQSS get_decrqss() which may change. Using force=True to re-retrieve any request.

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Always re-query for latest values.
caps – Capability names to query. When specified, only these additional capabilities may queried (incremental on cache). when unspecified, it as though all=True was used.

Return type:

TermcapResponse

does_xtgettcap(timeout: float | None = 1.0, force: bool = False) → bool[source]

Check if the terminal supports XTGETTCAP (DCS +q) queries.

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Bypass cached result.

Return type:

does_kitty_graphics(timeout: float | None = 1.0, force: bool = False) → bool[source]

Check if the terminal supports the Kitty graphics protocol.

Sends a minimal Kitty graphics query and checks for an OK response. Supported by kitty and WezTerm.

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Bypass cached result.

Return type:

get_iterm2_capabilities(timeout: float | None = 1.0, force: bool = False) → ITerm2Capabilities | None[source]

Query iTerm2 capabilities via OSC 1337;Capabilities.

When is_a_tty is False, returns None.

Responses are cached unless force is True.

Parameters:

timeout (float) – Timeout in seconds for each sub-query. On the first call, an additional CPR probe may be performed to enable fast negative detection, so total elapsed time may exceed timeout for terminals that do not respond.
force (bool) – Bypass cached result.

Return type:

ITerm2Capabilities or None

does_iterm2(timeout: float | None = 1.0, force: bool = False) → bool[source]

Check if the terminal supports any iTerm2 protocols.

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Bypass cached result.

Return type:

does_iterm2_graphics(timeout: float | None = 1.0, force: bool = False) → bool[source]

Check if the terminal supports iTerm2 inline image protocol.

This is equivalent to does_iterm2() and exists to pair with does_kitty_graphics() for graphics capability checks.

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Bypass cached result.

Return type:

does_kitty_notifications(timeout: float | None = 1.0, force: bool = False) → bool[source]

Check if the terminal supports Kitty desktop notifications (OSC 99).

Sends an OSC 99 query with a CPR boundary guard for fast negative detection. Currently supported only by kitty.

Parameters:

timeout (float) – Timeout in seconds for each sub-query. On the first call, an additional CPR probe may be performed to enable fast negative detection, so total elapsed time may exceed timeout for terminals that do not respond.
force (bool) – Bypass cached result.

Return type:

does_kitty_clipboard(timeout: float | None = 1.0, force: bool = False) → bool[source]

Check if the terminal supports the Kitty clipboard protocol (mode 5522).

Sends a DECRQM query for DEC private mode 5522 (Bracketed Paste MIME) with a CPR boundary guard for fast negative detection on terminals that do not recognize the mode.

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Bypass cached result.

Return type:

does_kitty_pointer_shapes(timeout: float | None = 1.0, force: bool = False) → str | None[source]

Query Kitty mouse pointer shape support (OSC 22).

Returns the current pointer shape name if supported, or None if the terminal does not respond. Uses a CPR boundary guard for fast negative detection.

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Bypass cached result.

Return type:

str or None

does_osc52_clipboard(timeout: float | None = 1.0, force: bool = False) → bool[source]

Detect OSC 52 clipboard support without reading the clipboard.

This method uses non-intrusive detection to avoid triggering user-facing clipboard permission prompts, DA1 extension 52 and XTGETTCAP ``Ms`` fields. These methods are preferred over sending an actual OSC 52 read request (\x1b]52;c;?\a), which may trigger a clipboard permission dialog in many modern terminals.

Parameters:

timeout (float) – Timeout in seconds for each sub-query.
force (bool) – Bypass cached result.

Return type:

Color palette update notifications

clipboard_copy(text: str, selection: str = 'c') → None[source]

Copy text to the system clipboard via OSC 52.

Writes an OSC 52 set sequence to the terminal output stream. Most modern terminals accept clipboard writes without any user prompt.

The sequence is written unconditionally when does_styling is True. If the terminal does not support OSC 52, the sequence should be ignored by the terminal.

Parameters:

text (str) – The text to copy to the clipboard.
selection (str) – The X11 selection target – 'c' for clipboard (default), 'p' for primary selection, or 's' for secondary. Most terminals only honor 'c'.

clipboard_paste(timeout: float | None = 10, selection: str = 'c') → str | None[source]

Read the system clipboard via OSC 52.

Sends an OSC 52 query (\x1b]52;c;?\a) and waits for the terminal to respond with the clipboard contents.

Warning

Many modern terminals display a permission dialog when an application reads the clipboard. The user must approve the dialog before the terminal sends a response.

The default timeout of 10 seconds allows time for human interaction. If the user denies the dialog, or no response is received within given timeout, this method returns None.

Parameters:

timeout (float) – Timeout in seconds. A generous timeout is recommended because the user may need to interact with a permission dialog.
selection (str) – The X11 selection target – 'c' for clipboard (default), 'p' for primary.

Return type:

str or None

Returns:

The clipboard text, or None if denied or timeout is reached.

get_color_scheme(timeout: float | None = 1.0, force: bool = False) → str | None[source]

Query the terminal’s color scheme preference (dark or light mode).

Sends a CSI ? 996 n Device Status Report query. Terminals that support color-scheme reporting respond with CSI ? 997 ; Ps n where Ps is 1 for dark mode or 2 for light mode. Uses a CPR boundary guard for fast negative detection.

This relates to Mode 2031 (COLOR_PALETTE_UPDATES) (not implemented).

See also

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Bypass cached result.

Return type:

str or None

Returns:

'dark', 'light', or None if unsupported.

does_kitty_query(timeout: float | None = 1.0, force: bool = False) → bool[source]

Detect Kitty with XTGETTCAP query extensions.

This is a trifle convenience wrapper of get_xtgettcap().

This method probes for kitty-query-name support. A successful response indicates that some set of Kitty query extensions are available.

To retrieve their values, follow up with get_xtgettcap() directly, for example:

>>> term = Terminal()
>>> term.does_kitty_query()
True
>>> term.get_xtgettcap(caps=[f"kitty-query-{key}" for key in [
    "font_family", "font_size", "dpi_x", "dpi_y"]])
TermcapResponse(supported=True, capabilities={
    'kitty-query-font_family': 'NotoSansMono-Regular',
    'kitty-query-font_size': '19',
    'kitty-query-dpi_x': '96',
    'kitty-query-dpi_y': '96'})

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Bypass cached result.

Return type:

get_decrqss(setting_id: str = 'm', timeout: float | None = 1.0) → str | None[source]

Query terminal state via DECRQSS (Request Status String).

Sends DCS $ q <setting_id> ST and decodes the response. Returns the parameter value string on success, with the echoed setting identifier stripped. Returns None when the terminal does not support DECRQSS or the setting is invalid.

Results are not cached – DECRQSS queries runtime state that may change between calls (cursor style, margins, SGR, etc.).

Use Decrqss for setting identifiers:

term = Terminal()
term.get_decrqss(term.Decrqss.DECSCUSR)  # cursor style
term.get_decrqss(term.Decrqss.DECSTBM)   # scroll region

See also

DECRQSS specification

Parameters:

setting_id (str) – Setting identifier to query (default: SGR).
timeout (float) – Timeout in seconds.

Return type:

str or None

does_decrqss(timeout: float | None = 1.0, force: bool = False) → bool[source]

Detect DECRQSS (Request Status String) support.

Sends a DECRQSS query for the current SGR state. A valid response indicates the terminal supports status string queries.

See also

DECRQSS specification

Parameters:

timeout (float) – Timeout in seconds.
force (bool) – Bypass cached result.

Return type:

does_styled_underlines(timeout: float | None = 1.0, force: bool = False) → bool[source]

Detect extended underline style support (curly, dotted, dashed).

Queries the terminal’s Smulx terminfo capability via XTGETTCAP. When supported, the terminal can render underline styles beyond the standard single underline, such as CSI 4:3 m (curly).

Parameters:

timeout (float) – Timeout in seconds for XTGETTCAP query.
force (bool) – Bypass cached result.

Return type:

does_colored_underlines(timeout: float | None = 1.0, force: bool = False) → bool[source]

Detect colored underline support (CSI 58;2;r;g;b m).

Queries the terminal’s Setulc terminfo capability via XTGETTCAP.

Parameters:

timeout (float) – Timeout in seconds for XTGETTCAP query.
force (bool) – Bypass cached result.

Return type:

does_text_sizing(timeout: float = 1.0, force: bool = False) → TextSizingResult[source]

Detect Kitty text sizing protocol support (OSC 66).

Tests width and scale text sizing by sending OSC 66 probes and measuring cursor position delta. Supported terminals may write up to 2 destructive spaces at the current cursor position, while unsupported terminals typically produce no output.

Responses are cached unless force is True.

Parameters:

timeout (float) – Timeout in seconds for each cursor position query.
force (bool) – Bypass cached result.

Return type:

TextSizingResult

Returns:

Result with .width and .scale boolean attributes.

mouse_enabled(*, clicks: bool = True, report_pixels: bool = False, report_drag: bool = False, report_motion: bool = False, timeout: float = 1.0) → Generator[None, None, None][source]

Context manager for enabling mouse tracking with various reporting modes.

Enables mouse event reporting with sensible defaults, and always enables SGR extended mouse mode (1006).

Parameters:

clicks (bool) – Enable basic click reporting (default True)
report_pixels (bool) – Report pixel coordinates instead of cell coordinates
report_drag (bool) – Report mouse drag events (button held while moving)
report_motion (bool) – Report all mouse motion events
timeout (float) – Timeout for mode queries (default 1.0s)

The reporting modes have precedence: motion > drag > clicks. Enabling a higher-precedence mode automatically includes lower modes.

Example:

with term.mouse_enabled():
    # Basic click tracking
    inp = term.inkey()
    if inp.name and inp.name.startswith('MOUSE_'):
        print(f"Clicked at {inp.x}, {inp.y}")

with term.mouse_enabled(report_drag=True):
    # Track clicks and drags
    pass

with term.mouse_enabled(report_motion=True, report_pixels=True):
    # Track all motion with pixel coordinates
    pass

bracketed_paste(timeout: float = 1.0) → Generator[None, None, None][source]

Context manager for enabling bracketed paste mode.

When enabled, pasted text is wrapped with special escape sequences, allowing applications to distinguish pasted content from typed input.

Parameters:: timeout (float) – Timeout for mode query (default 1.0s)

Example:

with term.bracketed_paste():
    inp = term.inkey()
    if inp.name == 'BRACKETED_PASTE':
        pasted_text = inp.text
        print(f"You pasted: {pasted_text}")

synchronized_output(timeout: float = 1.0) → Generator[None, None, None][source]

Context manager for enabling synchronized output mode.

Buffers all terminal output until the context exits, eliminating screen flicker during redraws. Perfect for animations and full-screen updates.

Parameters:: timeout (float) – Timeout for mode query (default 1.0s)

focus_events(timeout: float = 1.0) → Generator[None, None, None][source]

Context manager for enabling focus event reporting.

Reports when the terminal window gains or loses focus, useful for pausing animations or updating status indicators.

Parameters:: timeout (float) – Timeout for mode query (default 1.0s)

notify_on_resize(timeout: float = 1.0) → Generator[None, None, None][source]

Context manager for enabling in-band window resize notifications.

When enabled, the terminal will automatically send resize events as in-band sequences whenever the window size changes. These events are received by inkey() as keystroke events with name equal to 'RESIZE_EVENT'.

The new dimensions are automatically cached and available immediately through the standard height, width, pixel_height, and pixel_width properties without additional ioctl system calls.

This is the preferred method for handling terminal resizes as it avoids the race conditions and signal handling complexity of SIGWINCH on Unix systems, and provides a consistent cross-platform API.

Parameters:: timeout (float) – Timeout for mode query (default 1.0s)

Example:

with term.notify_on_resize():
    while True:
        inp = term.inkey(timeout=0.1)
        if inp.name == 'RESIZE_EVENT':
            # Dimensions updated automatically
            redraw_display(term.height, term.width)
        elif inp == 'q':
            break

get_sixel_height_and_width(timeout: float | None = 1.0, force: bool = False) → Tuple[int, int][source]

Query sixel graphics pixel dimensions.

Returns the maximum height and width in pixels for sixel graphics rendering. Detection order (from most to least reliable):

XTWINOPS 16t (CSI 16 t) - Character cell size, multiplied by rows/cols
XTWINOPS 14t (CSI 14 t) - Text area size in pixels
XTSMGRAPHICS - Sixel graphics query
TIOCSWINSZ / In-band resize - System ioctl / event pixel dimensions

The cell-based calculation (method 1) is preferred because it accounts for the actual drawable text area, excluding window margins and decorations.

When is_a_tty is False, no sequences are transmitted or response awaited, and (-1, -1) is returned without inquiry.

Parameters:

timeout (float) – Timeout in seconds for queries
force (bool) – Bypass cache and re-query the terminal

Return type:

Returns:

(height, width) in pixels, or (-1, -1) if unsupported/timeout

get_sixel_colors(timeout: float | None = 1.0, force: bool = False) → int[source]

Query number of sixel color registers (XTSMGRAPHICS).

Returns the maximum number of color registers available for sixel graphics rendering. If XTSMGRAPHICS query fails but the terminal advertises Sixel support via DA1 (Device Attributes), returns 256 as a sensible default.

When is_a_tty is False, no sequences are transmitted or response awaited, and -1 is returned without inquiry.

Parameters:

timeout (float) – Timeout in seconds for both possible queries
force (bool) – Bypass cache and re-query the terminal

Return type:

int

Returns:

Number of color registers, 256 if DA1 advertises sixel but XTSMGRAPHICS fails, or -1 if unsupported/timeout

get_cell_height_and_width(timeout: float | None = 1.0, force: bool = False) → Tuple[int, int][source]

Query character cell pixel dimensions (XTWINOPS).

Returns the height and width in pixels of a single character cell.

When is_a_tty is False, no sequences are transmitted or response awaited, and (-1, -1) is returned without inquiry.

Parameters:

timeout (float) – Timeout in seconds for the query
force (bool) – Bypass cache and re-query the terminal

Return type:

Returns:

(height, width) in pixels, or (-1, -1) if unsupported/timeout

get_kitty_keyboard_state(timeout: float | None = 1.0, force: bool = False) → KittyKeyboardProtocol | None[source]

Query the current Kitty keyboard protocol flags.

Sends a Kitty keyboard protocol query to the terminal and returns a KittyKeyboardProtocol instance with the current flags. This method is not normally used directly, rather it is used by the enable_kitty_keyboard() context manager on entrance to discover and restore the previous state on exit.

When is_a_tty is False, no sequences are transmitted or response awaited, and None is returned.

In many cases a timeout value (in seconds) should be set, as it is possible for a terminal that succeeds is_a_tty to fail to respond to either Kitty keyboard protocol state request, or the simple device attribute request query carried with it! And not just “dumb” terminals fail to respond, even some fairly modern terminals like Konsole.

If a Kitty keyboard protocol query fails to respond within the timeout specified, None is returned. If this was the first Kitty keyboard protocol query, all subsequent queries return None unless force=True is set.

No state caching is performed - each call re-queries the terminal unless the first query previously failed (sticky failure) and force=False.

Parameters:

timeout (float) – Timeout in seconds to await terminal response
force (bool) – Force active terminal inquiry in all cases

Return type:

KittyKeyboardProtocol or None

Returns:

KittyKeyboardProtocol instance with current flags, or None if unsupported/timeout

enable_kitty_keyboard(*, disambiguate: bool = True, report_events: bool = False, report_alternates: bool = False, report_all_keys: bool = False, report_text: bool = False, mode: int = 1, timeout: float | None = 1.0, force: bool = False) → Generator[None, None, None][source]

Context manager that enables Kitty keyboard protocol features.

Parameters:

disambiguate (bool) – Enable disambiguated escape codes (fixes issues with Esc vs sequences)
report_events (bool) – Report key repeat and release events
report_alternates (bool) – Report shifted and base layout keys for shortcuts
report_all_keys (bool) – Report all keys as escape codes (including text keys)
report_text (bool) – Report associated text with key events (requires report_all_keys)
mode (int) – Protocol mode (1=set/clear specified flags, 2=set only, 3=clear only)
timeout (float) – Timeout for querying current flags before setting new ones
force (bool) – Force sequences to be emitted even if timeout previously occurred

Always queries current state before setting new flags and restores previous state on exit.

Example:

with term.enable_kitty_keyboard(disambiguate=True):
    # Now Alt+C won't conflict with Ctrl+C
    key = term.inkey()
    if key.alt and key.is_alt('c'):
        print("Alt+C pressed")

Note

A timeout value should be set to avoid blocking when the terminal does not respond to DA1 or kitty protocol queries, which may happen with some kinds of “dumb” terminals, even some modern terminals like Konsole.

fullscreen() → Generator[None, None, None][source]

Context manager that switches to secondary screen, restoring on exit.

Under the hood, this switches between the primary screen buffer and the secondary one. The primary one is saved on entry and restored on exit. Likewise, the secondary contents are also stable and are faithfully restored on the next entry:

with term.fullscreen():
    main()

Note

There is only one primary and one secondary screen buffer. fullscreen() calls cannot be nested, only one should be entered at a time.

hidden_cursor() → Generator[None, None, None][source]

Context manager that hides the cursor, setting visibility on exit.

with term.hidden_cursor():
main()

Note

hidden_cursor() calls cannot be nested: only one should be entered at a time.

cursor_shape(style: int | str = 2) → Generator[None, None, None][source]

Context manager that sets cursor shape, restoring default on exit.

Parameters:: style – A CursorShape constant or string name (e.g. 'blinking_bar').

Uses DECSCUSR (DEC Set Cursor Style) escape sequences:

with term.cursor_shape(term.CursorShape.BLINKING_BAR):
    main()

String names are also accepted:

with term.cursor_shape('steady_underline'):
    main()

On exit, the cursor is reset to the terminal default (DECSCUSR 0).

Note

DECSCUSR is supported by most modern terminals including xterm, VTE-based terminals, iTerm2, Windows Terminal, kitty, ghostty, alacritty, and WezTerm.

no_line_wrap() → Generator[None, None, None][source]

Context manager that disables line wrapping, enabling on exit.

Uses DEC Auto Wrap Mode (DECAWM) to control whether text reaching the right edge wraps to the next line:

with term.no_line_wrap():
    print(term.move_x(0) + 'x' * 200)  # Clips, doesn't wrap

On exit, line wrapping is unconditionally enabled as terminals should prefer line-wrapping mode for normal operation.

Note

no_line_wrap() calls cannot be nested: only one should be entered at a time.

scroll_region(top: int = 0, height: int | None = None) → Generator[None, None, None][source]

Context manager that sets a scrolling region, resetting on exit.

Parameters:

top (int) – Top row of the scrolling region (0-indexed). Defaults to 0.
height (int) – Number of rows in the scrolling region. Defaults to self.height - top (extending to the bottom of the screen).

Returns:

a context manager.

Return type:

Iterator

A scrolling region restricts scrolling to a portion of the screen. When text scrolls within the region, content outside the region remains fixed. This is useful for creating interfaces with fixed headers, footers, or status bars:

with term.fullscreen(), term.scroll_region(top=1, height=term.height - 2):
    # row 0 and the last row remain fixed
    # scrolling happens only in the middle region
    for i in range(100):
        print(f'Line {i}')

The cursor position may be reset to the home position when the scroll region changes. Use move_yx() to reposition as needed after entering the context.

Note

scroll_region() calls cannot be nested: only one should be entered at a time.

move_xy(x: int, y: int) → str[source]

A callable string that moves the cursor to the given (x, y) screen coordinates.

Parameters:

x (int) – horizontal position, from left, 0, to right edge of screen, self.width - 1.
y (int) – vertical position, from top, 0, to bottom of screen, self.height - 1.

Return type:

ParameterizingString

Returns:

Callable string that moves the cursor to the given coordinates

move_yx(y: int, x: int) → str[source]

A callable string that moves the cursor to the given (y, x) screen coordinates.

Parameters:

y (int) – vertical position, from top, 0, to bottom of screen, self.height - 1.
x (int) – horizontal position, from left, 0, to right edge of screen, self.width - 1.

Return type:

ParameterizingString

Returns:

Callable string that moves the cursor to the given coordinates

property move_left: FormattingOtherString: Move cursor 1 cells to the left, or callable string for n>1 cells.

property move_right: FormattingOtherString: Move cursor 1 or more cells to the right, or callable string for n>1 cells.

property move_up: FormattingOtherString: Move cursor 1 or more cells upwards, or callable string for n>1 cells.

property move_down: FormattingOtherString: Move cursor 1 or more cells downwards, or callable string for n>1 cells.

property color: NullCallableString | ParameterizingString

A callable string that sets the foreground color.

Return type:: ParameterizingString

The capability is unparameterized until called and passed a number, at which point it returns another string which represents a specific color change. This second string can further be called to color a piece of text and set everything back to normal afterward.

This should not be used directly, but rather a specific color by name or color_rgb() value.

color_rgb(red: int, green: int, blue: int) → FormattingString[source]

Provides callable formatting string to set foreground color to the specified RGB color.

Parameters:

red (int) – 8-bit RGB value of Red (0-255).
green (int) – 8-bit RGB value of Green (0-255).
blue (int) – 8-bit RGB value of Blue (0-255).

Return type:

FormattingString

Returns:

Callable string that sets the foreground color.

If the terminal does not support RGB color, the nearest supported color will be determined using color_distance_algorithm.

color_hex(hex_color: str) → FormattingString[source]

Provides callable formatting string to set foreground color from hex.

Parameters:: hex_color (str) – Hex color in #RGB, #RRGGBB, or #RRRRGGGGBBBB format. The # prefix is optional.
Return type:: FormattingString
Returns:: Callable string that sets the foreground color.

If the terminal does not support RGB color, the nearest supported color will be determined using color_distance_algorithm.

See hex_to_rgb() for supported hex formats.

property on_color: NullCallableString | ParameterizingString

A callable capability that sets the background color.

Return type:: ParameterizingString

on_color_rgb(red: int, green: int, blue: int) → FormattingString[source]

Provides callable formatting string to set background color to the specified RGB color.

Parameters:

red (int) – 8-bit RGB value of Red (0-255).
green (int) – 8-bit RGB value of Green (0-255).
blue (int) – 8-bit RGB value of Blue (0-255).

Return type:

FormattingString

Returns:

Callable string that sets the background color.

If the terminal does not support RGB color, the nearest supported color will be determined using color_distance_algorithm.

on_color_hex(hex_color: str) → FormattingString[source]

Provides callable formatting string to set background color from hex.

Parameters:: hex_color (str) – Hex color in #RGB, #RRGGBB, or #RRRRGGGGBBBB format. The # prefix is optional.
Return type:: FormattingString
Returns:: Callable string that sets the background color.

If the terminal does not support RGB color, the nearest supported color will be determined using color_distance_algorithm.

See hex_to_rgb() for supported hex formats.

formatter(value: str) → NullCallableString | FormattingString[source]

Provides callable formatting string to set color and other text formatting options.

Parameters:: value (str) – Sugary, ordinary, or compound formatted terminal capability, such as “red_on_white”, “normal”, “red”, or “bold_on_black”.
Return type:: FormattingString or NullCallableString
Returns:: Callable string that sets color and other text formatting options

Calling term.formatter('bold_on_red') is equivalent to term.bold_on_red, but a string that is not a valid text formatter will return a NullCallableString. This is intended to allow validation of text formatters without the possibility of inadvertently returning another terminal capability.

rgb_downconvert(red: int, green: int, blue: int) → int[source]

Translate an RGB color to a color code of the terminal’s color depth.

This method is only be used to downconvert for terminals of 256 or fewer colors.

Parameters:

red (int) – RGB value of Red (0-255).
green (int) – RGB value of Green (0-255).
blue (int) – RGB value of Blue (0-255).

Return type:

int

Returns:

Color code of downconverted RGB color

property normal: str

A capability that resets all video attributes.

Return type:: str

normal is an alias for sgr0 or exit_attribute_mode. Any styling attributes previously applied, such as foreground or background colors, reverse video, or bold are reset to defaults.

link(url: str, text: str, url_id: str = '') → str[source]

Display text that when touched or clicked, navigates to url.

Optional url_id may be specified, so that non-adjacent cells can reference a single target, all cells painted with the same “id” will highlight on hover, rather than any individual one, as described in “Hovering and underlining the id parameter” of gist https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda.

Parameters:

url¶ (str) – Hyperlink URL.
text¶ (str) – Clickable text.
url_id¶ (str) – Optional ‘id’.

Return type:

Returns:

String of text as a hyperlink to url.

set_window_title(title: str, mode: int = 0) → str[source]

Return sequence to set the terminal title.

Uses xterm OSC (Operating System Command) sequences to set the window and/or icon title.

Parameters:

title¶ (str) – Title text. Any embedded escape or BEL characters are stripped to prevent sequence injection.
mode¶ (int) – OSC mode – 0 sets both icon name and window title, 1 sets icon name only, 2 sets window title only.

Return type:

Returns:

Escape sequence string that sets the terminal title, or empty string when does_styling is False.

window_title(title: str, mode: int = 0) → Generator[None, None, None][source]

Context manager that sets terminal title, restoring on exit.

Uses the xterm title stack (XTWINOPS push/pop) to save and restore the previous title. Not all terminals support the title stack – those that do not will simply set the title without restoring it on exit.

Parameters:

title¶ (str) – Title text.
mode¶ (int) – OSC mode – 0 sets both icon name and window title, 1 sets icon name only, 2 sets window title only.

progress_bar(state: str | int, value: int | None = None) → str[source]

Return OSC 9;4 sequence for terminal progress bar support.

Support for ‘OSC 9;4’ cannot be detected. It is generally safe to write to unsupported terminals. Some terminals display a graphical progress indicator in the taskbar and window menu or status bar matching the given value (0-100). Supported by at least Windows Terminal.exe, ConEmu, Ghostty, kitty, and iTerm2.

Parameters:

state¶ –
Progress state. Accepts either an integer or a string name:
- 0 or 'clear': Remove progress indicator
- 1 or 'normal': Set progress to value (0 to 100)
- 2 or 'error': Error state (typically red)
- 3 or 'indeterminate': Indeterminate / pulsing
- 4 or 'paused': Paused state (typically yellow)
value¶ (int) – Progress value as integer of percent (0 to 100). Required when state is 'normal' or 1. Terminals are expected to ignore ‘value’ for all other states.

Return type:

Returns:

OSC 9;4 escape sequence, or '' when does_styling is False.

Raises:

ValueError – on bad state identifier or invalid or out of bounds value.

property stream: IO[str]

Read-only property: stream the terminal outputs to.

This is a convenience attribute. It is used internally for implied writes performed by context managers hidden_cursor(), fullscreen(), location(), and keypad().

property number_of_colors: int

Number of colors supported by terminal.

Common return values are 0, 8, 16, 256, or 1 << 24.

This may be used to test whether the terminal supports colors, and at what depth, if that’s a concern.

If this property is assigned a value of 88, the value 16 will be saved. This is due to the the rarity of 88 color support and the inconsistency of behavior between implementations.

Assigning this property to a value other than 0, 4, 8, 16, 88, 256, or 1 << 24 will raise an AssertionError.

property color_distance_algorithm: str

Color distance algorithm used by rgb_downconvert().

The slowest, but most accurate, ‘cie2000’, is default. Other available options are ‘rgb’, ‘rgb-weighted’, ‘cie76’, and ‘cie94’. This function is only be used to downconvert for terminals of 256 or fewer colors.

ljust(text: str, width: SupportsIndex | None = None, fillchar: str = ' ') → str[source]

Left-align text, which may contain terminal sequences.

Parameters:

text (str) – String to be aligned
width (int) – Total width to fill with aligned text. If unspecified, the whole width of the terminal is filled.
fillchar (str) – String for padding the right of text

Return type:

Returns:

String of text, left-aligned by width.

rjust(text: str, width: SupportsIndex | None = None, fillchar: str = ' ') → str[source]

Right-align text, which may contain terminal sequences.

Parameters:

text (str) – String to be aligned
width (int) – Total width to fill with aligned text. If unspecified, the whole width of the terminal is used.
fillchar (str) – String for padding the left of text

Return type:

Returns:

String of text, right-aligned by width.

center(text: str, width: SupportsIndex | None = None, fillchar: str = ' ') → str[source]

Center text, which may contain terminal sequences.

Parameters:

text (str) – String to be centered
width (int) – Total width in which to center text. If unspecified, the whole width of the terminal is used.
fillchar (str) – String for padding the left and right of text

Return type:

Returns:

String of text, centered by width

text_sized(text: str, scale: int = 1, *, width: int = 0, numerator: int = 0, denominator: int = 0, vertical_align: int | str = 0, horizontal_align: int | str = 0) → str[source]

Wrap text in a text sizing escape sequence (OSC 66).

Returns text unchanged when the terminal does not support text sizing, providing graceful degradation.

Parameters:

text (str) – Text payload.
scale (int) – Scale factor (1 to 7).
width (int) – Width in cells (0 to 7). 0 means auto-calculate from the inner text.
numerator (int) – Fractional scaling numerator (0 to 15).
denominator (int) – Fractional scaling denominator (0 to 15).
vertical_align – Vertical alignment: (‘top’, ‘bottom’, ‘center’), or protocol code (0=top, 1=bottom, 2=center).
horizontal_align – Horizontal alignment. (‘left’, ‘right’, ‘center’) or protocol code (0=left, 1=right, 2=center).

Return type:

Kitty Text Sizing Protocol

Returns:

Text wrapped in an OSC 66 escape sequence, or plain text on unsupported terminals.

Raises:

ValueError – when the encoded text exceeds 4096 bytes.
ValueError – when vertical_align or horizontal_align is an unrecognized string value.

See also

Note

Because the first call to Terminal.text_sized() will cause the side effect of writing destructive spaces to the columns and row following the current cursor position as required for detection of kitty text sizing protocol, it is suggested to first call Terminal.does_text_sizing() during program initialization.

The result is permanently cached and all further calls to these methods return immediately without this side effect.

truncate(text: str, width: SupportsIndex | None = None) → str[source]

Truncate text to width printable characters, retaining terminal sequences.

Wide characters (such as CJK or emoji) that would partially exceed width are replaced with space padding to maintain exact width.

Parameters:

text (str) – Text to truncate
width (int) – The width to truncate to. If unspecified, the whole width of the terminal is used.

Return type: