xcontroller 0.1

Library for controlling an X desktop Environment.

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 geometry 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:

Note: All controllers take a display parameter to which they connect. If no display parameter is given, they will connect to the default display.

• get the desktop geometry:

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

• find a window and raise it:

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

• Press and release keys on the keyboard:

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

• Start an Xvfb server:

  from xcontroller.xvfb import start_xvfb
  from pathlib import Path
  
  start_xvfb(Path("/usr/bin/Xvfb"), 1920, 1080, 24)

  Note: If no display number is given, this will choose a random number and export the DISPLAY environment variable (unless otherwise instructed).