API reference

Oraide provides a set of conveniences around tmux’s send-keys command. For more information about how tmux actually works, please see tmux’s man page.

oraide

oraide.send_keys(session, keys, literal=True)

Send keys to a tmux session. This function is a wrapper around tmux’s send-keys command.

If literal is False, tmux will attempt to convert keynames such as Escape or Space to their single-key equivalents.

Parameters:
  • session – name of a tmux session
  • keys – keystrokes to send to the tmux session
  • literal – whether to prevent tmux from looking up keynames
class oraide.Session(session, enable_auto_advance=False, teletype_delay=None)

A session to which to send keys. This function allows for the deduplication of session names when repeatedly sending keystrokes the same session.

Parameters:
  • session – the name of a tmux session
  • enable_auto_advance – whether to send keystrokes to the session immediately, or wait for confirmation, on certain methods
  • teletype_delay (int) – the delay between keystrokes for the teletype() method (for overriding the default of 90 milliseconds)
auto_advance()

Return a context manager that disables prompts before sending keystrokes to the session. For example:

session.enter('vim some_file.txt')    # prompt first
with session.auto_advance():          # disables prompts
    session.teletype('jjji')
    session.enter('Hello, World!', after=keys.escape)
session.enter(':x')                   # prompt first
enter(keys=None, teletype=True, after='Enter')

Type keys, then press Enter.

By default, typing character-by-character is enabled with the teletype parameter.

Note

If auto-advancing is disabled, then a confirmation prompt appears before keystrokes are sent to the session.

Parameters:
  • keys – the keystroke to be sent to the to the session. These keys may only be literal keystrokes, not keynames to be looked up by tmux.
  • teletype – whether to enable simulated typing
  • after – additional keystrokes to send to the session with literal set to False (typically for appending a special keys from oraide.keys, like the default, Enter)
send_keys(keys, literal=True)

Send each literal character in keys to the session.

Parameters:
  • keys – literal keystrokes to send to the session
  • literal – whether to prevent tmux from looking up keynames

See also

send_keys()

teletype(keys, delay=90)

Type keys character-by-character, as if you were actually typing them by hand.

The delay parameter adds time between each keystroke for verisimilitude. The actual time between keystrokes varies up to ten percent more or less than the nominal value. The default, 90 milliseconds, approximates a fast typist.

Note

If auto-advancing is disabled, then a confirmation prompt appears before keystrokes are sent to the session.

Parameters:
  • keys – the literal keys to be typed
  • delay (int) – the nominal time between keystrokes in milliseconds.

Exceptions

If tmux’s send-keys command ends with an error status code, an exception is raised.

exception oraide.TmuxError(returncode, cmd, output=None)

The command sent to tmux returned a non-zero exit status. This is an unrecognized tmux error.

This exception type inherits from subprocess.CalledProcessError, which adds returncode, cmd, and output attributes.

exception oraide.ConnectionFailedError(returncode, cmd, output=None)

Bases: oraide.TmuxError

The tmux server connection failed (often because the server was not running at the time the command was sent).

exception oraide.SessionNotFoundError(returncode, cmd, output=None, session=None)

Bases: oraide.TmuxError

The tmux session was not found (but a connection to tmux server was established).

This exception type adds another attribute, session, for your debugging convenience.

oraide.keys

This module provides shortcuts for sending special keystrokes to tmux sessions. The functions and constants are typically used with oraide.Session.send_keys(), or the after parameter on certain oraide.Session methods.

The constants of this module are provided as a Pythonic substitute for the strings used in tmux’s keyname lookup table. For example, to send a backspace key, the string 'BSpace' may be replaced with a reference to oraide.keys.backspace. The following keys are provided:

  • backspace
  • end
  • enter
  • escape
  • home
  • page_down
  • page_up
  • space
  • tab
  • up
  • down
  • left
  • right

as well as the function keys f1 through f20.

oraide.keys.alt(key)

Make a string that tmux will parse as the alt key (Alt) and key pressed at the same time.

Note

The key parameter is case-sensitive. If key is uppercase, it’s equivalent to entering Shift and the key.

>>> from oraide.keys import alt
>>> alt('a')  # alt + a
'A-a'
>>> alt('A')  # alt + shift + a
'A-A'
oraide.keys.command(key)

Make a string that tmux will parse as the command key (also known as the meta, super, cmd, Apple, and Windows key) and key pressed at the same time.

Note

The key parameter is case-sensitive. If key is uppercase, it’s equivalent to entering Shift and the key.

>>> from oraide.keys import command
>>> command('a')  # command + a
'M-a'
>>> command('A')  # command + shift + a
'M-A'
oraide.keys.control(key)

Make a string that tmux will parse as the control key (Ctrl) and key pressed at the same time.

Note

The key parameter is case-sensitive. If key is uppercase, it’s equivalent to entering Shift and the key.

>>> from oraide.keys import control
>>> control('a')  # ctrl + a
'C-a'
>>> control('A')  # ctrl + shift + a
'C-A'