xcontroller

xcontroller is a Python library for developing X11 automation scripts. It includes functionality for controlling the window manager, the keyboard, and the mouse.

It is based on the following projects:

pyewmh by Julien Pagès: The functionality for controlling the window manager and windows, like getting the desktop size or setting the active window, are taken from this project. The code has only been refactored to follow Python style naming and some type hints were modified.

pynput by Moses Palmér: The keyboard and mouse controllers were adapted from this project. A lot of the capabilities of pynput have been left out, most importantly support for Windows and MacOS, listeners, and thread safety. Type hints have been improved.

python-xvfb by Jonathan Ultis: The function for starting an Xvfb server was taken from this project with only some minor modifications.

Usage examples

• get the desktop geometry

  from xcontroller.ewmh import WMController
  
  wm = WMController()
  width, height = wm.get_desktop_geometry()
  

• find a shell window and raise it

  from xcontroller.ewmh import WMController
  
  wmc = WMController()
  for window in wmc.get_client_list():
      if "Shell" in window.get_wm_name():
          window.raise_window()
  

• press and release keys on the keyboard

  from xcontroller.keyboard import KeyboardController, SpecialKey
  
  kc = KeyboardController()
  
  kc.tap("x")
  
  kc.press(SpecialKey.ENTER)
  kc.release(SpecialKey.ENTER)
  
  with kc.pressed(SpecialKey.CTRL):
      kc.tap("s")
  

• move the mouse pointer and click the right button

  from xcontroller.mouse import MouseController, Button
  
  mc = MouseController()
  
  mc.move(800, 500)
  mc.click(Button.RIGHT)
  

• start an 1920x1080x24 Xvfb server on display 42

  from xcontroller.xvfb import start_xvfb
  
  process = start_xvfb(42, 1920, 1080, 24)