Adding type hints to class methods returning self and child (#361)

* Adding `SessionDict`, `WindowDict`, and `PaneDict` type aliases to `common.py` for _list methods
* Adding hints for methods returning `self` and collections of children

Author: tony

libtmux/common.py

@@ -25,6 +25,10 @@
 #: Most recent version of tmux supported
 TMUX_MAX_VERSION = "2.4"
 
+SessionDict = t.Dict[str, t.Any]
+WindowDict = t.Dict[str, t.Any]
+PaneDict = t.Dict[str, t.Any]
+
 
 class EnvironmentMixin:
 

libtmux/pane.py

@@ -154,7 +154,7 @@ def reset(self):
 
     def split_window(
         self, attach=False, vertical=True, start_directory=None, percent=None
-    ):
+    ) -> "Pane":
         """
         Split window at pane and return newly created :class:`Pane`.
 
@@ -261,7 +261,7 @@ def capture_pane(self):
         """
         return self.cmd("capture-pane", "-p").stdout
 
-    def select_pane(self):
+    def select_pane(self) -> "Pane":
         """
         Select pane. Return ``self``.
 
@@ -275,7 +275,7 @@ def select_pane(self):
         """
         return self.window.select_pane(self.get("pane_id"))
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "{}({} {})".format(
             self.__class__.__name__, self.get("pane_id"), self.window
         )

libtmux/server.py

@@ -6,11 +6,15 @@
 """
 import logging
 import os
+import typing as t
 
 from . import exc, formats
 from .common import (
     EnvironmentMixin,
+    PaneDict,
+    SessionDict,
     TmuxRelationalObject,
+    WindowDict,
     has_gte_version,
     session_check_name,
     tmux_cmd,
@@ -125,7 +129,7 @@ def cmd(self, *args, **kwargs):
 
         return tmux_cmd(*args, **kwargs)
 
-    def _list_sessions(self):
+    def _list_sessions(self) -> t.List[SessionDict]:
         """
         Return list of sessions in :py:obj:`dict` form.
 
@@ -165,12 +169,12 @@ def _list_sessions(self):
         return sessions
 
     @property
-    def _sessions(self):
+    def _sessions(self) -> t.List[SessionDict]:
         """Property / alias to return :meth:`~._list_sessions`."""
 
         return self._list_sessions()
 
-    def list_sessions(self):
+    def list_sessions(self) -> t.List[Session]:
         """
         Return list of :class:`Session` from the ``tmux(1)`` session.
 
@@ -181,14 +185,14 @@ def list_sessions(self):
         return [Session(server=self, **s) for s in self._sessions]
 
     @property
-    def sessions(self):
+    def sessions(self) -> t.List[Session]:
         """Property / alias to return :meth:`~.list_sessions`."""
         return self.list_sessions()
 
     #: Alias :attr:`sessions` for :class:`~libtmux.common.TmuxRelationalObject`
     children = sessions
 
-    def _list_windows(self):
+    def _list_windows(self) -> t.List[WindowDict]:
         """
         Return list of windows in :py:obj:`dict` form.
 
@@ -239,7 +243,7 @@ def _list_windows(self):
 
         return self._windows
 
-    def _update_windows(self):
+    def _update_windows(self) -> "Server":
         """
         Update internal window data and return ``self`` for chainability.
 
@@ -250,7 +254,7 @@ def _update_windows(self):
         self._list_windows()
         return self
 
-    def _list_panes(self):
+    def _list_panes(self) -> t.List[PaneDict]:
         """
         Return list of panes in :py:obj:`dict` form.
 
@@ -310,7 +314,7 @@ def _list_panes(self):
 
         return self._panes
 
-    def _update_panes(self):
+    def _update_panes(self) -> "Server":
         """
         Update internal pane data and return ``self`` for chainability.
 
@@ -322,7 +326,7 @@ def _update_panes(self):
         return self
 
     @property
-    def attached_sessions(self):
+    def attached_sessions(self) -> t.Optional[t.List[Session]]:
         """
         Return active :class:`Session` objects.
 
@@ -345,7 +349,7 @@ def attached_sessions(self):
 
         return [Session(server=self, **s) for s in attached_sessions] or None
 
-    def has_session(self, target_session, exact=True):
+    def has_session(self, target_session: str, exact: bool = True) -> bool:
         """
         Return True if session exists. ``$ tmux has-session``.
 
@@ -382,7 +386,7 @@ def kill_server(self):
         """``$ tmux kill-server``."""
         self.cmd("kill-server")
 
-    def kill_session(self, target_session=None):
+    def kill_session(self, target_session=None) -> "Server":
         """
         Kill the tmux session with ``$ tmux kill-session``, return ``self``.
 
@@ -462,7 +466,7 @@ def new_session(
         window_command=None,
         *args,
         **kwargs,
-    ):
+    ) -> Session:
         """
         Return :class:`Session` from  ``$ tmux new-session``.
 

libtmux/session.py

@@ -6,12 +6,14 @@
 """
 import logging
 import os
+import typing as t
 
 from . import exc, formats
 from .common import (
     EnvironmentMixin,
     TmuxMappingObject,
     TmuxRelationalObject,
+    WindowDict,
     handle_option_error,
     has_version,
     session_check_name,
@@ -129,7 +131,7 @@ def switch_client(self):
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
 
-    def rename_session(self, new_name):
+    def rename_session(self, new_name: str) -> "Session":
         """
         Rename session and return new :class:`Session` object.
 
@@ -171,7 +173,7 @@ def new_window(
         attach=True,
         window_index="",
         window_shell=None,
-    ):
+    ) -> Window:
         """
         Return :class:`Window` from ``$ tmux new-window``.
 
@@ -273,20 +275,18 @@ def kill_window(self, target_window=None):
 
         self.server._update_windows()
 
-    def _list_windows(self):
+    def _list_windows(self) -> t.List[WindowDict]:
         windows = self.server._update_windows()._windows
 
-        windows = [w for w in windows if w["session_id"] == self.id]
-
-        return windows
+        return [w for w in windows if w["session_id"] == self.id]
 
     @property
-    def _windows(self):
+    def _windows(self) -> t.List[WindowDict]:
         """Property / alias to return :meth:`Session._list_windows`."""
 
         return self._list_windows()
 
-    def list_windows(self):
+    def list_windows(self) -> t.List[Window]:
         """Return a list of :class:`Window` from the ``tmux(1)`` session.
 
         Returns
@@ -298,15 +298,15 @@ def list_windows(self):
         return [Window(session=self, **window) for window in windows]
 
     @property
-    def windows(self):
+    def windows(self) -> t.List[Window]:
         """Property / alias to return :meth:`Session.list_windows`."""
         return self.list_windows()
 
     #: Alias :attr:`windows` for :class:`~libtmux.common.TmuxRelationalObject`
     children = windows
 
     @property
-    def attached_window(self):
+    def attached_window(self) -> Window:
         """
         Return active :class:`Window` object.
 
@@ -333,7 +333,7 @@ def attached_window(self):
         if len(self._windows) == int(0):
             raise exc.LibTmuxException("No Windows")
 
-    def select_window(self, target_window):
+    def select_window(self, target_window: str) -> Window:
         """
         Return :class:`Window` selected via ``$ tmux select-window``.
 

libtmux/window.py

@@ -7,9 +7,15 @@
 import logging
 import os
 import shlex
+import typing as t
 
 from . import exc, formats
-from .common import TmuxMappingObject, TmuxRelationalObject, handle_option_error
+from .common import (
+    PaneDict,
+    TmuxMappingObject,
+    TmuxRelationalObject,
+    handle_option_error,
+)
 from .pane import Pane
 
 logger = logging.getLogger(__name__)
@@ -270,7 +276,7 @@ def show_window_option(self, option, g=False):
 
         return option[1]
 
-    def rename_window(self, new_name):
+    def rename_window(self, new_name: str) -> "Window":
         """
         Return :class:`Window` object ``$ tmux rename-window <new_name>``.
 
@@ -335,7 +341,7 @@ def move_window(self, destination="", session=None):
 
         self.server._update_windows()
 
-    def select_window(self):
+    def select_window(self) -> "Window":
         """
         Select window. Return ``self``.
 
@@ -349,7 +355,7 @@ def select_window(self):
         """
         return self.session.select_window(self.index)
 
-    def select_pane(self, target_pane):
+    def select_pane(self, target_pane: str) -> t.Optional[Pane]:
         """
         Return selected :class:`Pane` through ``$ tmux select-pane``.
 
@@ -373,7 +379,7 @@ def select_pane(self, target_pane):
 
         return self.attached_pane
 
-    def last_pane(self):
+    def last_pane(self) -> t.Optional[Pane]:
         """Return last pane."""
         return self.select_pane("-l")
 
@@ -385,7 +391,7 @@ def split_window(
         vertical=True,
         shell=None,
         percent=None,
-    ):
+    ) -> Pane:
         """
         Split window and return the created :class:`Pane`.
 
@@ -486,7 +492,7 @@ def split_window(
         return Pane(window=self, **pane)
 
     @property
-    def attached_pane(self):
+    def attached_pane(self) -> t.Optional[Pane]:
         """
         Return the attached :class:`Pane`.
 
@@ -499,25 +505,21 @@ def attached_pane(self):
                 # for now pane_active is a unicode
                 if pane.get("pane_active") == "1":
                     return Pane(window=self, **pane)
-                else:
-                    continue
 
-        return []
-
-    def _list_panes(self):
+    def _list_panes(self) -> t.List[PaneDict]:
         panes = self.server._update_panes()._panes
 
         panes = [p for p in panes if p["session_id"] == self.get("session_id")]
         panes = [p for p in panes if p["window_id"] == self.id]
         return panes
 
     @property
-    def _panes(self):
+    def _panes(self) -> t.List[PaneDict]:
         """Property / alias to return :meth:`~._list_panes`."""
 
         return self._list_panes()
 
-    def list_panes(self):
+    def list_panes(self) -> t.List[Pane]:
         """
         Return list of :class:`Pane` for the window.
 
@@ -529,7 +531,7 @@ def list_panes(self):
         return [Pane(window=self, **pane) for pane in self._panes]
 
     @property
-    def panes(self):
+    def panes(self) -> t.List[Pane]:
         """Property / alias to return :meth:`~.list_panes`."""
         return self.list_panes()