libtmux-easy 0.2.0__py3-none-any.whl

libtmux_easy/__init__.py

@@ -0,0 +1,36 @@
+# The names below are loaded on first use, not at import. The lte-run console
+# script imports libtmux_easy.wrap, which runs this file first; importing
+# tmux_lib here would drag libtmux and psutil into every wrapped pane (about
+# 4x the startup time and +7 MB each) for a script that uses neither.
+_EXPORTS = (
+    "TmuxSession",
+    "session_exists",
+    "set_server",
+    "tmux_command",
+    "DeprecatedError",
+    "libtmux_version",
+    "ExitStatus",
+    "PaneStatus",
+    "PANE_MODE_SHELL",
+    "PANE_MODE_EXEC",
+    "PANE_MODE_WRAP",
+    "Capture",
+    "OutputExpect",
+    "OutputMatch",
+    "OutputWatch",
+    "PaneExited",
+)
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name):
+    if name in _EXPORTS:
+        from . import tmux_lib
+
+        return getattr(tmux_lib, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_EXPORTS))

libtmux_easy/_tmux.py

@@ -0,0 +1,38 @@
+"""Running the tmux binary, for the stdlib-only modules (dash, keys, launch).
+It talks to the server of the calling process ($TMUX), or the default one."""
+
+import subprocess
+
+
+def tmux(*args, check=False):
+    """Run 'tmux ARGS'; return its stdout lines. 'check' raises on failure."""
+    proc = subprocess.run(["tmux", *args], capture_output=True, text=True)
+    if check and proc.returncode:
+        raise RuntimeError(f"tmux {args[0]}: {proc.stderr.strip()}")
+    return proc.stdout.splitlines()
+
+
+def option(target, name, scope="-q", run=tmux):
+    """An option's value, or ''. 'scope': '-q' session, '-wq' window, '-gq' global."""
+    out = run("show-options", f"{scope}v", "-t", target, name) if target else \
+        run("show-options", f"{scope}v", name)
+    return out[0].strip() if out else ""
+
+
+# Set by tmux for each pane, or describing the caller's own terminal or
+# session: never copied into a pane's environment. LTE_DIR would point
+# lte-run at another session's socket.
+SKIP_ENV = frozenset(("TMUX", "TMUX_PANE", "TERM", "TERM_PROGRAM", "TERM_PROGRAM_VERSION",
+                      "COLUMNS", "LINES", "LTE_DIR"))
+
+
+def pane_env(env):
+    """'env' (a mapping, e.g. os.environ) as it may go into a pane: SKIP_ENV
+    left out, values as strings."""
+    return {k: str(v) for k, v in (env or {}).items() if k not in SKIP_ENV}
+
+
+def env_args(env):
+    """'env' as tmux '-e NAME=VALUE' arguments (new-window, split-window,
+    respawn-pane)."""
+    return [arg for k, v in pane_env(env).items() for arg in ("-e", f"{k}={v}")]

libtmux_easy/close.py

@@ -0,0 +1,302 @@
+"""lte-close: close a tmux session gracefully, running its close actions.
+
+    lte-close [-t SESSION] [--timeouts INT,TERM,KILL]
+    lte-close add [-t SESSION] [--before] -- COMMAND [ARG...]
+    lte-close list [-t SESSION]
+    lte-close clear [-t SESSION]
+
+Opens a 'close' window in the session and, there, with its progress shown:
+
+  1. runs the 'before' actions;
+  2. stops what runs in the panes: the session's script, if it is still
+     running, stops its own (and runs its Python on_close callbacks); every
+     other pane gets Ctrl-C, then SIGTERM, then SIGKILL;
+  3. runs the 'after' actions (the default for 'add');
+  4. kills the session.
+
+Ctrl-C in the close window skips to killing the session. Works on any
+session, with or without libtmux_easy. Sessions made by the library borrow
+prefix Q for it (see KEY); for every session, bind it in ~/.tmux.conf:
+
+    bind-key Q run-shell -b "lte-close -t '#{session_id}'"
+
+Stdlib only. See docs/session-close.md.
+"""
+
+import argparse
+import json
+import os
+import shlex
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from . import wrap
+from .proc import alive, comm, pane_pids
+from ._tmux import option, tmux as _tmux
+from .dash.control import Control, describe, read_status
+from .dash.options import (HOME_KIND_OPTION, HOME_OPTION, SIDEBAR_OPTION, STATUS_OPTION,
+                           WINDOW_OPTION)
+
+ACTIONS_OPTION = "@lte_on_close"   # session option: JSON list of {"cmd", "cwd", "when"}
+STATE_OPTION = "@lte_closing"      # set by the script: "stopping", then "done"
+WINDOW_OPTION_CLOSE = "@lte_close_window"
+KEY_OPTION = "@lte_close_key"      # session option: set where a borrowed close key applies
+KEY = "Q"                          # borrowed by create() and lte-session, if unbound
+KEY_ROLE = "close"                 # ~/.tmux.conf: set -g @lte_key_close KEY ("" for none)
+WINDOW_NAME = "close"
+WHEN = ("before", "after")
+
+TIMEOUTS = (10.0, 5.0, 2.0)        # SIGINT, SIGTERM, SIGKILL: as stop_pane()
+ACK_TIMEOUT = 2.0                  # for the script to take the 'close' command
+SCRIPT_TIMEOUT = 120.0             # for it to finish
+PAUSE = 1.5                        # the summary stays up this long before the kill
+
+
+# ---------- actions (session option) ----------
+
+def actions(session, run=_tmux):
+    try:
+        return json.loads(option(session, ACTIONS_OPTION, run=run) or "[]")
+    except ValueError:
+        return []
+
+
+def add_action(session, command, when="after", cwd=None, run=_tmux):
+    """Store shell 'command' to run on close, in 'cwd' (default: here)."""
+    if when not in WHEN:
+        raise ValueError(f"when must be one of {WHEN}, not {when!r}")
+    entries = actions(session, run) + [{"cmd": command, "cwd": cwd or os.getcwd(), "when": when}]
+    run("set-option", "-q", "-t", session, ACTIONS_OPTION, json.dumps(entries))
+
+
+def clear_actions(session, run=_tmux):
+    run("set-option", "-uq", "-t", session, ACTIONS_OPTION)
+
+
+def run_actions(entries, when, out=print):
+    """Run the shell actions for one phase, in order; output goes to ours."""
+    for entry in (e for e in entries if e.get("when", "after") == when):
+        out(f"$ {entry['cmd']}")
+        try:
+            code = subprocess.run(entry["cmd"], shell=True, cwd=entry.get("cwd") or None).returncode
+        except OSError as exc:
+            out(f"  failed: {exc}")
+            continue
+        if code:
+            out(f"  exited {code}")
+
+
+# ---------- the close sequence ----------
+
+class Closer:
+    def __init__(self, session, timeouts=TIMEOUTS, out=print, run=_tmux):
+        self.session = session
+        self.timeouts = timeouts
+        self.out = out
+        self.run = run
+        self.name = (run("display-message", "-p", "-t", session, "#{session_name}") or [session])[0]
+
+    def opt(self, name, target=None):
+        return option(target or self.session, name, run=self.run)
+
+    def __call__(self):
+        out = self.out
+        out(f"Closing session {self.name}. Ctrl-C: skip to killing it now.\n")
+        entries = actions(self.session, self.run)
+        try:
+            run_actions(entries, "before", out)
+            self.stop_script()
+            self.stop_panes()
+            run_actions(entries, "after", out)
+        except KeyboardInterrupt:
+            out("\nSkipped the rest.")
+        out("\nKilling the session.")
+        time.sleep(PAUSE)
+        self.run("kill-session", "-t", self.session)
+
+    # ----- the script -----
+
+    def stop_script(self):
+        """Hand the script its own panes: it knows how they end (wrap mode)
+        and runs its Python on_close callbacks."""
+        ctl_dir = self.opt(wrap.DIR_OPTION)
+        control = Control(os.path.join(ctl_dir, wrap.SOCKET_NAME) if ctl_dir else None)
+        if not control.online():
+            return
+        self.run("set-option", "-uq", "-t", self.session, STATE_OPTION)
+        control.send("close", None)
+        deadline = time.monotonic() + ACK_TIMEOUT
+        while not self.opt(STATE_OPTION) and time.monotonic() < deadline:
+            time.sleep(0.05)
+        if not self.opt(STATE_OPTION):
+            self.out("The session's script did not answer: stopping its panes directly.")
+            return
+        self.out("The session's script is stopping its panes:")
+        seen = {}
+        deadline = time.monotonic() + SCRIPT_TIMEOUT
+        while time.monotonic() < deadline:
+            done = self.opt(STATE_OPTION) == "done"
+            path = self.opt(STATUS_OPTION)
+            for entry in (read_status(path) if path else None) or ():
+                label = describe(entry)[0]
+                if seen.get(entry["pane_id"]) != label:
+                    if entry["pane_id"] in seen or label != "running":
+                        self.out(f"  {entry['name']}: {label}")
+                    seen[entry["pane_id"]] = label
+            if done:
+                return
+            time.sleep(0.2)
+        self.out("  ...gave up waiting for it.")
+
+    # ----- every other pane -----
+
+    def _panes(self):
+        """pane id -> label, for the panes to stop: not this one, nor the
+        dashboard's sidebar or (unless it runs a command) its home pane."""
+        skip = {os.environ.get("TMUX_PANE")}
+        dash_window = self.opt(WINDOW_OPTION)
+        if dash_window:
+            skip.add(self.opt(SIDEBAR_OPTION))
+            if option(dash_window, HOME_KIND_OPTION, "-wq", run=self.run) != "command":
+                skip.add(option(dash_window, HOME_OPTION, "-wq", run=self.run))
+        panes = {}
+        for line in self.run("list-panes", "-s", "-t", self.session, "-F",
+                             "#{pane_id} #{pane_pid} #{pane_dead} #{window_name}.#{pane_index}"):
+            fields = line.split(None, 3)
+            if len(fields) == 4 and fields[0] not in skip and fields[2] != "1":
+                panes[fields[0]] = (int(fields[1]), fields[3])
+        return panes
+
+    def stop_panes(self):
+        running = {}
+        for pane_id, (pid, label) in self._panes().items():
+            pids = pane_pids(pid)
+            if pids:
+                running[pane_id] = (f"{label} ({comm(pids[0]) or pids[0]})", pids)
+        if not running:
+            self.out("Nothing left running in the panes.")
+            return
+        self.out(f"Stopping {len(running)} pane(s):")
+        for step, timeout in zip(("SIGINT", "SIGTERM", "SIGKILL"), self.timeouts):
+            if not running:
+                break
+            for pane_id, (label, pids) in running.items():
+                if step == "SIGINT":
+                    # A typed Ctrl-C: the foreground job, as the user would.
+                    self.run("send-keys", "-t", pane_id, "C-c")
+                else:
+                    for pid in pids:
+                        try:
+                            os.kill(pid, getattr(signal, step))
+                        except (ProcessLookupError, PermissionError):
+                            pass
+            self.out(f"  {step} to {', '.join(l for l, _ in running.values())}")
+            deadline = time.monotonic() + timeout
+            while running and time.monotonic() < deadline:
+                for pane_id, (label, pids) in list(running.items()):
+                    if not any(alive(p) for p in pids):
+                        self.out(f"  {label}: stopped by {step}")
+                        del running[pane_id]
+                time.sleep(0.1)
+        for label, _ in running.values():
+            self.out(f"  {label}: still running")
+
+
+# ---------- the window ----------
+
+def self_command():
+    """Shell text that runs lte-close from this install, PATH or not."""
+    src = Path(__file__).resolve().parents[1]
+    return f"env PYTHONPATH={shlex.quote(str(src))} {shlex.quote(sys.executable)} -m libtmux_easy.close"
+
+
+def key_command():
+    """tmux command text for a key binding: close the session it's pressed in."""
+    return f"run-shell -b \"{self_command()} -t '#{{session_id}}'\""
+
+
+def _session_of_caller():
+    pane = os.environ.get("TMUX_PANE")
+    out = _tmux("display-message", "-p", "-t", pane, "#{session_id}") if pane else []
+    return out[0].strip() if out else None
+
+
+def open_close_window(session, timeouts=TIMEOUTS):
+    """Run the close sequence in a new window of 'session' (or the one it
+    already has), and show it."""
+    window = option(session, WINDOW_OPTION_CLOSE)
+    if window and _tmux("list-panes", "-t", window, "-F", "#{pane_id}"):
+        _tmux("select-window", "-t", window)
+        return window
+    command = (f"{self_command()} --here -t {shlex.quote(session)} "
+               f"--timeouts {','.join(str(t) for t in timeouts)}")
+    out = _tmux("new-window", "-t", f"{session}:", "-n", WINDOW_NAME,
+                "-P", "-F", "#{window_id}", command)
+    if not out:
+        return None
+    window = out[0].strip()
+    _tmux("set-option", "-q", "-t", session, WINDOW_OPTION_CLOSE, window)
+    _tmux("select-window", "-t", window)
+    return window
+
+
+def _timeouts(text):
+    values = tuple(float(v) for v in text.split(","))
+    if len(values) != 3:
+        raise argparse.ArgumentTypeError("three values: SIGINT,SIGTERM,SIGKILL seconds")
+    return values
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="lte-close", description=__doc__.split("\n\n")[0],
+        formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__.split("\n\n", 2)[2])
+    parser.add_argument("-t", "--target", help="session (default: the one this runs in)")
+    parser.add_argument("--timeouts", type=_timeouts, default=TIMEOUTS, metavar="INT,TERM,KILL",
+                        help="seconds to wait after each signal (default 10,5,2)")
+    parser.add_argument("--here", action="store_true", help=argparse.SUPPRESS)
+    parser.add_argument("action", nargs="?", default="close",
+                        choices=("close", "add", "list", "clear"))
+    parser.add_argument("--before", action="store_true",
+                        help="add: run before the panes are stopped (default: after)")
+    parser.add_argument("command", nargs="*", help="add: the command ('--' before one with options)")
+    argv = sys.argv[1:] if argv is None else list(argv)
+    # A command after '--' is split off by hand: argparse mishandles '--'
+    # next to an optional positional.
+    after = argv[argv.index("--") + 1:] if "--" in argv else None
+    args = parser.parse_args(argv[:argv.index("--")] if after is not None else argv)
+    if after is not None:
+        args.command = args.command + after
+
+    session = args.target or _session_of_caller()
+    if not session or not _tmux("display-message", "-p", "-t", session, "#{session_id}"):
+        sys.stderr.write("lte-close: no such session (run inside tmux, or pass -t)\n")
+        return 1
+    session = _tmux("display-message", "-p", "-t", session, "#{session_id}")[0].strip()
+
+    if args.action == "add":
+        command = args.command
+        if not command:
+            parser.error("add needs a command")
+        text = command[0] if len(command) == 1 else " ".join(shlex.quote(c) for c in command)
+        add_action(session, text, "before" if args.before else "after")
+        return 0
+    if args.action == "list":
+        for entry in actions(session):
+            print(f"{entry.get('when', 'after'):6}  {entry['cmd']}  (in {entry.get('cwd')})")
+        return 0
+    if args.action == "clear":
+        clear_actions(session)
+        return 0
+    if args.here:
+        signal.signal(signal.SIGHUP, signal.SIG_DFL)
+        Closer(session, args.timeouts)()
+        return 0
+    return 0 if open_close_window(session, args.timeouts) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

libtmux_easy/dash/__init__.py

@@ -0,0 +1,46 @@
+"""lte-dash: a status sidebar for a libtmux_easy session.
+
+    lte-dash --status FILE [--ctl SOCKET]
+
+Runs as the left pane of the session's dashboard window (see
+TmuxSession.dashboard()). The right pane is a viewport: selecting a pane in
+the sidebar swaps the real pane into it with 'tmux swap-pane', so it is fully
+interactive. The "home" pane (a 'tail -F' of the script's output) is the
+placeholder that fills the selected pane's slot in its own window while it is
+on show, so every window keeps its layout.
+
+Stdlib only, like wrap.py, except app.py (Textual): only cli.main() imports
+it, so the library can use Viewport without Textual.
+
+  options.py   tmux option names holding the dashboard's state
+  window.py    open_window(), launcher()
+  viewport.py  Viewport: swap panes in and out
+  control.py   Control (actions to the script), read_status()
+  cli.py       lte-dash
+  app.py       the sidebar UI (Textual)
+  keys.py      lte-key: borrow a prefix key
+  winhook.py   a tmux hook that tells the sidebar its window changed
+  homelog.py   the tee behind TmuxSession.tee_home()
+
+A program that is not a TmuxSession can open a dashboard too: 'lte-dash
+--open SESSION ...', or open_window(). It then writes the status file
+itself and answers the control socket's commands.
+
+    lte-dash --open SESSION --status FILE --ctl SOCKET --home-log FILE
+"""
+
+from .control import Control, read_status
+from .options import (AUTO, FROM_OPTION, HOME_CMD_OPTION, HOME_KIND_OPTION, HOME_LOG,
+                      HOME_OPTION, HOME_STATUS_OPTION, INITIAL_OPTION, INSTALL_HINT, KEY,
+                      KEY_COMMAND, MIN_WIDTH, RUN_DIR_OPTION, SIDEBAR_OPTION, STATUS_OPTION,
+                      VIEW_OPTION, WIDTH_OPTION, WINDOW_OPTION)
+from .viewport import Viewport
+from .window import launcher, open_window
+
+__all__ = [
+    "Control", "Viewport", "launcher", "open_window", "read_status",
+    "AUTO", "FROM_OPTION", "HOME_CMD_OPTION", "HOME_KIND_OPTION", "HOME_LOG", "HOME_OPTION",
+    "HOME_STATUS_OPTION", "INITIAL_OPTION", "INSTALL_HINT", "KEY", "KEY_COMMAND", "MIN_WIDTH",
+    "RUN_DIR_OPTION", "SIDEBAR_OPTION", "STATUS_OPTION", "VIEW_OPTION", "WIDTH_OPTION",
+    "WINDOW_OPTION",
+]

libtmux_easy/dash/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())