From b31b0d06838f9516dffca6182a883cc656c28666 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 13 Jul 2026 19:34:11 -0500 Subject: [PATCH 1/2] from_env(docs): Hide doctest setup with # doctest: +HIDE MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit why: The socket_path/env plumbing that opens each from_env example is needed for the doctest to execute but is noise to the reader. Marking it hidden runs it as a test while keeping it out of the rendered docs. what: - Tag the setup lines in Server/Window/Pane.from_env with `# doctest: +HIDE`; split the env dicts so the marker fits <=88 cols. - Session.from_env hides only socket_path — its env carries the deliberately wrong session id the surrounding prose explains, so it stays visible (hide plumbing, not meaning). Relies on the +HIDE optionflag (gp-libs>=0.0.19) and the render strip (gp-sphinx>=0.0.1a34), both already pinned on master. --- src/libtmux/pane.py | 7 +++++-- src/libtmux/server.py | 9 ++++++--- src/libtmux/session.py | 2 +- src/libtmux/window.py | 7 +++++-- 4 files changed, 17 insertions(+), 8 deletions(-) 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 ...)) From ab4acca104e92800b3e7c0ec94c472019fd5f0c1 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 13 Jul 2026 21:02:49 -0500 Subject: [PATCH 2/2] docs(CHANGES): Cleaner from_env examples why: Note the docs-presentation change this branch introduces. what: - Add a Documentation entry: the from_env family now hides its environment-setup plumbing in rendered examples. --- CHANGES | 12 ++++++++++++ 1 file changed, 12 insertions(+) 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