Repository navigation
docs: add the docstrings libei's private helpers and dunders were mis… #8
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -66,6 +66,7 @@ class CObject: | |||||||||||
| _instances_lock: ClassVar[threading.RLock] | ||||||||||||
|
|
||||||||||||
| def __init_subclass__(cls, **kwargs: Any) -> None: | ||||||||||||
| """Give each wrapper hierarchy one identity cache, shared by subclasses.""" | ||||||||||||
| super().__init_subclass__(**kwargs) | ||||||||||||
| # One cache per wrapper *hierarchy*, not per class. Only a root | ||||||||||||
| # wrapper class -- one whose only CObject ancestor is CObject | ||||||||||||
|
|
@@ -98,6 +99,7 @@ def __init_subclass__(cls, **kwargs: Any) -> None: | |||||||||||
| cls._instances_lock = threading.RLock() | ||||||||||||
|
|
||||||||||||
| def __init__(self, pointer: int, *, _adopt: bool = False) -> None: | ||||||||||||
| """Take a reference on a non-NULL pointer and cache this wrapper for it.""" | ||||||||||||
| if not pointer: | ||||||||||||
| raise ValueError(f"{type(self).__name__} cannot wrap a NULL pointer") | ||||||||||||
| self._pointer = pointer | ||||||||||||
|
|
@@ -121,6 +123,7 @@ def __init__(self, pointer: int, *, _adopt: bool = False) -> None: | |||||||||||
|
|
||||||||||||
| @property | ||||||||||||
| def _as_parameter_(self) -> int: | ||||||||||||
| """The raw pointer ctypes passes to C -- an error once it is released.""" | ||||||||||||
| if self._pointer == 0: | ||||||||||||
| raise RuntimeError( | ||||||||||||
| f"{type(self).__name__} has already been released; " | ||||||||||||
|
|
@@ -159,6 +162,7 @@ def release(self) -> None: | |||||||||||
|
|
||||||||||||
| @classmethod | ||||||||||||
| def _get_or_create(cls: type[T], pointer: int | None, *, adopt: bool) -> T | None: | ||||||||||||
| """The wrapper already caching this pointer, or a new one; None for NULL.""" | ||||||||||||
| if not pointer: | ||||||||||||
| return None | ||||||||||||
| if not cls._wrappable: | ||||||||||||
|
|
@@ -232,6 +236,7 @@ def adopt(cls: type[T], pointer: int | None) -> T | None: | |||||||||||
| return cls._get_or_create(pointer, adopt=True) | ||||||||||||
|
|
||||||||||||
| def __eq__(self, other: object) -> bool: | ||||||||||||
| """Equal when the types match and the wrapped pointers are the same.""" | ||||||||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win Document the released-wrapper exception in When either Proposed wording- """Equal when the types match and the wrapped pointers are the same."""
+ """Equal when live wrappers have the same type and pointer.
+
+ A released wrapper compares equal only to itself.
+ """📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||||||||
| if not isinstance(other, CObject): | ||||||||||||
| return NotImplemented | ||||||||||||
| if type(self) is not type(other): | ||||||||||||
|
|
@@ -245,6 +250,7 @@ def __eq__(self, other: object) -> bool: | |||||||||||
| return self._pointer == other._pointer | ||||||||||||
|
|
||||||||||||
| def __hash__(self) -> int: | ||||||||||||
| """Stable for the object's life: the original pointer, not the live one.""" | ||||||||||||
| # Deliberately keyed on _hash_key, not _pointer: release() zeroes | ||||||||||||
| # _pointer, and an object whose hash changes mid-life vanishes | ||||||||||||
| # from any set or dict it was placed in. Two wrappers can share a | ||||||||||||
|
|
||||||||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -427,18 +427,21 @@ def on_response( | |
| params: Any, | ||
| *_a: Any, | ||
| ) -> None: | ||
| """Record the first reply and quit the loop; later replies are ignored.""" | ||
| if result: # both subscriptions may fire; the first reply wins | ||
| return | ||
| result["code"], result["results"] = params.unpack() | ||
| loop.quit() | ||
|
|
||
| def on_timeout() -> bool: | ||
| """Stop the loop and record that it timed out rather than finished.""" | ||
| nonlocal timed_out | ||
| timed_out = True | ||
| loop.quit() | ||
| return False # one-shot; GLib removes the source when this is False | ||
|
|
||
| def subscribe(path: str) -> None: | ||
| """Subscribe to Response on one path, keeping the handle alive.""" | ||
| subscriptions.append( | ||
| connection.signal_subscribe( | ||
| busname, | ||
|
|
@@ -685,12 +688,20 @@ def close(self) -> None: | |
| self._connection = None | ||
|
|
||
| def __enter__(self) -> RemoteDesktopSession: | ||
| """Return self: entering performs no action of its own.""" | ||
| return self | ||
|
|
||
| def __exit__(self, *_exc: Any) -> None: | ||
| """Close the session on the way out, whatever happened.""" | ||
| self.close() | ||
|
|
||
| def __del__(self) -> None: | ||
| """Close the fd only: __del__ can run during interpreter shutdown. | ||
|
|
||
| A synchronous D-Bus round trip there may hang or fail with nothing | ||
| left able to report it, so the D-Bus half of close() is deliberately | ||
| not attempted. | ||
| """ | ||
| # Deliberately only the fd, not the D-Bus half of close(): __del__ | ||
| # can run during interpreter shutdown, where a synchronous D-Bus | ||
| # round trip may hang or fail in ways nothing can report. Closing an | ||
|
|
@@ -1037,6 +1048,7 @@ def on_signal( | |
| params: Any, | ||
| *_a: Any, | ||
| ) -> None: | ||
| """Record the first matching signal; anything else is logged and dropped.""" | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Correct the Later signals return silently after the first matching signal. Only signals for another session are logged and dropped. Update the wording to match this behavior. 🤖 Prompt for AI Agents |
||
| if result: # a subscription that outlives its own wait can fire twice | ||
| return | ||
| args = params.unpack() | ||
|
|
@@ -1058,6 +1070,7 @@ def on_signal( | |
| loop.quit() | ||
|
|
||
| def on_timeout() -> bool: | ||
| """Stop the loop and record that it timed out rather than finished.""" | ||
| nonlocal timed_out | ||
| timed_out = True | ||
| loop.quit() | ||
|
|
@@ -1487,12 +1500,15 @@ def close(self) -> None: | |
| self._connection = None | ||
|
|
||
| def __enter__(self) -> InputCaptureSession: | ||
| """Return self: entering performs no action of its own.""" | ||
| return self | ||
|
|
||
| def __exit__(self, *_exc: Any) -> None: | ||
| """Close the session on the way out, whatever happened.""" | ||
| self.close() | ||
|
|
||
| def __del__(self) -> None: | ||
| """Close the fd only, for the reason RemoteDesktopSession.__del__ gives.""" | ||
| # See RemoteDesktopSession.__del__ for why this closes only the fd. | ||
| if getattr(self, "_eis_fd_claimed", True): | ||
| return | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the
CObject.__init__ownership docstring._adopt=Trueskips_ref_func, and unref-only wrappers have no_ref_func. The current text incorrectly states that construction always takes a reference.Proposed wording
📝 Committable suggestion
🤖 Prompt for AI Agents