Embedding in Python Applications

vncdotool is built with the Twisted framework, as such it best intergrates with other Twisted Applications Rewriting your application to use Twisted may not be an option, so vncdotool provides a compatibility layer. It uses a separate thread to run the Twisted reactor and communicates with the main program using a threadsafe Queue.

To use the synchronous API you can do the following:

from vncdotool import api
client = api.connect('vncserver', password=None)

The first argument passed to the connect method is the VNC server to connect to, and it needs to be in the format address[:display|::port]. For example:

# connect to 192.168.1.1 on default port 5900
client = api.connect('192.168.1.1', password=None)

# connect to localhost on display :3 (port 5903)
client = api.connect('localhost:3', password=None)

# connect to myvncserver.com on port 5902 (two colons needed)
client = api.connect('myvncserver.com::5902', password=None)

You can then call any of the methods available on vncdotool.client.VNCDoToolClient and they will block until completion. For example:

client.captureScreen('screenshot.png')
client.keyPress('enter')
client.expectScreen('login_success.png', maxrms=10)

It is possible to set a per-client timeout in seconds to prevent calls from blocking indefinitely.

client.timeout = 10
try:
    client.captureScreen('screenshot.png')
except TimeoutError:
    print('Timeout when capturing screen')

In case of too many timeout errors, it is recommended to reset the client connection via the disconnect and connect methods.

The vncdotool.client.VNCDoToolClient supports the context manager protocol.

with api.connect('vnchost:display') as client:
    client.captureScreen('screenshot.png')

The synchronous API can be used to automate the starting of a Virtual Machine or other application:

vmtool.start('myvirtualmachine.img')
client.connect('vmaddress::5950')
client.expectScreen('booted.png')
for k in 'username':
    client.keyPress(k)
client.keyPress('enter')
for k in 'password':
    client.keyPress(k)
client.keyPress('enter')
client.expectScreen('loggedin.png')
client.disconnect()

# continue with your testing session or other work