Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,19 @@ All notable changes to python-libei are recorded here. The format follows

## [Unreleased]

### Changed

- **Ruff now enforces pydocstyle plus the same complexity/simplification/
argument rules pyguitest and pyguitest-recorder already gate on** (`D`,
`C4`, `SIM`, `RET`, `ARG`, `C901`, ceiling 15) -- this repo's config had
never turned them on. Closing the gap surfaced two real things: eight
`try`/`except OSError: pass` blocks (tests plus two `__del__` methods in
`portal.py`) rewritten as `contextlib.suppress(OSError)`, and ~40 missing
docstrings, mostly one-line additions to the per-event dataclasses in
`ei.py`/`eis.py` naming the numbering scheme a field uses (e.g.
`KeyEvent.key` is a Linux `KEY_*` code, matching `Device.keyboard_key()`)
since that wasn't stated on the class itself.

### Fixed

- **`_wait_for_signal` (used by `InputCaptureSession.wait_for_activation`/
Expand Down
33 changes: 32 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -87,8 +87,39 @@ select = [
"E", "W", # pycodestyle
"F", # pyflakes
"I", # isort
"UP", # pyupgrade
"D", # pydocstyle
"B", # bugbear
"UP", # pyupgrade
"C4", # comprehensions
"SIM", # simplification
"RET", # return consistency
"ARG", # unused arguments
"C901", # cyclomatic complexity
]
ignore = [
"D203", # incompatible with D211; keep no blank line before class docstring
"D213", # incompatible with D212; keep the summary on the first line
"D401", # properties read better as noun phrases than imperatives
"D105", # __enter__/__exit__ and friends document themselves
]

[tool.ruff.lint.mccabe]
# pyguitest's ceiling; python-libei's own worst case (InputCaptureSession.
# negotiate(), forking on portal version) sits at 14, just under it. A
# ceiling on what gets added, not a claim everything else is close to it.
max-complexity = 15

[tool.ruff.lint.pydocstyle]
convention = "pep257"

[tool.ruff.lint.per-file-ignores]
# Tests use fakes with deliberately unused arguments and multi-with blocks
# that read better nested; matching pyguitest's/pyguitest-recorder's own
# per-file-ignores for the same reasons.
"tests/*" = [
"ARG001", "ARG002", "ARG003", "ARG005", # fakes accept arguments they ignore
"SIM117", # nested with-blocks read better in tests
"D100", "D101", "D102", "D103", "D104", "D107",
]

[tool.mypy]
Expand Down
7 changes: 5 additions & 2 deletions src/libei/_capi/__init__.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
"""Low-level ctypes bindings. Not part of the public API -- use
``libei.ei``, ``libei.eis`` and ``libei.oeffis`` instead."""
"""Low-level ctypes bindings.

Not part of the public API -- use ``libei.ei``, ``libei.eis`` and
``libei.oeffis`` instead.
"""

from . import libei, libeis, liboeffis

Expand Down
86 changes: 71 additions & 15 deletions src/libei/ei.py
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ class Error(Exception):
"""

def __init__(self, message: str, errno: int | None = None) -> None:
"""Record the failure message and, where libei reported one, errno."""
super().__init__(message)
self.message = message
self.errno = errno
Expand Down Expand Up @@ -199,6 +200,12 @@ class _LogPriority(enum.IntEnum):

@dataclasses.dataclass(frozen=True, slots=True)
class XkbModifiersEvent:
"""XKB modifier state from a KEYBOARD_MODIFIERS event.

``depressed``/``latched``/``locked`` are XKB's own mod-state bitmasks;
``group`` is the active keyboard layout group.
"""

depressed: int
latched: int
locked: int
Expand All @@ -207,66 +214,103 @@ class XkbModifiersEvent:

@dataclasses.dataclass(frozen=True, slots=True)
class KeyEvent:
"""Key code and press state from a KEYBOARD_KEY event.

``key`` is a Linux ``KEY_*`` code, the same numbering
:meth:`Device.keyboard_key` sends.
"""

key: int
is_press: bool


@dataclasses.dataclass(frozen=True, slots=True)
class ButtonEvent:
"""Button code and press state from a BUTTON_BUTTON event.

``button`` is a Linux ``BTN_*`` code, the same numbering
:meth:`Device.button` sends.
"""

button: int
is_press: bool


@dataclasses.dataclass(frozen=True, slots=True)
class PointerEvent:
"""Relative motion deltas, in logical pixels, from a POINTER_MOTION event."""

dx: float
dy: float


@dataclasses.dataclass(frozen=True, slots=True)
class PointerAbsoluteEvent:
"""Absolute position from a POINTER_MOTION_ABSOLUTE event.

In the logical pixel space of the :class:`Region` the emitting device
covers -- see :meth:`Event.pointer_absolute_event`.
"""

x: float
y: float


@dataclasses.dataclass(frozen=True, slots=True)
class ScrollEvent:
"""Smooth scroll deltas from a SCROLL_DELTA event."""

dx: float
dy: float


@dataclasses.dataclass(frozen=True, slots=True)
class ScrollDiscreteEvent:
"""Detent scroll deltas (120 per detent) from a SCROLL_DISCRETE event."""

dx: int
dy: int


@dataclasses.dataclass(frozen=True, slots=True)
class ScrollStopEvent:
"""Which axes stopped scrolling, from a SCROLL_STOP/SCROLL_CANCEL event."""

stop_x: bool
stop_y: bool


@dataclasses.dataclass(frozen=True, slots=True)
class TouchEvent:
"""Touch id and position from a TOUCH_DOWN or TOUCH_MOTION event."""

touchid: int
x: float
y: float


@dataclasses.dataclass(frozen=True, slots=True)
class TouchUpEvent:
"""Touch id and cancellation flag from a TOUCH_UP event.

See :meth:`Event.touch_up_event` for when ``is_cancel`` is trustworthy.
"""

touchid: int
is_cancel: bool


@dataclasses.dataclass(frozen=True, slots=True)
class TextUtf8Event:
"""UTF-8 text carried by a TEXT_UTF8 event."""

text: str


@dataclasses.dataclass(frozen=True, slots=True)
class TextKeysymEvent:
"""Keysym and press state from a TEXT_KEYSYM event."""

keysym: int
is_press: bool

Expand Down Expand Up @@ -545,9 +589,10 @@ def stop_emulating(self) -> Device:
return self

def frame(self, timestamp: int | None = None) -> Device:
"""Commit the events queued since the last frame as one logical
hardware event. ``timestamp`` defaults to the context's current
time."""
"""Commit the events queued since the last frame as one logical hardware event.

``timestamp`` defaults to the context's current time.
"""
if timestamp is None:
timestamp = _capi.libei.now(_capi.libei.device_get_context(self))
_capi.libei.device_frame(self, timestamp)
Expand All @@ -564,8 +609,10 @@ def pointer_motion_absolute(self, x: float, y: float) -> Device:
return self

def button(self, button: int, is_press: bool) -> Device:
"""Queue a button press or release. ``button`` is a Linux
``BTN_*`` code (e.g. ``0x110`` for ``BTN_LEFT``)."""
"""Queue a button press or release.

``button`` is a Linux ``BTN_*`` code (e.g. ``0x110`` for ``BTN_LEFT``).
"""
_capi.libei.device_button_button(self, button, is_press)
return self

Expand Down Expand Up @@ -760,8 +807,11 @@ def __repr__(self) -> str:

@property
def event_type(self) -> EventType | int:
"""The event's type, or a raw int for a value newer than this
package's :class:`EventType` table -- see its docstring."""
"""The event's type.

Returns a raw int for a value newer than this package's
:class:`EventType` table -- see its docstring.
"""
raw = _capi.libei.event_get_type(self)
try:
return EventType(raw)
Expand Down Expand Up @@ -1009,11 +1059,14 @@ class Context(CObject):
_wrappable = False

def __init__(self, pointer: int, *, _adopt: bool = False) -> None:
# _adopt is accepted and forwarded for signature consistency with
# CObject, but with _wrappable = False, _get_or_create() never
# actually reaches this constructor -- Context (and Sender/
# Receiver) are always built directly via cls(cls._new()) in
# create_for_fd()/create_for_socket().
"""Wrap a freshly created ``struct ei *`` and arm its log handler.

_adopt is accepted and forwarded for signature consistency with
CObject, but with _wrappable = False, _get_or_create() never
actually reaches this constructor -- Context (and Sender/
Receiver) are always built directly via cls(cls._new()) in
create_for_fd()/create_for_socket().
"""
super().__init__(pointer, _adopt=_adopt)
self._name: str | None = None
_capi.libei.log_set_handler(self, _log_handler)
Expand Down Expand Up @@ -1081,7 +1134,8 @@ def set_fd(self: _ContextT, fd: IO[bytes] | int) -> _ContextT:
"""Use an already-connected socket as the transport.

libei takes ownership of a raw int fd and closes it itself; a file
object is duplicated first, so the caller's own object stays valid."""
object is duplicated first, so the caller's own object stays valid.
"""
# ei_setup_backend_fd() takes ownership of the fd and will close it
# itself. A raw int is assumed to already be one the caller is
# handing off (matching what eis.Eis.add_client()/oeffis.eis_fd
Expand All @@ -1099,7 +1153,8 @@ def set_socket(self: _ContextT, path: Path | None) -> _ContextT:
"""Connect to an EIS socket by path.

``None`` uses ``$LIBEI_SOCKET``; a relative path is resolved
against ``$XDG_RUNTIME_DIR``."""
against ``$XDG_RUNTIME_DIR``.
"""
encoded = os.fspath(path).encode("utf-8") if path else None
err = _capi.libei.setup_backend_socket(self, encoded)
if err < 0:
Expand Down Expand Up @@ -1162,7 +1217,8 @@ def dispatch(self) -> None:
"""Read from the connection and queue any events that arrive.

Call this before iterating :attr:`events`, which only drains what
is already queued."""
is already queued.
"""
_capi.libei.dispatch(self)


Expand Down
Loading
Loading