Skip to content

Add KDE Plasma 6 Wayland backend using KWin scripting - #120

Open
samaral79 wants to merge 2 commits into
Kalmat:masterfrom
samaral79:kde-wayland
Open

samaral79 wants to merge 2 commits into
Kalmat:masterfrom
samaral79:kde-wayland

Conversation

@samaral79

Copy link
Copy Markdown

Summary

Adds a KDE Plasma 6 Wayland backend. Today, on a KDE Wayland session, the Linux backend goes down the Wayland path, calls org.gnome.Shell.Eval and fails (getAllTitles() raises CalledProcessError on Fedora 44 / Plasma 6.8). X11 calls through XWayland only see XWayland windows, so native Wayland apps (Dolphin, KCalc, Firefox, ...) are invisible.

On KDE the compositor can be scripted. The new backend loads a small KWin script through KWin's D-Bus scripting interface (org.kde.kwin.Scripting.loadScript). The script reads or changes the requested window(s) and sends the result back with callDBus() to a temporary D-Bus method we listen on. Then the script is unloaded. This works for all windows, including native Wayland ones, and each call takes a few ms.

Changes

  • src/pywinctl/_pywinctl_linux_kwin.py: new KWinWindow(BaseWindow) and the module-level functions, mirroring _pywinctl_linux.py. Window handles are KWin internal ids (UUID strings).
  • _main.py: on Linux, picks the KWin backend when XDG_SESSION_TYPE=wayland, XDG_CURRENT_DESKTOP contains KDE and KDE_SESSION_VERSION >= 6. Everything else (X11, GNOME, Plasma 5) keeps the current backend. PYWINCTL_LINUX_BACKEND=x11|kwin forces one backend.
  • New Linux-only dependency jeepney (sys_platform == 'linux'). It is pure Python with no dependencies (a ~49 KB wheel), and it is only imported when the KWin backend is actually used. If it is missing, a clear KWinError explains how to install it. Environment markers can't detect the desktop, so it's installed on all Linux systems. Shelling out to gdbus (as the GNOME path does) isn't enough here, because we need to receive a D-Bus call from KWin.
  • uv.lock: only adds jeepney (+11 lines, lock format unchanged). mypy.ini: follow_untyped_imports for jeepney, like the objc entries.
  • tests/test_kwin_backend.py: a plain script, like test_pywinctl.py. It tests backend selection anywhere on Linux, and runs live tests (with a kitty window) only inside a Plasma 6 Wayland session.
  • README / CHANGES: documented.

Wayland limitations (documented)

  • hide() minimizes the window.
  • sendBehind() keeps the window below the others; it can't go behind the desktop.
  • acceptInput() and setParent() aren't supported.
  • Resizing is asynchronous because the client must accept the new size, so use wait=True to confirm it.

Testing

  • KDE Plasma 6.8 Wayland (Fedora 44):
    • tests/test_pywinctl.py's basic_test() passes in full against a kitty window, including the watchdog callbacks.
    • tests/test_kwin_backend.py passes.
    • Python 3.9 and 3.14, with jeepney 0.8.0 and 0.9.0.
  • Linux X11: I replicated the CI tests job in an Ubuntu 24.04 container (Xvfb + openbox + gedit, uv sync --locked). The result is identical before and after this change.
  • ruff (0.15.16 from the lock): all checks pass.
  • mypy (mypy ., Python 3.9 and 3.14, --platform linux/win32/darwin): same results as master.
  • Packaging: the wheel is still py3-none-any. Resolving dependencies for Windows/macOS doesn't pull jeepney.
  • Not tested: real Windows/macOS machines (the only change there is inside the sys.platform == "linux" branch) and a real Plasma 5 session (only the selection logic was tested).

🤖 Generated with Claude Code

On Wayland, X11 calls only see XWayland windows, and on KDE the current
Wayland code path calls org.gnome.Shell and fails. This adds a backend that
loads small KWin scripts through KWin's D-Bus scripting interface; the script
reads or changes the requested windows and sends the result back with
callDBus(). It works for every window, including native Wayland ones.

- New _pywinctl_linux_kwin module (KWinWindow + module functions)
- Selected automatically on Wayland + KDE + KDE_SESSION_VERSION >= 6;
  PYWINCTL_LINUX_BACKEND=x11|kwin forces a backend
- New Linux-only dependency: jeepney (pure Python D-Bus)
- tests/test_kwin_backend.py: backend selection + live tests on KWin

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Avasam

Avasam commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator

There will be some slight conflict with #118 , But I believe both PRs will work hand in hand.
#120 adds support for Wayland on KDE Plasma
#118 Fixes XWayland support for all Desktop Environments

Comment thread mypy.ini Resolved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants