API Reference

jinxed

Jinxed is a pure-Python implementation of a subset of the Python curses library.

jinxed.setupterm(term=None, fd=-1): Reimplementation of curses.setupterm()

jinxed.tigetflag(capname): Reimplementation of curses.tigetflag()

jinxed.tigetnum(capname): Reimplementation of curses.tigetnum()

jinxed.tigetstr(capname): Reimplementation of curses.tigetstr()

jinxed.tparm(str[, ...]): Reimplementation of curses.tparm()

class jinxed.Terminal(term=None, fd=-1)

Persistent terminal object for functions that require a previously configured state

overlay_capabilities(str_caps=None, num_caps=None, bool_caps=None)

Overlay terminfo capabilities onto this terminal instance.

Methods tigetstr(), tigetnum(), and tigetflag() consult these given caches before falling back to the virtual terminfo database. This can be used to “patch” the capabilities database or with dynamic capability responses.

Parameters:

str_caps (dict) – Mapping of capability name to string value. String values are encoded as latin-1; bytes values are stored directly. For non-ASCII text, prefer bytes to avoid ambiguities with latin-1 encoding.
num_caps (dict) – Mapping of capability name to integer value.
bool_caps (set) – Set of boolean capability names that are present.

tigetflag(capname): Reimplementation of curses.tigetflag()

tigetnum(capname): Reimplementation of curses.tigetnum()

tigetstr(capname): Reimplementation of curses.tigetstr()

exception jinxed.error: Generic class for Jinxed errors

jinxed.win32

Support functions and wrappers for calls to the Windows API

Note

Some functions require a file descriptor while others require a file handle. The windows library generally requires file handles, but some functions are intended to mimic existing functions that use file descriptors. An example of a obtaining a file descriptor is fd = sys.stdout.fileno(). The file handle can then be obtained with msvcrt.get_osfhandle(fd).

jinxed.win32.VTMODE_SUPPORTED: True when the Windows version is 10.0.10586 or higher

class jinxed.win32.ConsoleScreenBufferInfo: Python representation of a CONSOLE_SCREEN_BUFFER_INFO object

jinxed.win32.get_csbi(filehandle=None)

Parameters:: filehandle (int) – Windows filehandle object as returned by msvcrt.get_osfhandle()
Returns:: CONSOLE_SCREEN_BUFFER_INFO structure
Return type:: ConsoleScreenBufferInfo

Wrapper for GetConsoleScreenBufferInfo

If filehandle is None, uses the filehandle of sys.__stdout__.

jinxed.win32.get_console_input_encoding()

Returns:: Current console mode
Return type:: int

Query for the console input code page and provide an encoding

If the code page can not be resolved to a Python encoding, None is returned.

jinxed.win32.get_console_mode(filehandle)

Parameters:: filehandle (int) – Windows filehandle object as returned by msvcrt.get_osfhandle()
Returns:: Current console mode
Return type:: int
Raises:: OSError – Error calling Windows API

Wrapper for GetConsoleMode

jinxed.win32.set_console_mode(filehandle, mode)

Parameters:

filehandle (int) – Windows filehandle object as returned by msvcrt.get_osfhandle()
mode (int) – Desired console mode

Raises:

OSError – Error calling Windows API

Wrapper for SetConsoleMode

jinxed.win32.setcbreak(filehandle)

Parameters:: filehandle (int) – Windows filehandle object as returned by msvcrt.get_osfhandle()
Raises:: OSError – Error calling Windows API

Convenience function which mimics tty.setcbreak() behavior

All console input options are disabled except ENABLE_PROCESSED_INPUT and, if supported, ENABLE_VIRTUAL_TERMINAL_INPUT

jinxed.win32.setraw(filehandle)

Parameters:: filehandle (int) – Windows filehandle object as returned by msvcrt.get_osfhandle()
Raises:: OSError – Error calling Windows API

Convenience function which mimics tty.setraw() behavior

All console input options are disabled except, if supported, ENABLE_VIRTUAL_TERMINAL_INPUT

jinxed.win32.enable_vt_mode(filehandle=None)

Parameters:: filehandle (int) – Windows filehandle object as returned by msvcrt.get_osfhandle()
Raises:: OSError – Error calling Windows API

Enables virtual terminal processing mode for the given console

If filehandle is None, uses the filehandle of sys.__stdout__.

jinxed.win32.get_terminal_size(fd)

Parameters:: fd (int) – Python file descriptor
Returns:: Named tuple representing terminal size
Return type:: os.terminal_size

Convenience function for getting terminal size

In Python 3.3 and above, this is a wrapper for os.get_terminal_size(). In older versions of Python, this function calls GetConsoleScreenBufferInfo.

jinxed.win32.flush_and_set_console(fd, mode=None)

Parameters:

filehandle (int) – Windows filehandle object as returned by msvcrt.get_osfhandle()
mode (int) – Desired console mode. If None, mode is not changed

Attempts to set console to specified mode, but will not raise on failure

If the file descriptor is STDOUT or STDERR, attempts to flush first

jinxed.win32.get_term(fd, fallback=True)

Parameters:

fd (int) – Python file descriptor
fallback (bool) – Use fallback terminal type if type can not be determined

Returns:

Terminal type

Return type:

str

Attempts to determine and enable the current terminal type

The current logic is:

If TERM is defined in the environment, the value is returned

Else, if ANSICON is defined in the environment, 'ansicon' is returned

Else, if WT_SESSION is set (Windows Terminal, a modern host application distinct from the legacy console host), 'ms-terminal' is returned

Else, if virtual terminal mode is natively supported (legacy Windows Console Host, conhost.exe), it is enabled and 'vtwin10' is returned

Else, if fallback is True, Ansicon is loaded, and 'ansicon' is returned

If no other conditions are satisfied, 'unknown' is returned

This logic may change in the future as additional terminal types are added.

class jinxed.win32.ConsoleInput(fd)

Console input handle with wait, peek, and read operations.

Parameters:: fd (int) – Python file descriptor (e.g. sys.stdin.fileno()).

Example:

console = ConsoleInput(sys.stdin.fileno())
if console.wait(timeout=5.0):
    event = console.peek()

property fd: The Python file descriptor.

property handle: The Windows console handle.

wait(timeout=None)

Wait for console input to become available.

Parameters:: timeout (float) – Seconds to wait. None blocks indefinitely, 0 is non-blocking, positive values specify a deadline.
Returns:: True if input is available, False on timeout.
Return type:: bool
Raises:: OSError – If WaitForSingleObject fails.

The call is non-destructive – no events are consumed.

peek()

Peek at the next console input event without consuming it.

Returns:: The next INPUT_RECORD, or None if the buffer is empty.
Return type:: INPUT_RECORD or None
Raises:: OSError – If PeekConsoleInputW fails.

read()

Read and consume the next console input event.

Returns:: The next INPUT_RECORD, or None if the buffer is empty.
Return type:: INPUT_RECORD or None
Raises:: OSError – If ReadConsoleInputW fails.