This tutorial will walk you through the process of installing and using Oraide for the first time.
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
.
To install Oraide, run pip install oraide
, or download and install the latest release from PyPI.
First, get a tmux session up and running:
- Start a terminal session.
Start a new tmux session. Enter
tmux new-session -s 'my_session'
and pressEnter
. 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; runexit
at the command line, or, by default, pressCtrl + 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'sattach-session
command. Put the second terminal on your screen (e.g., your laptop's built-in display) and give your neck a rest.- Start a separate terminal session. This is the session you will use to send keystrokes to
my_session
. Start the Python interactive interpreter. Enter
python
and pressEnter
. 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. >>> _
oraide
At it's simplest, Oraide is a wrapper around tmux's send-keys
command. Let's give it a try.
In the Python interactive session, import Oraide. Enter
import oraide
and pressEnter
. It'll look like this:>>> import oraide
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.Next, send the
Enter
key tomy_session
. Type:>>> send_keys('my_session', 'Enter', literal=False)
and then press
Enter
. TheEnter
key is sent tomy_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 theEsc
key), but this can be quite surprising. Instead, Oraide defaults to treating the string literally. If you want to look up special keystrokes, setliteral
toFalse
(or, at least, something falsy).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 substituteEnter
fororaide.keys.enter
.
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 <sending_keystrokes>
. 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:
- 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.
The keys are sent one at a time, with a short delay between each, to simulate typing.
The enter
method does the same as teletype
, except the Enter
key is sent after the literal keys.
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.
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.