Server: Add __repr__, __eq__, socket_path (#463)

Author: tony

CHANGES

@@ -14,6 +14,25 @@ $ pip install --user --upgrade --pre libtmux
 
 <!-- Maintainers and contributors: Insert change notes for the next release above -->
 
+### Breaking
+- Server: Add `__repr__` and set `socket_path` if none set.
+
+  Before (0.17 and below):
+
+  ```python
+  libtmux.server.Server object at ...>
+  ```
+
+  New `__repr__` (0.18+):
+
+  ```python
+  Server(socket_name=test)
+  ```
+
+  ```python
+  Server(socket_path=/tmp/tmux-1000/default)
+  ```
+
 ## libtmux 0.17.2 (2022-12-27)
 
 - Server: Move `_list_panes` and `_update_panes` to deprecated

README.md

@@ -55,7 +55,7 @@ Connect to a live tmux session:
 >>> import libtmux
 >>> s = libtmux.Server()
 >>> s
-<libtmux.server.Server object at ...>
+Server(socket_path=/tmp/tmux-.../default)
 ```
 
 Tip: You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your

docs/quickstart.md

@@ -98,7 +98,7 @@ First, we can grab a {class}`Server`.
 >>> import libtmux
 >>> server = libtmux.Server()
 >>> server
-<libtmux.server.Server object at ...>
+Server(socket_path=/tmp/tmux-.../default)
 ```
 
 :::{tip}

docs/reference/properties.md

@@ -33,7 +33,7 @@ Attach default tmux {class}`~libtmux.Server` to `t`:
 >>> import libtmux
 >>> t = libtmux.Server()
 >>> t
-<libtmux.server.Server object at ...>
+Server(socket_path=/tmp/tmux-.../default)
 ```
 
 ## Session

docs/topics/traversal.md

@@ -34,7 +34,7 @@ Attach default tmux {class}`~libtmux.Server` to `t`:
 >>> import libtmux
 >>> t = libtmux.Server();
 >>> t
-<libtmux.server.Server object at ...>
+Server(socket_path=/tmp/tmux-.../default)
 ```
 
 Get first session {class}`~libtmux.Session` to `session`:
@@ -96,7 +96,7 @@ Access the window/server of a pane:
 Window(@1 ...:..., Session($1 ...))
 
 >>> p.server
-<libtmux.server.Server object at ...>
+Server(socket_name=libtmux_test...)
 ```
 
 [target]: http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#COMMANDS

src/libtmux/pytest_plugin.py

@@ -133,8 +133,7 @@ def server(
 
         >>> result.assert_outcomes(passed=1)
     """
-    t = Server()
-    t.socket_name = "libtmux_test%s" % next(namer)
+    t = Server(socket_name="libtmux_test%s" % next(namer))
 
     def fin() -> None:
         t.kill_server()

src/libtmux/server.py

@@ -6,6 +6,7 @@
 """
 import logging
 import os
+import pathlib
 import shutil
 import subprocess
 import typing as t
@@ -55,7 +56,7 @@ class Server(EnvironmentMixin):
     Examples
     --------
     >>> server
-    <libtmux.server.Server object at ...>
+    Server(socket_name=libtmux_test...)
 
     >>> server.sessions
     [Session($1 ...)]
@@ -99,7 +100,7 @@ class Server(EnvironmentMixin):
     def __init__(
         self,
         socket_name: t.Optional[str] = None,
-        socket_path: t.Optional[str] = None,
+        socket_path: t.Optional[t.Union[str, pathlib.Path]] = None,
         config_file: t.Optional[str] = None,
         colors: t.Optional[int] = None,
         **kwargs: t.Any,
@@ -108,11 +109,19 @@ def __init__(
         self._windows: t.List[WindowDict] = []
         self._panes: t.List[PaneDict] = []
 
-        if socket_name:
+        if socket_path is not None:
+            self.socket_path = socket_path
+        elif socket_name is not None:
             self.socket_name = socket_name
 
-        if socket_path:
-            self.socket_path = socket_path
+        tmux_tmpdir = pathlib.Path(os.getenv("TMUX_TMPDIR", "/tmp"))
+        socket_name = self.socket_name or "default"
+        if (
+            tmux_tmpdir is not None
+            and self.socket_path is None
+            and self.socket_name is None
+        ):
+            self.socket_path = str(tmux_tmpdir / f"tmux-{os.geteuid()}" / socket_name)
 
         if config_file:
             self.config_file = config_file
@@ -531,6 +540,26 @@ def panes(self) -> QueryList[Pane]:  # type:ignore
 
         return QueryList(panes)
 
+    #
+    # Dunder
+    #
+    def __eq__(self, other: object) -> bool:
+        assert isinstance(other, Server)
+        return (
+            self.socket_name == other.socket_name
+            and self.socket_path == other.socket_path
+        )
+
+    def __repr__(self) -> str:
+        if self.socket_name is not None:
+            return (
+                f"{self.__class__.__name__}"
+                f"(socket_name={getattr(self, 'socket_name')})"
+            )
+        return (
+            f"{self.__class__.__name__}" f"(socket_path={getattr(self, 'socket_path')})"
+        )
+
     #
     # Legacy: Redundant stuff we want to remove
     #