Skip to content
Back to top
View this page

# `utils` Module

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:

    Tuple[int, int] | 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:

    os.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 (types.LambdaType) – 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.

  Return type:

    bytes

  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.