from_env(docs): Hide doctest setup with # doctest: +HIDE

CHANGES

@@ -45,6 +45,18 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Documentation
+
+#### Cleaner `from_env` examples (#719)
+
+The rendered examples for {meth}`Pane.from_env() <libtmux.Pane.from_env>` and
+its {meth}`Server <libtmux.Server.from_env>`,
+{meth}`Session <libtmux.Session.from_env>`, and
+{meth}`Window <libtmux.Window.from_env>` siblings now hide the incidental
+environment-setup plumbing, so each example leads with the constructor call it
+demonstrates instead of the socket-path and `$TMUX` boilerplate needed to run
+it.
+
 ## libtmux 0.62.0 (2026-07-12)
 
 libtmux 0.62.0 teaches libtmux objects to locate themselves and to resolve

src/libtmux/pane.py

@@ -238,10 +238,13 @@ def from_env(cls, env: t.Mapping[str, str] | None = None) -> Pane:
 
         Examples
         --------
-        >>> socket_path = server.cmd(
+        >>> socket_path = server.cmd(  # doctest: +HIDE
         ...     "display-message", "-p", "-t", pane.pane_id, "#{socket_path}"
         ... ).stdout[0]
-        >>> env = {"TMUX": f"{socket_path},1,0", "TMUX_PANE": pane.pane_id}
+        >>> env = {  # doctest: +HIDE
+        ...     "TMUX": f"{socket_path},1,0",
+        ...     "TMUX_PANE": pane.pane_id,
+        ... }
 
         >>> Pane.from_env(env)
         Pane(%1 Window(@1 1:..., Session($1 ...)))

src/libtmux/server.py

@@ -230,11 +230,14 @@ def from_env(cls, env: t.Mapping[str, str] | None = None) -> Server:
 
         Examples
         --------
-        >>> from libtmux.server import Server as TmuxServer
-        >>> socket_path = server.cmd(
+        >>> from libtmux.server import Server as TmuxServer  # doctest: +HIDE
+        >>> socket_path = server.cmd(  # doctest: +HIDE
         ...     "display-message", "-p", "-t", pane.pane_id, "#{socket_path}"
         ... ).stdout[0]
-        >>> env = {"TMUX": f"{socket_path},1,0", "TMUX_PANE": pane.pane_id}
+        >>> env = {  # doctest: +HIDE
+        ...     "TMUX": f"{socket_path},1,0",
+        ...     "TMUX_PANE": pane.pane_id,
+        ... }
 
         >>> TmuxServer.from_env(env)
         Server(socket_path=...)

src/libtmux/session.py

@@ -217,7 +217,7 @@ def from_env(cls, env: t.Mapping[str, str] | None = None) -> Session:
 
         Examples
         --------
-        >>> socket_path = server.cmd(
+        >>> socket_path = server.cmd(  # doctest: +HIDE
         ...     "display-message", "-p", "-t", pane.pane_id, "#{socket_path}"
         ... ).stdout[0]
 

src/libtmux/window.py

@@ -253,10 +253,13 @@ def from_env(cls, env: t.Mapping[str, str] | None = None) -> Window:
 
         Examples
         --------
-        >>> socket_path = server.cmd(
+        >>> socket_path = server.cmd(  # doctest: +HIDE
         ...     "display-message", "-p", "-t", pane.pane_id, "#{socket_path}"
         ... ).stdout[0]
-        >>> env = {"TMUX": f"{socket_path},1,0", "TMUX_PANE": pane.pane_id}
+        >>> env = {  # doctest: +HIDE
+        ...     "TMUX": f"{socket_path},1,0",
+        ...     "TMUX_PANE": pane.pane_id,
+        ... }
 
         >>> Window.from_env(env)
         Window(@1 1:..., Session($1 ...))