diff --git a/CHANGES b/CHANGES index e256ec322..eb0ac5620 100644 --- a/CHANGES +++ b/CHANGES @@ -45,6 +45,18 @@ $ uvx --from 'libtmux' --prerelease allow python _Notes on the upcoming release will go here._ +### Documentation + +#### Cleaner `from_env` examples (#719) + +The rendered examples for {meth}`Pane.from_env() ` and +its {meth}`Server `, +{meth}`Session `, and +{meth}`Window ` 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 diff --git a/src/libtmux/pane.py b/src/libtmux/pane.py index 5641d0d4d..d10dabb0b 100644 --- a/src/libtmux/pane.py +++ b/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 ...))) diff --git a/src/libtmux/server.py b/src/libtmux/server.py index 615921571..e650557c3 100644 --- a/src/libtmux/server.py +++ b/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=...) diff --git a/src/libtmux/session.py b/src/libtmux/session.py index 1581b1018..31d071aca 100644 --- a/src/libtmux/session.py +++ b/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] diff --git a/src/libtmux/window.py b/src/libtmux/window.py index 8a7980d98..02c16f3f6 100644 --- a/src/libtmux/window.py +++ b/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 ...))