Tutorial

This tutorial will walk you through the process of installing and using Oraide for the first time.

Prerequisites

Oraide requires tmux 1.7 or later. Your system may already have tmux installed, or you may need to use your system’s package manager to install it. For example, to install tmux with APT, run apt-get install tmux. On Mac OS X, you can install tmux with Homebrew. To install tmux with Homebrew, run: brew install tmux.

Installation

To install Oraide, run pip install oraide, or download and install the latest release from PyPI.

Setting up

First, get a tmux session up and running:

  1. Start a terminal session.

  2. Start a new tmux session. Enter tmux new-session -s 'my_session' and press Enter. You should find yourself in a terminal session, as if you had just started. It’s a terminal session in a terminal session (yes, it’s a little confusing, but it’s easy to leave; run exit at the command line, or, by default, press Ctrl + b followed by the the & key).

    This is the session we’ll be controlling with Oraide.

    Note

    Don’t crane your neck! If your presentation is going to be on a large screen or projector that would be awkward for you to look at while you give your presentation, attach a second terminal to my_session with tmux’s attach-session command. Put the second terminal on your screen (e.g., your laptop’s built-in display) and give your neck a rest.

  3. Start a separate terminal session. This is the session you will use to send keystrokes to my_session.

  4. Start the Python interactive interpreter. Enter python and press Enter. It will look something like this:

    $ python
    Python 2.7.5 (default, Jun  9 2013, 16:41:37)
    [GCC 4.2.1 Compatible Apple LLVM 4.2 (clang-425.0.28)] on darwin
    Type "help", "copyright", "credits" or "license" for more information.
    >>> _
    

Sending keystrokes

At it’s simplest, Oraide is a wrapper around tmux’s send-keys command. Let’s give it a try.

  1. In the Python interactive session, import Oraide. Enter import oraide and press Enter. It’ll look like this:

    >>> import oraide
    
  2. Send some keys to the tmux session with the send_keys() function. It requires two parameters: a session name and a string of keys to send. Enter this:

    >>> oraide.send_keys('my_session', "echo 'Hello, World!'")
    

    and then press Enter. If you look at your tmux session, you’ll see the second parameter entered at the prompt, like this:

    $ echo 'Hello, World!'
    

    Note that the command is unexecuted, because we haven’t sent the Enter key yet.

  3. Next, send the Enter key to my_session. Type:

    >>> send_keys('my_session', 'Enter', literal=False)
    

    and then press Enter. The Enter key is sent to my_session.

    The send_keys() function accepts an optional keyword argument, literal. tmux can try to convert the names of keys into the keystrokes themselves (e.g., Escape to the Esc key), but this can be quite surprising. Instead, Oraide defaults to treating the string literally. If you want to look up special keystrokes, set literal to False (or, at least, something falsy).

    See also

    Remembering which strings convert to which keystrokes is annoying, so you can use attributes of the oraide.keys module instead of literal strings. Then you can substitute Enter for oraide.keys.enter.

Session management

While send_keys() is useful, it’s tedious to re-enter the session name every time. To alleviate that frustration, and introduce some more features, Oraide provides the Session class. Here’s a simple script that demonstrates its use:

from oraide import keys, Session

s = Session('my_session')

s.send_keys("echo 'Hello, World!'")
s.send_keys(keys.enter, literal=False)

The script is equivalent to the two send_keys calls made in the previous section. The Session.send_keys() method is just like the send_keys function, but the session name is no longer needed.

The Session class, by keeping the name of the session, allows for some special behavior, including the Session.teletype() and Session.enter() methods. Let’s take a look:

from oraide import keys, Session

s = Session('my_session')

s.teletype("echo 'Hello, World!'")
s.send_keys(keys.enter, literal=False)

s.enter("echo 'Look Ma, no hands!'")

The teletype method works like send_keys with two differences:

  1. Before the keys are sent, a prompt appears (in the terminal where the script is running, not the tmux session), so you can control the pacing of your presentation.

  2. The keys are sent one at a time, with a short delay between each, to simulate typing.

    It looks something like this (slowed for dramatic effect):

    _images/no-hands.gif

The enter method does the same as teletype, except the Enter key is sent after the literal keys.

Auto-advancement

By default, the teletype and enter methods prompt before sending keys to the session. Sometimes this is inconvenient. For example, you may want to narrate a longer sequence of steps without stopping. To suppress prompts, you can use the Session.auto_advance() context manager, like this:

from oraide import keys, Session

s = Session('my_session')

with s.auto_advance():
   s.teletype("echo 'Hello, World!'")
   s.send_keys(keys.enter, literal=False)

s.enter("echo 'Look Ma, no hands!'")

The commands inside the with statement are executed without prompting.

If you want to auto-advance all keys sent to a session, you can instantiate a Session object with enable_auto_advance=True.

Note

It’s unwise to auto-advance your entire presentation. Not only is it easier to practice shorter auto-advancing sequences, but you also give yourself room to respond to questions or repeat an important point.

Learning more

Now you’re ready to start using Oraide. For more detailed information about the API, see the API reference. If you’d like to see more examples, try the scripts in Oraide’s examples directory. If you have problems, see Oraide’s GitHub issues.