python-libei 0.5.1__tar.gz → 0.5.2__tar.gz

{python_libei-0.5.1 → python_libei-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.5.1
+Version: 0.5.2
 Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
 Author: Dennis K. Paulsen
 License-Expression: MIT
@@ -156,7 +156,7 @@ and why, is in
 
 ## Status
 
-Beta (`0.5.1`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.5.2`), published on [PyPI](https://pypi.org/project/python-libei/)
 since `0.1.0`, and **the API is not frozen** — expect renames before 1.0.
 
 The injection path is exercised end to end against the real libraries by the
@@ -187,11 +187,11 @@ Exactly what was run, when, and against which versions:
   portal paths are the part likeliest to come up short off Linux, since
   they need an xdg-desktop-portal RemoteDesktop backend to talk to.
 - CPython 3.10 or newer (tested on 3.13)
-- The native libraries: on Fedora, `sudo dnf install libei libeis liboeffis`;
-  on FreeBSD, `pkg install libei` (the `x11/libei` port), which supplies all
-  three sonames including `liboeffis`
-- `libei.portal` only: PyGObject (`pip install 'python-libei[portal]'`), plus
-  whatever GObject-introspection libraries your distro needs for `Gio` --
+- The native `libei`, `libeis` and `liboeffis` libraries, which `pip` cannot
+  supply. Which package provides them on your distribution — and what to do
+  when the name does not match — is in [docs/install.md](docs/install.md).
+- `libei.portal` only: PyGObject, via the `portal` extra, plus whatever
+  GObject-introspection libraries your distribution needs for `Gio`, since
   PyPI's PyGObject wheel supplies the Python side only. Not needed for
   `libei.ei`, `libei.eis` or `libei.oeffis`.
 - libei 1.0.0 or newer for the core: connecting, binding a seat, and
@@ -224,22 +224,11 @@ Exactly what was run, when, and against which versions:
 
 ## Install
 
-From [PyPI](https://pypi.org/project/python-libei/):
-
 ```sh
 pip install python-libei
 ```
 
-The distribution is named `python-libei`, the import is `libei` -- so
-`pip show python-libei`, but `from libei import ei`.
-
-Pure Python, no build step: the wheel is `py3-none-any` and ctypes talks to
-the native libraries directly, so there is no compiler, no headers and no
-`libei-devel` involved at install time. What `pip` does *not* bring is the
-native libraries themselves -- see [Requirements](#requirements) above; on
-Fedora, `sudo dnf install libei libeis liboeffis`.
-
-To track `main` instead, or to hack on it, install from a checkout:
+From a checkout instead, to track `main` or to work on the package:
 
 ```sh
 git clone https://github.com/ctrondlp/python-libei.git
@@ -247,15 +236,11 @@ cd python-libei
 pip install .          # or `pip install -e '.[dev]'` to develop
 ```
 
-Importing is always safe, even where the native libraries are missing — they
-are loaded on first use, not at import. Check before you rely on them:
-
-```python
-from libei import ei
-
-if not ei.is_available():
-    ...  # fall back to another input backend
-```
+That is the half `pip` can do. The native `libei`/`libeis`/`liboeffis`
+libraries it cannot supply, the `portal` extra, and how to check what actually
+loaded are all in [docs/install.md](docs/install.md) — see
+[Requirements](#requirements) above for the version floors. Importing is safe
+without any of it: those libraries are loaded on first *use*, not at import.
 
 ## Concepts
 

{python_libei-0.5.1 → python_libei-0.5.2}/README.md

@@ -119,7 +119,7 @@ and why, is in
 
 ## Status
 
-Beta (`0.5.1`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.5.2`), published on [PyPI](https://pypi.org/project/python-libei/)
 since `0.1.0`, and **the API is not frozen** — expect renames before 1.0.
 
 The injection path is exercised end to end against the real libraries by the
@@ -150,11 +150,11 @@ Exactly what was run, when, and against which versions:
   portal paths are the part likeliest to come up short off Linux, since
   they need an xdg-desktop-portal RemoteDesktop backend to talk to.
 - CPython 3.10 or newer (tested on 3.13)
-- The native libraries: on Fedora, `sudo dnf install libei libeis liboeffis`;
-  on FreeBSD, `pkg install libei` (the `x11/libei` port), which supplies all
-  three sonames including `liboeffis`
-- `libei.portal` only: PyGObject (`pip install 'python-libei[portal]'`), plus
-  whatever GObject-introspection libraries your distro needs for `Gio` --
+- The native `libei`, `libeis` and `liboeffis` libraries, which `pip` cannot
+  supply. Which package provides them on your distribution — and what to do
+  when the name does not match — is in [docs/install.md](docs/install.md).
+- `libei.portal` only: PyGObject, via the `portal` extra, plus whatever
+  GObject-introspection libraries your distribution needs for `Gio`, since
   PyPI's PyGObject wheel supplies the Python side only. Not needed for
   `libei.ei`, `libei.eis` or `libei.oeffis`.
 - libei 1.0.0 or newer for the core: connecting, binding a seat, and
@@ -187,22 +187,11 @@ Exactly what was run, when, and against which versions:
 
 ## Install
 
-From [PyPI](https://pypi.org/project/python-libei/):
-
 ```sh
 pip install python-libei
 ```
 
-The distribution is named `python-libei`, the import is `libei` -- so
-`pip show python-libei`, but `from libei import ei`.
-
-Pure Python, no build step: the wheel is `py3-none-any` and ctypes talks to
-the native libraries directly, so there is no compiler, no headers and no
-`libei-devel` involved at install time. What `pip` does *not* bring is the
-native libraries themselves -- see [Requirements](#requirements) above; on
-Fedora, `sudo dnf install libei libeis liboeffis`.
-
-To track `main` instead, or to hack on it, install from a checkout:
+From a checkout instead, to track `main` or to work on the package:
 
 ```sh
 git clone https://github.com/ctrondlp/python-libei.git
@@ -210,15 +199,11 @@ cd python-libei
 pip install .          # or `pip install -e '.[dev]'` to develop
 ```
 
-Importing is always safe, even where the native libraries are missing — they
-are loaded on first use, not at import. Check before you rely on them:
-
-```python
-from libei import ei
-
-if not ei.is_available():
-    ...  # fall back to another input backend
-```
+That is the half `pip` can do. The native `libei`/`libeis`/`liboeffis`
+libraries it cannot supply, the `portal` extra, and how to check what actually
+loaded are all in [docs/install.md](docs/install.md) — see
+[Requirements](#requirements) above for the version floors. Importing is safe
+without any of it: those libraries are loaded on first *use*, not at import.
 
 ## Concepts
 

{python_libei-0.5.1 → python_libei-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-libei"
-version = "0.5.1"
+version = "0.5.2"
 description = "Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis"
 readme = "README.md"
 license = "MIT"
@@ -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]

{python_libei-0.5.1 → python_libei-0.5.2}/src/libei/__init__.py

@@ -31,6 +31,6 @@ the full breakdown, including which features need which libei version.
 Beta: the API is not frozen.
 """
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 
 __all__ = ["__version__"]

python_libei-0.5.2/src/libei/_capi/__init__.py

@@ -0,0 +1,9 @@
+"""Low-level ctypes bindings.
+
+Not part of the public API -- use ``libei.ei``, ``libei.eis`` and
+``libei.oeffis`` instead.
+"""
+
+from . import libei, libeis, liboeffis
+
+__all__ = ["libei", "libeis", "liboeffis"]

{python_libei-0.5.1 → python_libei-0.5.2}/src/libei/ei.py

@@ -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
@@ -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
@@ -207,48 +214,76 @@ 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
@@ -256,17 +291,26 @@ class TouchEvent:
 
 @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
 
@@ -545,9 +589,10 @@ class Device(CObject):
         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)
@@ -564,8 +609,10 @@ class Device(CObject):
         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
 
@@ -760,8 +807,11 @@ class Event(CObject):
 
     @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)
@@ -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)
@@ -1081,7 +1134,8 @@ class Context(CObject):
         """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
@@ -1099,7 +1153,8 @@ class Context(CObject):
         """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:
@@ -1162,7 +1217,8 @@ class Context(CObject):
         """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)
 
 

{python_libei-0.5.1 → python_libei-0.5.2}/src/libei/eis.py

@@ -55,6 +55,7 @@ class Error(Exception):
     """
 
     def __init__(self, message: str, errno: int | None = None) -> None:
+        """Record the failure message and, where libeis reported one, errno."""
         super().__init__(message)
         self.message = message
         self.errno = errno
@@ -166,48 +167,75 @@ class _LogPriority(enum.IntEnum):
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class KeyEvent:
+    """Key code and press state received on a KEYBOARD_KEY event.
+
+    ``key`` is a Linux ``KEY_*`` code, as sent by the client's
+    ``ei.Device.keyboard_key``.
+    """
+
     key: int
     is_press: bool
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ButtonEvent:
+    """Button code and press state received on a BUTTON_BUTTON event.
+
+    ``button`` is a Linux ``BTN_*`` code, as sent by the client's
+    ``ei.Device.button``.
+    """
+
     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 region the sending device covers.
+    """
+
     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
@@ -215,17 +243,23 @@ class TouchEvent:
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class TouchUpEvent:
+    """Touch id and cancellation flag from a TOUCH_UP event."""
+
     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
 
@@ -576,8 +610,10 @@ class Device(CObject):
         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.libeis.now(_capi.libeis.device_get_context(self))
         _capi.libeis.device_frame(self, timestamp)
@@ -837,8 +873,11 @@ class Event(CObject):
 
     @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.libeis.event_get_type(self)
         try:
             return EventType(raw)
@@ -1069,10 +1108,13 @@ class Eis(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 -- Eis is always built directly
-        # via cls(cls._new()) in create_for_fd().
+        """Wrap a freshly created ``struct eis *`` 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 -- Eis is always built directly
+        via cls(cls._new()) in create_for_fd().
+        """
         super().__init__(pointer, _adopt=_adopt)
         _capi.libeis.log_set_handler(self, _log_handler)
         _capi.libeis.log_set_priority(self, _LogPriority.DEBUG)
@@ -1146,7 +1188,8 @@ class Eis(CObject):
         """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.libeis.dispatch(self)
 
     def add_client(self) -> int:
@@ -1172,14 +1215,16 @@ class Eis(CObject):
 
     @classmethod
     def create_for_fd(cls, flags: Sequence[Flag] = ()) -> Eis:
-        """Create a server using the fd backend -- the one real compositors
-        use, since it keeps each client's fd private rather than exposing a
-        connectable socket path. Call :meth:`add_client` once per
-        connection you want to accept.
+        """Create a server using the fd backend.
+
+        The one real compositors use, since it keeps each client's fd
+        private rather than exposing a connectable socket path. Call
+        :meth:`add_client` once per connection you want to accept.
 
         ``flags`` are applied here rather than left to the caller because
         :meth:`set_flag` has to run before the backend is set up, and this
-        method does both."""
+        method does both.
+        """
         server = cls(cls._new())
         for flag in flags:
             server.set_flag(flag)
@@ -1190,9 +1235,12 @@ class Eis(CObject):
 
     @classmethod
     def create_for_socket(cls, path: Path, flags: Sequence[Flag] = ()) -> Eis:
-        """Create a server listening on a Unix socket, as a compositor
-        would (this is the path a real ``ei_setup_backend_socket()`` client
-        connects to). See :meth:`create_for_fd` on ``flags``."""
+        """Create a server listening on a Unix socket.
+
+        As a compositor would (this is the path a real
+        ``ei_setup_backend_socket()`` client connects to). See
+        :meth:`create_for_fd` on ``flags``.
+        """
         server = cls(cls._new())
         for flag in flags:
             server.set_flag(flag)

{python_libei-0.5.1 → python_libei-0.5.2}/src/libei/oeffis.py

@@ -1,5 +1,7 @@
-"""Pythonic wrapper around liboeffis -- negotiates an EIS connection through
-the ``org.freedesktop.portal.RemoteDesktop`` XDG desktop portal.
+"""Pythonic wrapper around liboeffis.
+
+Negotiates an EIS connection through the
+``org.freedesktop.portal.RemoteDesktop`` XDG desktop portal.
 
 This is the path a sandboxed or otherwise non-privileged client uses to get
 an EI socket: it asks the portal, the user is shown a consent dialog, and on
@@ -52,6 +54,7 @@ class DisconnectedError(Exception):
     """The portal session ended unexpectedly (error, or denied by the user)."""
 
     def __init__(self, message: str | None) -> None:
+        """Record why the session ended."""
         super().__init__(message)
         self.message = message
 
@@ -60,6 +63,7 @@ class SessionClosedError(DisconnectedError):
     """The portal explicitly closed the session (not necessarily an error)."""
 
     def __init__(self) -> None:
+        """Build the fixed "Session closed" message."""
         super().__init__(message="Session closed")
 
 
@@ -100,6 +104,7 @@ class Oeffis:
     """
 
     def __init__(self) -> None:
+        """Create the underlying liboeffis context (no portal call yet)."""
         pointer = _capi.liboeffis.new(None)
         if not pointer:
             raise DisconnectedError("oeffis_new() returned NULL")