Jinxed Terminal Library

Warnings

• breaking The behavior of `tparm` changed in version 1.2.1. It no longer persists dynamic variables between calls, aligning with `ncurses` versions >=6.3. Code relying on the prior persistence of dynamic variables will behave differently.
  Fix: Review `tparm` calls and ensure they do not rely on state persistence across invocations. Parameters should be explicitly passed for each call.
• breaking In version 1.2.1, a specific `tparm` pattern (`b'%p1%s'` with no arguments) now returns an empty string in Jinxed, whereas `ncurses` would return Null. Code expecting a Null value may encounter different behavior.
  Fix: Adjust code to handle an empty string return for `b'%p1%s'` with no arguments instead of Null, if this specific pattern was used.
• breaking Support for Python 3.4 was dropped in version 1.0.0.
  Fix: Upgrade to Python 3.5 or newer.
• gotcha In version 1.3.0, `jinxed.win32.get_term()` was updated to check if `ENABLE_VIRTUAL_TERMINAL_INPUT` is already enabled in the console before setting it. Previously, it would unconditionally enable it. This can affect Windows applications that relied on Jinxed always setting this mode.
  Fix: If your Windows application requires `ENABLE_VIRTUAL_TERMINAL_INPUT` to be explicitly set, ensure it is configured independently or verify its state before relying on Jinxed to activate it implicitly.
• gotcha Version 1.4.0 introduced approximately 100x improved response time for keyboard events and added support for mouse and resize events. While this is a significant performance and feature enhancement, applications sensitive to precise timing of keyboard events or that previously worked around the lack of mouse/resize support might need re-evaluation or could inadvertently expose new interaction possibilities.
  Fix: Test existing applications with `jinxed` 1.4.0 to ensure consistent behavior with the faster event loop. Consider leveraging the new mouse and resize event capabilities.

Install

• pip install jinxed Install stable version

Imports

• tigetstr

  from jinxed.terminfo import tigetstr

  For retrieving string capabilities from the terminfo database.
• tparm

  from jinxed.terminfo import tparm

  For instantiating parameterized terminfo strings.
• ConsoleInput

  from jinxed.win32 import ConsoleInput

  For advanced Windows console input handling (introduced in v1.4.0).

Quickstart

This quickstart demonstrates how to use `jinxed` to retrieve and apply terminfo capabilities like moving the cursor. It fetches terminal capabilities using `tigetstr` and then uses `tparm` to instantiate parameterized strings, which are then written to the console.

import os
from jinxed.terminfo import tigetstr, tparm

def main():
    # Get the terminal type from environment, default to 'xterm'
    term_type = os.environ.get('TERM', 'xterm')
    print(f"Using terminal type: {term_type}")

    # Get the 'cursor up' capability string
    cursor_up_cap = tigetstr('cuu1')
    if cursor_up_cap:
        print(f"'cursor up' capability: {cursor_up_cap!r}")
    else:
        print("'cursor up' capability not found for this terminal.")

    # Get and apply a parameterized capability, e.g., 'cursor address' (cup)
    # This moves the cursor to a specific row and column (0-indexed)
    cursor_address_cap = tigetstr('cup')
    if cursor_address_cap:
        # Move cursor to row 5, column 10 (0-indexed)
        # Note: tparm parameters are often 1-indexed in terminfo, but curses/jinxed often maps to 0-indexed.
        # Actual behavior may depend on specific terminal and capability.
        control_sequence = tparm(cursor_address_cap, 5, 10)
        if control_sequence:
            print(f"Moving cursor to (5,10): {control_sequence!r}")
            os.write(1, control_sequence) # Write directly to stdout's file descriptor
            os.write(1, b'Hello!\n')
    else:
        print("'cursor address' capability not found.")

if __name__ == '__main__':
    main()