Files
hyprland-headless-stream-pl…/tests/pointer/test_vendored_protocol.py
T
HermenixandClaude Opus 5 f931858f30 Stage 1: the driver learns to type
`zwp_virtual_keyboard_v1`, spoken by the process that already speaks
`zwlr_virtual_pointer_v1`. One device for the seat, one keymap uploaded
once, keysym names on our socket and evdev codes only on the Wayland
request -- the division buttons.py already draws.

keymap.py is the new seam, and it holds the three decisions that have a
wrong version which looks right:

  * A capital is the MASK, not a synthetic Shift keycode. Hyprland's
    virtual keyboard never runs updateXkbStateWithKey, so a virtual
    KEY_LEFTSHIFT changes no modifier state at all -- and sending both
    is how a toolkit applies Shift twice.
  * A modifier is whatever the keymap says is one, measured by pressing
    each key in a throwaway xkb state. Not a name list: `@` on `de` is a
    level-three symbol, and a Shift-only special case types the wrong
    character. (The measured set is also smaller than the canonical one,
    because no keycode on us/pc105 carries Meta or Hyper.)
  * A lock is not a modifier. Caps_Lock reports a *locked* mask, so
    `type` refuses while it is held rather than guessing the case.

The whole string resolves before anything is emitted, and every refusal
names the scalar INDEX, never the character: these messages reach the
driver's log and the string is a password as often as not.

Folding in the review's changes 1, 2, 3 and 6:

  1 a Rejected now carries a `kind`. A bad keysym or an unmappable
    character is `invalid_argument`; a missing keyboard global is
    `refused`. Without the token the broker would have to tell exit 2
    from exit 10 by reading English, and _drive maps every `ok: false`
    to driver_refused today.
  2 the keymap `size` on the wire includes the trailing NUL, and the fd
    outlives a roundtrip rather than a flush. Hyprland mmaps exactly
    that many bytes and hands the pointer to xkb_keymap_new_from_string.
  3 release_all lifts buttons, then keys in press order, then zeroes the
    mask -- and the mask only if something set it, so a compositor with
    no keyboard global still gets its buttons lifted. One release_all is
    the whole of expiry; an exception in the key half would abandon it.
  6 `key` and `type` never call _aimed(). A keyboard has no output, and
    one test deliberately never warps so that stays true.

Also: `--xkb-layout/-model/-variant/-options`, compiled BEFORE any
Wayland call so a bad layout is exit 2 rather than exit 10; a comma in
the layout refused outright, because v1 always sends group 0 and
xkbcommon would hand back a second group nothing could reach; the
keymap uploaded after connect and before listen, with one
modifiers(0,0,0,0) after it; and xkbcommon as a hard, non-optional
dependency -- an optional one would let test_keymap.py skip, and the
unmappable-character path is the one that must not rot.

  nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
  549 passed in 25.70s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 03:39:00 +00:00

202 lines
8.2 KiB
Python

"""The vendored protocol and the packaging around it.
The whole point of slice D is that coordinates are *output-local*, and the only
thing that makes them so is ``create_virtual_pointer_with_output``, which exists
at version 2 of ``zwlr_virtual_pointer_manager_v1`` and not at version 1. So
the version is asserted here, cheaply, on the generated source — a regeneration
against an older XML would otherwise be a silent downgrade of the one guarantee
the slice exists to provide.
The pywayland import is checked when pywayland is present and skipped when it is
not: the dev shell has no pywayland, the built package does, and this file is
run in both.
"""
from __future__ import annotations
import importlib.util
from pathlib import Path
import pytest
HAVE_PYWAYLAND = importlib.util.find_spec("pywayland") is not None
# Located through the import system, not through a path relative to this file,
# so the suite is the same whether it runs in a checkout or against the
# installed package in a build sandbox.
_spec = importlib.util.find_spec("hhstream_pointer")
assert _spec is not None and _spec.origin, "hhstream_pointer is not importable"
PACKAGE = Path(_spec.origin).parent
PROTOCOL_DIR = PACKAGE / "_protocol/wlr_virtual_pointer_unstable_v1"
MANAGER = PROTOCOL_DIR / "zwlr_virtual_pointer_manager_v1.py"
KEYBOARD_DIR = PACKAGE / "_protocol/virtual_keyboard_unstable_v1"
KEYBOARD_MANAGER = KEYBOARD_DIR / "zwp_virtual_keyboard_manager_v1.py"
KEYBOARD = KEYBOARD_DIR / "zwp_virtual_keyboard_v1.py"
#: Only present in a checkout; a build sandbox gets the test directory alone.
PYPROJECT = Path(__file__).resolve().parents[2] / "pyproject.toml"
def test_the_generated_protocol_is_vendored():
assert (PROTOCOL_DIR / "__init__.py").is_file()
assert MANAGER.is_file()
assert (PROTOCOL_DIR / "zwlr_virtual_pointer_v1.py").is_file()
# Every vendored file is scanner output; a hand-edit should be noticed.
for path in PROTOCOL_DIR.glob("*.py"):
assert path.read_text().startswith("# This file has been autogenerated")
def test_the_manager_is_version_2_with_the_output_request():
source = MANAGER.read_text()
assert " version = 2\n" in source
assert "def create_virtual_pointer_with_output(self, seat" in source
assert "output: WlOutput | None" in source
def test_the_shim_resolves_the_generated_relative_import():
assert "from ..wayland import WlOutput" in MANAGER.read_text()
shim = (PROTOCOL_DIR.parent / "wayland.py").read_text()
assert "from pywayland.protocol.wayland import WlOutput, WlSeat" in shim
@pytest.mark.skipif(not PYPROJECT.is_file(), reason="not running from a checkout")
def test_pyproject_declares_the_entry_point_and_the_dependencies():
pyproject = PYPROJECT.read_text()
assert 'hhstream-pointer = "hhstream_pointer.__main__:main"' in pyproject
assert "pywayland" in pyproject
# Not optional, and the comment beside it in pyproject.toml says why: an
# optional xkbcommon would let test_keymap.py skip, and the
# unmappable-character path is the one that must not rot.
assert "xkbcommon" in pyproject
# -- the virtual keyboard --------------------------------------------------
def test_the_keyboard_protocol_is_vendored_beside_the_pointer_one():
assert (KEYBOARD_DIR / "__init__.py").is_file()
assert KEYBOARD_MANAGER.is_file()
assert KEYBOARD.is_file()
for path in KEYBOARD_DIR.glob("*.py"):
assert path.read_text().startswith("# This file has been autogenerated")
def test_the_keyboard_manager_is_version_1_with_the_seat_only_request():
source = KEYBOARD_MANAGER.read_text()
assert 'name = "zwp_virtual_keyboard_manager_v1"' in source
assert " version = 1" in source
# Seat and nothing else: a virtual keyboard has no output argument, which
# is why `ops.py` must not route a key through `_aimed()`.
assert "def create_virtual_keyboard(self, seat: WlSeat)" in source
assert "WlOutput" not in source
def test_the_keyboard_carries_keymap_key_and_modifiers():
source = KEYBOARD.read_text()
assert 'name = "zwp_virtual_keyboard_v1"' in source
assert " version = 1" in source
assert "def keymap(self, format: int, fd: int, size: int)" in source
assert "def key(self, time: int, key: int, state: int)" in source
assert (
"def modifiers(self, mods_depressed: int, mods_latched: int, "
"mods_locked: int, group: int)" in source
)
# The keymap fd really is an fd on the wire, not a number we invented.
assert "ArgumentType.FileDescriptor" in source
# No frame, and there is nothing to add one from: `ops.py` says why a key
# queued until one would never arrive.
assert "def frame(" not in source
def test_the_integers_the_xml_names_but_does_not_define_live_in_our_code():
"""The one real cost of using Hyprland's copy of the XML.
It names `keymap_format` and `key_state` in the request descriptions and
defines neither enum, so the scanner emits no `IntEnum` for either. Both
are therefore written down with a citation, and this test is what notices
if a future regeneration against a *complete* XML makes them redundant --
at which point they should be deleted rather than left to drift.
"""
source = KEYBOARD.read_text()
assert "keymap_format" in source, "the description still refers to it"
assert "class keymap_format" not in source, "...and still does not define it"
assert "class key_state" not in source
from hhstream_pointer import buttons
from hhstream_pointer.keymap import XKB_V1
assert XKB_V1 == 1
# `wl_pointer.button_state` and `wl_keyboard.key_state` agree on these two,
# which is why there is one table rather than a second that can drift.
assert buttons.STATES["up"] == 0
assert buttons.STATES["down"] == 1
def test_the_shim_resolves_the_keyboard_relative_import():
assert "from ..wayland import WlSeat" in KEYBOARD_MANAGER.read_text()
@pytest.mark.skipif(
not HAVE_PYWAYLAND,
reason="pywayland is not in this environment (it is in the built package)",
)
def test_the_protocol_binds_against_the_installed_pywayland():
from hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1 import (
ZwlrVirtualPointerManagerV1,
ZwlrVirtualPointerV1,
)
assert ZwlrVirtualPointerManagerV1.version == 2
assert ZwlrVirtualPointerV1.version == 2
assert hasattr(
ZwlrVirtualPointerManagerV1.proxy_class, "create_virtual_pointer_with_output"
)
@pytest.mark.skipif(
not HAVE_PYWAYLAND,
reason="pywayland is not in this environment (it is in the built package)",
)
def test_the_keyboard_protocol_binds_against_the_installed_pywayland():
from hhstream_pointer._protocol.virtual_keyboard_unstable_v1 import (
ZwpVirtualKeyboardManagerV1,
ZwpVirtualKeyboardV1,
)
assert ZwpVirtualKeyboardManagerV1.name == "zwp_virtual_keyboard_manager_v1"
assert ZwpVirtualKeyboardManagerV1.version == 1
assert ZwpVirtualKeyboardV1.version == 1
for request in ("keymap", "key", "modifiers", "destroy"):
assert hasattr(ZwpVirtualKeyboardV1.proxy_class, request)
assert hasattr(ZwpVirtualKeyboardManagerV1.proxy_class, "create_virtual_keyboard")
@pytest.mark.skipif(
not HAVE_PYWAYLAND,
reason="pywayland is not in this environment (it is in the built package)",
)
def test_the_backend_binds_the_keyboard_manager_at_version_1_and_survives_its_absence():
from hhstream_pointer.backend import KEYBOARD_MANAGER_VERSION, WaylandSink
assert KEYBOARD_MANAGER_VERSION == 1
# A sink that never connected has no keyboard and says so rather than
# raising: `ops.release_all` asks this question precisely so that a
# compositor with no keyboard global still gets its buttons lifted.
sink = WaylandSink(Path("/nonexistent"))
assert sink.has_keyboard() is False
@pytest.mark.skipif(
not HAVE_PYWAYLAND,
reason="pywayland is not in this environment (it is in the built package)",
)
def test_the_backend_refuses_a_version_1_manager():
from hhstream_pointer.backend import MANAGER_VERSION, ManagerTooOld
assert MANAGER_VERSION == 2
message = str(ManagerTooOld(1))
assert "version 1" in message
assert "create_virtual_pointer_with_output" in message
assert "Refusing to start" in message