!squash

Author: tony

libtmux/common.py

@@ -13,7 +13,7 @@
 import typing as t
 from collections.abc import MutableMapping
 from distutils.version import LooseVersion
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, Generic, List, Optional, TypeVar, Union, overload
 
 from . import exc
 from ._compat import console_to_str, str_from_console
@@ -315,8 +315,11 @@ def __getattr__(self, key: str) -> str:
             raise AttributeError(f"{self.__class__} has no property {key}")
 
 
-class TmuxRelationalObject:
+O = TypeVar("O", "Pane", "Window", "Session")
+D = TypeVar("D", "PaneDict", "WindowDict", "SessionDict")
 
+
+class TmuxRelationalObject(Generic[O, D]):
     """Base Class for managing tmux object child entities.  .. # NOQA
 
     Manages collection of child objects  (a :class:`Server` has a collection of
@@ -345,6 +348,9 @@ class TmuxRelationalObject:
     ================ ================================== ==============
     """
 
+    children: t.List[O]
+    child_id_attribute: str
+
     def find_where(
         self, attrs: Dict[str, str]
     ) -> Optional[Union["Pane", "Window", "Session"]]:
@@ -359,9 +365,20 @@ def find_where(
         except IndexError:
             return None
 
-    def where(
-        self, attrs: Dict[str, str], first: bool = False
-    ) -> List[Union["Session", "Pane", "Window", t.Any]]:
+    @overload
+    def where(self, attrs: Dict[str, str], first: t.Literal[True]) -> O:
+        ...
+
+    @overload
+    def where(self, attrs: Dict[str, str], first: t.Literal[False]) -> t.List[O]:
+        ...
+
+    @overload
+    def where(self, attrs: Dict[str, str]) -> t.List[O]:
+        ...
+
+    def where(self, attrs: Dict[str, str], first: bool = False) -> t.Union[List[O], O]:
+        # ) -> List[Union["Session", "Pane", "Window", t.Any]]:
         """
         Return objects matching child objects properties.
 
@@ -376,7 +393,7 @@ def where(
         """
 
         # from https://github.com/serkanyersen/underscore.py
-        def by(val: WindowDict) -> bool:
+        def by(val: D) -> bool:
             for key in attrs.keys():
                 try:
                     if attrs[key] != val[key]:

libtmux/pane.py

@@ -23,7 +23,7 @@
 logger = logging.getLogger(__name__)
 
 
-class Pane(TmuxMappingObject, TmuxRelationalObject):
+class Pane(TmuxMappingObject):
     """
     A :term:`tmux(1)` :term:`Pane` [pane_manual]_.
 

libtmux/server.py

@@ -24,8 +24,12 @@
 
 logger = logging.getLogger(__name__)
 
+if t.TYPE_CHECKING:
+    from libtmux.common import SessionDict
+    from libtmux.window import Window
 
-class Server(TmuxRelationalObject, EnvironmentMixin):
+
+class Server(TmuxRelationalObject["Session", "SessionDict"], EnvironmentMixin):
 
     """
     The :term:`tmux(1)` :term:`Server` [server_manual]_.
@@ -193,7 +197,7 @@ def sessions(self) -> t.List[Session]:
         return self.list_sessions()
 
     #: Alias :attr:`sessions` for :class:`~libtmux.common.TmuxRelationalObject`
-    children = sessions
+    children = sessions  # type: ignore
 
     def _list_windows(self) -> t.List[WindowDict]:
         """

libtmux/session.py

@@ -32,7 +32,9 @@
 logger = logging.getLogger(__name__)
 
 
-class Session(TmuxMappingObject, TmuxRelationalObject, EnvironmentMixin):
+class Session(
+    TmuxMappingObject, TmuxRelationalObject["Window", "WindowDict"], EnvironmentMixin
+):
     """
     A :term:`tmux(1)` :term:`Session` [session_manual]_.
 
@@ -319,7 +321,7 @@ def windows(self) -> t.List[Window]:
         return self.list_windows()
 
     #: Alias :attr:`windows` for :class:`~libtmux.common.TmuxRelationalObject`
-    children = windows
+    children = windows  # type: ignore  # mypy#1362
 
     @property
     def attached_window(self) -> Window:

libtmux/window.py

@@ -24,13 +24,14 @@
 )
 
 if t.TYPE_CHECKING:
+    from .common import PaneDict
     from .server import Server
     from .session import Session
 
 logger = logging.getLogger(__name__)
 
 
-class Window(TmuxMappingObject, TmuxRelationalObject):
+class Window(TmuxMappingObject, TmuxRelationalObject["Pane", "PaneDict"]):
     """
     A :term:`tmux(1)` :term:`Window` [window_manual]_.
 
@@ -550,4 +551,4 @@ def panes(self) -> t.List[Pane]:
         return self.list_panes()
 
     #: Alias :attr:`panes` for :class:`~libtmux.common.TmuxRelationalObject`
-    children = panes
+    children = panes  # type:ignore  # mypy#1362

tests/test_tmuxobject.py

@@ -109,12 +109,14 @@ def test_where(server: Server, session: Session) -> None:
         session_name = session.get("session_name")
         assert session_name is not None
 
-        where = server.where({"session_id": session_id, "session_name": session_name})
+        server_sessions = server.where(
+            {"session_id": session_id, "session_name": session_name}
+        )
 
-        assert len(where) == 1
-        assert isinstance(where, list)
-        assert where[0] == session
-        assert isinstance(where[0], Session)
+        assert len(server_sessions) == 1
+        assert isinstance(server_sessions, list)
+        assert server_sessions[0] == session
+        assert isinstance(server_sessions[0], Session)
 
         # session.where
         for window in session.windows:
@@ -124,14 +126,14 @@ def test_where(server: Server, session: Session) -> None:
             window_index = window.get("window_index")
             assert window_index is not None
 
-            where = session.where(
+            session_windows = session.where(
                 {"window_id": window_id, "window_index": window_index}
             )
 
-            assert len(where) == 1
-            assert isinstance(where, list)
-            assert where[0] == window
-            assert isinstance(where[0], Window)
+            assert len(session_windows) == 1
+            assert isinstance(session_windows, list)
+            assert session_windows[0] == window
+            assert isinstance(session_windows[0], Window)
 
             # window.where
             for pane in window.panes:
@@ -141,12 +143,12 @@ def test_where(server: Server, session: Session) -> None:
                 pane_tty = pane.get("pane_tty")
                 assert pane_tty is not None
 
-                where = window.where({"pane_id": pane_id, "pane_tty": pane_tty})
+                window_panes = window.where({"pane_id": pane_id, "pane_tty": pane_tty})
 
-                assert len(where) == 1
-                assert isinstance(where, list)
-                assert where[0] == pane
-                assert isinstance(where[0], Pane)
+                assert len(window_panes) == 1
+                assert isinstance(window_panes, list)
+                assert window_panes[0] == pane
+                assert isinstance(window_panes[0], Pane)
 
 
 def test_get_by_id(server: Server, session: Session) -> None: