Functions related to terminals.

Short summary:

• modify_termios: Apply mode changes to a tty. Return the previous tty modes as from termios.tcgetattr or None if the changes could not be applied. If strict, raise an exception instead of returning None.

• rmoveto: Move the cursor dx positions horizontally and dy positions vertically. dy is negative for up and positive for down.

• rmoveto_bs: Return the control bytes needed to move the cursor dx positions horizontally and dy positions vertically. dy is negative for up and positive for down.

• setupterm: Run curses.setupterm, needed to be able to use the status line. Uses a global flag to avoid doing this twice.

• stack_termios: Context manager to apply and restore changes to a tty. Yield the previous tty modes as from termios.tcgetattr or None if the changes could not be applied. If strict, raise an exception instead of yielding None.

• status: Write a message to the terminal's status line.

• statusline: Update the status line.

• statusline_bs: Return a byte string to update the status line.

• ttysize: Return a (rows, columns) tuple for the specified file descriptor.

• ttysizepx: Return a (rows,columns,widthpx,heightpx) tuple for the specified file descriptor being the terminal character rows and columns and pixel width and height respectively.

• WinSize: WinSize(rows, columns).

• WinSizePX: Size information about a terminal including its pixel size.

Functions

modify_termios(fd=0, set_modes=None, clear_modes=None, strict=False)

Apply mode changes to a tty. Return the previous tty modes as from termios.tcgetattr or None if the changes could not be applied. If strict, raise an exception instead of returning None.

Parameters:

• fd: optional tty file descriptor, default 0.
• set_modes: an optional mapping of attribute name to new value for values to set
• clear_modes: an optional mapping of attribute name to new value for values to clear
• strict: optional flag, default False; if true, raise exceptions from failed tcgetattr and tcsetattr calls otherwise issue a warning if the errno is not ENOTTY and proceed. This aims to provide ease of use in batch mode by default while providing a mode to fail overtly if required.

The attribute names are from iflag, oflag, cflag, lflag, ispeed, ospeed, cc, corresponding to the list entries defined by the termios.tcgetattr call.

For set_modes, the attributes ispeed, ospeed and cc are applied directly; the other attributes are binary ORed into the existing modes.

For clear_modes, the attributes ispeed, ospeed and cc cannot be cleared; the other attributes are binary removed from the existing modes.

For example, to turn off the terminal echo during some operation:

old_modes = apply_termios(clear_modes={'lflag': termios.ECHO}):
    ... do something with tty echo disabled ...
if old_modes:
    termios.tcsetattr(fd, termios.TCSANOW, old_modes)

rmoveto(dx, dy, *, file=None, flush=False)

Move the cursor dx positions horizontally and dy positions vertically. dy is negative for up and positive for down.

Parameters:

• dx: the number of horizontal positions to move, negative is left, positive is right
• dy: the number of vertical positions to move, negative is up, positive is down
• file: the file object to write to, default sys.stdout
• flush: whether to flush file after the write, default False

rmoveto_bs(dx, dy, *, flush=False) -> bytes

Return the control bytes needed to move the cursor dx positions horizontally and dy positions vertically. dy is negative for up and positive for down.

setupterm(*args)

Run curses.setupterm, needed to be able to use the status line. Uses a global flag to avoid doing this twice.

stack_termios(fd=0, set_modes=None, clear_modes=None, strict=False)

Context manager to apply and restore changes to a tty. Yield the previous tty modes as from termios.tcgetattr or None if the changes could not be applied. If strict, raise an exception instead of yielding None.

Parameters:

• fd: optional tty file descriptor, default 0.
• set_modes: an optional mapping of attribute name to new value for values to set
• clear_modes: an optional mapping of attribute name to new value for values to clear
• strict: optional flag, default False; if true, raise exceptions from failed tcgetattr and tcsetattr calls otherwise issue a warning if the errno is not ENOTTY and proceed. This aims to provide ease of use in batch mode by default while providing a mode to fail overtly if required.

The attribute names are from iflag, oflag, cflag, lflag, ispeed, ospeed, cc, corresponding to the list entries defined by the termios.tcgetattr call.

For set_modes, the attributes ispeed, ospeed and cc are applied directly; the other attributes are binary ORed into the existing modes.

For clear_modes, the attributes ispeed, ospeed and cc cannot be cleared; the other attributes are binary removed from the existing modes.

For example, to turn off the terminal echo during some operation:

with stack_termios(clear_modes={'lflag': termios.ECHO}):
    ... do something with tty echo disabled ...

status(msg, *args, **kwargs)

Write a message to the terminal's status line.

Parameters:

• msg: message string
• args: if not empty, the message is %-formatted with args
• file: optional keyword argument specifying the output file. Default: sys.stderr.

Hack: if there is no status line use the xterm title bar sequence :-(

statusline(text, fd=None, reverse=False, xpos=None, ypos=None)

Update the status line.

statusline_bs(text, reverse=False, xpos=None, ypos=None)

Return a byte string to update the status line.

ttysize(fd)

Return a (rows, columns) tuple for the specified file descriptor.

If the window size cannot be determined, None will be returned for either or both of rows and columns.

This function relies on the UNIX stty command.

ttysizepx(fd)

Return a (rows,columns,widthpx,heightpx) tuple for the specified file descriptor being the terminal character rows and columns and pixel width and height respectively.

This function relies on the fcntl.ioctl using termios.TIOCGWINSZ.

Classes

class WinSize(builtins.tuple)

WinSize(rows, columns)

WinSize.__replace__(self, /, **kwds)

Return a new WinSize object replacing specified fields with new values

WinSize.columns

_tuplegetter(1, 'Alias for field number 1')

WinSize.rows

_tuplegetter(0, 'Alias for field number 0')

class WinSizePX(WinSizePX)

Size information about a terminal including its pixel size.

WinSizePX.char_height

<property object at 0x105fffe70>

WinSizePX.char_width

<property object at 0x105fffd80>