Core relational typings: Server, Session, Window, Pane (#385)

These will make it much easier to reason about dependent relations

Not as thorough as #383 will be

Author: tony

CHANGES

@@ -29,6 +29,9 @@ $ pip install --user --upgrade --pre libtmux
 
   This created issues with running poetry while inside the virtualenv.
 
+- Typings
+  - Core level relations, e.g. `Pane.window`, `Pane.session`, `Pane.server`, `Window.server` {issue}`385`
+
 ### Documentation
 
 - Renewed logo

libtmux/pane.py

@@ -6,10 +6,17 @@
 
 """
 import logging
+import typing as t
 
 from . import exc
 from .common import TmuxMappingObject, TmuxRelationalObject
 
+if t.TYPE_CHECKING:
+    from .server import Server
+    from .session import Session
+    from .window import Window
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -20,7 +27,7 @@ class Pane(TmuxMappingObject, TmuxRelationalObject):
     ``Pane`` instances can send commands directly to a pane, or traverse
     between linked tmux objects.
 
-    Parameters
+    Attributes
     ----------
     window : :class:`Window`
 
@@ -42,13 +49,16 @@ class Pane(TmuxMappingObject, TmuxRelationalObject):
        Accessed April 1st, 2018.
     """
 
-    #: namespace used :class:`~libtmux.common.TmuxMappingObject`
     formatter_prefix = "pane_"
-
-    def __init__(self, window=None, **kwargs):
-        if not window:
-            raise ValueError("Pane must have ``Window`` object")
-
+    """Namespace used for :class:`~libtmux.common.TmuxMappingObject`"""
+    window: "Window"
+    """:class:`libtmux.Window` pane is linked to"""
+    session: "Session"
+    """:class:`libtmux.Session` pane is linked to"""
+    server: "Server"
+    """:class:`libtmux.Server` pane is linked to"""
+
+    def __init__(self, window: "Window", **kwargs):
         self.window = window
         self.session = self.window.session
         self.server = self.session.server
@@ -275,7 +285,10 @@ def select_pane(self) -> "Pane":
         -------
         :class:`pane`
         """
-        return self.window.select_pane(self.get("pane_id"))
+        pane = self.window.select_pane(self._pane_id)
+        if pane is None:
+            raise exc.LibTmuxException(f"Pane not found: {self}")
+        return pane
 
     def __repr__(self) -> str:
         return "{}({} {})".format(

libtmux/server.py

@@ -60,18 +60,18 @@ class Server(TmuxRelationalObject, EnvironmentMixin):
        Accessed April 1st, 2018.
     """
 
-    #: ``[-L socket-name]``
     socket_name = None
-    #: ``[-S socket-path]``
+    """Passthrough to ``[-L socket-name]``"""
     socket_path = None
-    #: ``[-f file]``
+    """Passthrough to ``[-S socket-path]``"""
     config_file = None
-    #: ``-2`` or ``-8``
+    """Passthrough to ``[-f file]``"""
     colors = None
-    #: unique child ID used by :class:`~libtmux.common.TmuxRelationalObject`
+    """``-2`` or ``-8``"""
     child_id_attribute = "session_id"
-    #: namespace used :class:`~libtmux.common.TmuxMappingObject`
+    """Unique child ID used by :class:`~libtmux.common.TmuxRelationalObject`"""
     formatter_prefix = "server_"
+    """Namespace used for :class:`~libtmux.common.TmuxMappingObject`"""
 
     def __init__(
         self,

libtmux/session.py

@@ -22,6 +22,7 @@
 
 if t.TYPE_CHECKING:
     from .pane import Pane
+    from .server import Server
 
 
 logger = logging.getLogger(__name__)
@@ -50,12 +51,14 @@ class Session(TmuxMappingObject, TmuxRelationalObject, EnvironmentMixin):
        https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed April 1st, 2018.
     """
 
-    #: unique child ID key for :class:`~libtmux.common.TmuxRelationalObject`
     child_id_attribute = "window_id"
-    #: namespace used :class:`~libtmux.common.TmuxMappingObject`
+    """Unique child ID key for :class:`~libtmux.common.TmuxRelationalObject`"""
     formatter_prefix = "session_"
+    """Namespace used for :class:`~libtmux.common.TmuxMappingObject`"""
+    server: "Server"
+    """:class:`libtmux.server.Server` session is linked to"""
 
-    def __init__(self, server=None, **kwargs):
+    def __init__(self, server: "Server", **kwargs):
         EnvironmentMixin.__init__(self)
         self.server = server
 

libtmux/window.py

@@ -18,6 +18,10 @@
 )
 from .pane import Pane
 
+if t.TYPE_CHECKING:
+    from .server import Server
+    from .session import Session
+
 logger = logging.getLogger(__name__)
 
 
@@ -41,16 +45,16 @@ class Window(TmuxMappingObject, TmuxRelationalObject):
        https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed April 1st, 2018.
     """
 
-    #: unique child ID key for :class:`~libtmux.common.TmuxRelationalObject`
     child_id_attribute = "pane_id"
-    #: namespace used :class:`~libtmux.common.TmuxMappingObject`
+    """Unique child ID key for :class:`~libtmux.common.TmuxRelationalObject`"""
     formatter_prefix = "window_"
+    """Namespace used for :class:`~libtmux.common.TmuxMappingObject`"""
+    server: "Server"
+    """:class:`libtmux.Server` window is linked to"""
+    session: "Session"
+    """:class:`libtmux.Session` window is linked to"""
 
-    def __init__(self, session=None, **kwargs):
-
-        if not session:
-            raise ValueError("Window requires a Session, session=Session")
-
+    def __init__(self, session: "Session", **kwargs):
         self.session = session
         self.server = self.session.server