utils Module

Functions:

get_cell_size	Returns the current size of a character cell in the active terminal.
get_terminal_name_version	Returns the name and version of the active terminal, if available.
get_terminal_size	Returns the current size of the active terminal.
lock_tty	Synchronizes access to the active terminal.
read_tty_all	Reads all available input directly from the active terminal without blocking.
write_tty	Writes to the active terminal and waits until complete transmission.

term_image.utils.get_cell_size()

Returns the current size of a character cell in the active terminal.

Returns:

The cell size in pixels or None if undetermined.

Return type:

Size | None

The speed of this implementation is almost entirely dependent on the terminal; the method it supports and its response time if it has to be queried.

Note

Currently works on UNIX only, returns None on any other platform or when there is no active terminal.

term_image.utils.get_terminal_name_version()

Returns the name and version of the active terminal, if available.

Returns:

A 2-tuple, (name, version). If either is not available, returns None in its place.

Return type:

tuple[str | None, str | None]

term_image.utils.get_terminal_size()

Returns the current size of the active terminal.

Returns:

The terminal size in columns and lines.

Return type:

terminal_size

Note

This implementation is quite different from shutil.get_terminal_size() and os.get_terminal_size() in that it:

• gives the correct size of the active terminal even when output is redirected, in most cases

• gives different results in certain situations

• is what this library works with

term_image.utils.lock_tty(func)

Synchronizes access to the active terminal.

Parameters:

func (Callable[[~P], T]) – The function to be wrapped.

When a decorated function is called, a re-entrant lock is acquired by the current process or thread and released after the call, such that any other decorated function called within another thread or subprocess waits until the lock is fully released (i.e has been released as many times as acquired) by the current process or thread.

Note

It works across parent-/sub-processes, started directly or indirectly via multiprocessing.Process (or a subclass of it), and their threads, provided multiprocessing.synchronize is supported on the host platform. Otherwise, a warning is issued when starting a subprocess.

Warning

If multiprocessing.synchronize is supported and a subprocess is started within a call (possibly recursive) to a decorated function, the thread in which that occurs will be out of sync until that call returns. Hence, avoid starting a subprocess within a decorated function.

term_image.utils.read_tty_all()

Reads all available input directly from the active terminal without blocking.

Returns:

The input read or None if not supported.

Return type:

bytes | None

Important

Synchronized with lock_tty().

Note

Currently works on UNIX only, returns None on any other platform or when there is no active terminal.

term_image.utils.write_tty(data)

Writes to the active terminal and waits until complete transmission.

Parameters:

data (bytes) – Data to be written.

Important

Synchronized with lock_tty().

Note

Currently works on UNIX only, returns None on any other platform or when there is no active terminal.