SendKeys

Overview

SendKeys is a Python module for Windows that can send one or more keystrokes or keystroke combinations to the active window.

SendKeys exports 1 function, SendKeys, and 1 exception, KeySequenceError.

SendKeys

SendKeys(keys, pause=0.05, with_spaces=False,
         with_tabs=False, with_newlines=False,
         turn_off_numlock=True)

Parameters

keys : str: A string of keys.
pause : float: The number of seconds to wait between sending each key or key combination.
with_spaces : bool: Whether to treat spaces as {SPACE}. If False, spaces are ignored.
with_tabs : bool: Whether to treat tabs as {TAB}. If False, tabs are ignored.
with_newlines : bool: Whether to treat newlines as {ENTER}. If False, newlines are ignored.
turn_off_numlock : bool: Whether to turn off NUMLOCK before sending keys.

KeySequenceError

SendKeys may throw KeySequenceError if an error is found when reading keys. SendKeys reads all keys before pressing any, so if an error is found, no keys will be pressed.

SendKeys takes a string specifying one or more keys to press. Most letter, number, and punctuation keys are represented by the corresponding characters, but the following keys and characters have special meaning:

Key	Meaning
`+`	SHIFT
`^`	CTRL
`%`	ALT

To apply one or more modifiers to a key, place it in front of that key. For example, here's how to get CONTROL + a:

^a

You may apply one or more modifiers to a group of keys, by putting the keys in parentheses. For example, the following holds SHIFT down while all 3 keys are pressed:

+(abc)

To use one of the modifier keys, escape it by surrounding it with curly braces { and }. For example, for a literal % instead of ALT:

{%}

All of the following must be escaped within curly braces:

+ ^ % ~ { } [ ]

Each character must be escaped individually. You may not do the following:

{%%}

Note

When possible, SendKeys will automatically press SHIFT for you. This easier for the programmer to read and write. For example, if you wish SendKeys to type ABC!!, rather than using one of the following:

+a+b+c+1+1
+(abc11)

you may use:

ABC!!

Key Codes

For keys which don't have a character representation, you must use a code. Here are the codes SendKeys recognizes:

Key	Code
BACKSPACE	{BACKSPACE}, {BS}, or {BKSP}
BREAK	{BREAK}
CAPS LOCK	{CAPSLOCK} or {CAP}
DEL or DELETE	{DELETE} or {DEL}
DOWN ARROW	{DOWN}
END	{END}
ENTER	{ENTER} or `~`
ESC	{ESC}
HELP	{HELP}
HOME	{HOME}
INS or INSERT	{INSERT} or {INS}
LEFT ARROW	{LEFT}
NUM LOCK	{NUMLOCK}
PAGE DOWN	{PGDN}
PAGE UP	{PGUP}
PRINT SCREEN	{PRTSC}
RIGHT ARROW	{RIGHT}
SCROLL LOCK	{SCROLLLOCK}
SPACE BAR	{PACE}
TAB	{TAB}
UP ARROW	{UP}
F1	{F1}
F2	{F2}
F3	{F3}
F4	{F4}
F5	{F5}
F6	{F6}
F7	{F7}
F8	{F8}
F9	{F9}
F10	{F10}
F11	{F11}
F12	{F12}
F13	{F13}
F14	{F14}
F15	{F15}
F16	{F16}
F17	{F17}
F18	{F18}
F19	{F19}
F20	{F20}
F21	{F21}
F22	{F22}
F23	{F23}
F24	{F24}
Keypad add	{ADD}
Keypad subtract	{SUBTRACT}
Keypad multiply	{MULTIPLY}
Keypad divide	{DIVIDE}
Left Windows(R)	{LWIN}
Right Windows(R)	{RWIN}

Modifiers maybe used with codes as well. For example, for CONTROL + SHIFT + HOME:

^+{HOME}

Repeating Keys

Here's the syntax for a repeating key:

{key count}

Where key may be one of the Key Codes or a character and count is the number of times to press the key.

Examples:

Sequence	Equivalent
`{ENTER 2}`	`{ENTER}{ENTER}`
`{o 3}`	`ooo`
`^{A 2}`	`^(AA)`

Examples

Hello World

In this example, SendKeys is used to type "Hello World!" in notepad.

import SendKeys
SendKeys.SendKeys("""
    {LWIN}
    {PAUSE .25}
    r
    Notepad.exe{ENTER}
    {PAUSE 1}
    Hello{SPACE}World!
    {PAUSE 1}
    %{F4}
    n
""")

Tic-Tac-Toe

In this example, SendKeys is used to play a game of Tic-Tac-Toe in notepad.

import os, sys, tempfile
from SendKeys import SendKeys

try:
    True
except NameError:
    True,False = 1,0

if __name__ == '__main__':

    # create file game will be saved to
    filename = tempfile.mktemp('.txt')
    print >> sys.stdout, "saving tic-tac-toe game to `%s`" % filename
    f = open(filename,'w')
    f.write('')
    f.close()

    # open notepad
    SendKeys("""{LWIN}rNotepad.exe{SPACE}"%(filename)s"{ENTER}{PAUSE 1}"""
        % {'filename': filename.replace('~','{~}')}, with_spaces=True)

    # draw board
    SendKeys("""\
   |   |
---+---+---
   |   |
---+---+---
   |   |  """.replace('+','{+}'),0.1, with_spaces=True, with_newlines=True)

   # play the game
    SendKeys("""\
    ^{HOME}
    {DOWN 2}{RIGHT 5}+{RIGHT}{PAUSE 1}x
    {LEFT 4}+{LEFT}+o
    {UP 2}{RIGHT 3}+{RIGHT}x
    {DOWN 4}+{LEFT}+(o)
    {LEFT 4}+{LEFT}x
    {RIGHT 7}{UP 4}+{RIGHT}O
    {DOWN 4}+{LEFT}x
    {UP 4}{LEFT 8}+{LEFT}+O
    {RIGHT 7}{DOWN 2}+{RIGHT 1}x
    ^s
    """, 0.1)

    # read game saved from notepad
    f = open(filename)
    output = f.read()
    f.close()

    assert output == """\
 O | x | O
---+---+---
 O | x | x
---+---+---
 x | O | x"""
    print 'Bad news: cat got the game'
    print "Good news: that's what we expected, so the test passed"

Command Line Usage

SendKeys may also be used as a script:

C:\>python SendKeys.py --help
SendKeys.py [-h] [-d seconds] [-p seconds] [-f filename] or [string of keys]

    -dN    or --delay=N   : N is seconds before starting
    -pN    or --pause=N   : N is seconds between each key
    -fNAME or --file=NAME : NAME is filename containing keys to send
    -h     or --help      : show help message

Here's a silly example:

C:\>python SendKeys.py "echo{SPACE}'Hello{SPACE}World!'{ENTER}"

C:\>echo 'Hello World!'
'Hello World!'

C:\>

Known Issues

If NUMLOCK is on when SendKeys is called, then certain keystroke combinations don't seem to work. For example, C + SHIFT + LEFT (or ^+{LEFT}) doesn't select text in notepad. Instead, the cursor is just moved one to the left as if SHIFT hadn't been pressed.

As a work-around, when you call SendKeys(), by default it turns off NUMLOCK, if it's on. You may disable this behavior by passing turn_off_numlock=False to SendKeys(). If NUMLOCK was turned off, it is turned back on before SendKeys() returns.