pydotool

A ydotool client implemented in Python. The aim of pydotool is to write automation scripts in an easy way.

Usage

• click event
• key event
• mouse move event
• type characters

How to Use

• Install ydotoold. you may install it from your package manager, or build it from source.

• Install pydotool. pip install python-ydotool

• Write your automation script. Call init once in your program to connect to ydotoold

import pydotool
pydotool.init()

If you use another ydotoold socket than the default one (/tmp/.ydotool_socket), you can provide it in environment variable YDOTOOL_SOCKET, or pass it to init()

pydotool.init("/run/ydotoold/socket")

How to Implement the Examples in ydotool

Switch to tty1 (Ctrl+Alt+F1), wait 2 seconds, and type some words:

import time

from pydotool import KEY_F1, KEY_LEFTALT, KEY_LEFTCTRL, key_combination, init, type_string

init()  # call only once before using pydotool

key_combination([KEY_LEFTCTRL, KEY_LEFTALT, KEY_F1])
time.sleep(2)
type_string("echo Hey guys. This is Austin.")

Close a window in graphical environment (Alt+F4):

from pydotool import KEY_F4, KEY_LEFTALT

key_combination([KEY_LEFTALT, KEY_F4])

Relatively move mouse pointer to -100,100:

from pydotool import mouse_move
mouse_move((100, 100))

Move mouse pointer to 100,100:

mouse_move((100, 100), True)

Mouse right click:

from pydotool import right_click

right_click()

Mouse repeating left click:

from pydotool import click_sequence, ClickEnum

click_sequence([ClickEnum.LEFT_CLICK] * 5)

stdin is not natively supported, but you can implement it with python stdin.

Advanced Usage

There is no delay in pydotool API after the last event emitted.

for i in range(5):
    left_click()
    if i != 4:
        time.sleep(0.025)

# above code is equivalent to
click_sequence([ClickEnum.LEFT_CLICK] * 5)

Customize the delay time:

# Each click event is combined with "press" and "release", so there are totally 10 ydotool events, and 9 delays between each two consecutive events.
# the 9 delays are 10ms, 20ms, ..., 90ms.
click_sequence([ClickEnum.LEFT_CLICK] * 5, delay_sequence=list(range(10, 100, 10)))

Complex key operations:

# Ctrl+K and Ctrl+D without releasing Ctrl
key_seq([(KEY_LEFTCTRL, DOWN), (KEY_K, DOWN), (KEY_K, UP), (KEY_D, DOWN), (KEY_D, UP), (KEY_LEFTCTRL, UP)])

Control the press time when typing:

# Type "abcde", but hold 1 sec for each character.
# Note that long press may generate more content than expected.
type_string("abcde", hold_delay_ms=1000, each_char_delay_ms=20)
# possible output: 
# aaaaaaaaaaaabbbbbbbbbbbccccccccccccddddddddddddeeeeeeeeeeee

Long press key combination:

# Press Alt+F4 for 3 secs. Can close most of the apps. Not recommended to try this.
key_combination([KEY_LEFTALT, KEY_F4], press_ms=3000)

Using the low level API to send event:

# directly send an event using uinput_emit()
uinput_emit(EV_REL, REL_Y, 100, True)  # move 100 in y direction