libtmux-easy 0.2.0__tar.gz

libtmux_easy-0.2.0/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 California Institute of Technology
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

libtmux_easy-0.2.0/NOTICE

@@ -0,0 +1,10 @@
+Copyright 2026, by the California Institute of Technology. ALL RIGHTS RESERVED.
+United States Government Sponsorship acknowledged. Any commercial use must be
+negotiated with the Office of Technology Transfer at the California Institute of
+Technology.  
+
+This software may be subject to U.S. export control laws. By accepting this
+software, the user agrees to comply with all applicable U.S. export laws and
+regulations. User has the responsibility to obtain export licenses, or other
+export authority as may be required before exporting such information to foreign
+countries or providing access to foreign persons.

libtmux_easy-0.2.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: libtmux-easy
+Version: 0.2.0
+Summary: tmux sessions from Python: exact pane exit status, a live dashboard, pytest fixtures
+Author-email: Spencer Diehl <docdiehl@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/nasa-jpl/libtmux_easy
+Project-URL: Bug Tracker, https://github.com/nasa-jpl/libtmux_easy/issues
+Project-URL: Repository, https://github.com/nasa-jpl/libtmux_easy
+Keywords: tmux,terminal,multiplexer,session,dashboard,pytest
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Terminals
+Requires-Python: >=3.8.1
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: libtmux>=0.17
+Requires-Dist: psutil
+Requires-Dist: packaging
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: dash
+Requires-Dist: textual>=1.0; extra == "dash"
+Dynamic: license-file
+
+# libtmux-easy
+
+Build tmux sessions from Python and supervise what runs in them:
+
+- **exact exit status** for every pane, and an event the moment one exits;
+- panes stay **interactive**: attach, type, Ctrl-C, pdb;
+- a live **dashboard** of every pane;
+- **output** captured to files, searched, and watched for patterns;
+- a **pytest plugin** that launches the processes a test needs and fails
+  the test if one dies.
+
+Linux only.
+
+## Install
+
+| you want | install |
+|---|---|
+| library and commands, in a venv | `pip install 'libtmux-easy[dash]'` |
+| the commands only, any distro | `pipx install 'libtmux-easy[dash]'` |
+| Ubuntu system Python (ROS) | both `.deb`s from [Releases](https://github.com/nasa-jpl/libtmux_easy/releases) |
+| to develop | `uv sync` in a checkout |
+
+```bash
+pip install 'libtmux-easy[dash]'
+# not on PyPI yet:
+pip install 'libtmux-easy[dash] @ git+https://github.com/nasa-jpl/libtmux_easy'
+# Ubuntu:
+sudo apt install ./python3-libtmux-easy_0.2.0_all.deb ./libtmux-easy-dash_0.2.0_all.deb
+```
+
+- Needs tmux. `[dash]` adds Textual for the dashboard; everything else works without it.
+- Wrap-mode panes run `lte-run`: it must be on the panes' PATH, not only the
+  script's (the `.deb`, pipx, or `send_command_before("source .venv/bin/activate")`).
+- ROS: a venv made with `python3 -m venv --system-site-packages` sees `rclpy`.
+- More (pipx with the `.deb`, `--user` installs, building the `.deb`s):
+  [docs/packaging.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/packaging.md).
+
+## Quick start
+
+```python
+from libtmux_easy import TmuxSession
+
+session = TmuxSession.create("my-session")
+session.new_window("work")
+session.new_pane("editor", "nvim")
+server = session.new_pane("server", "python3 -m http.server", mode="wrap")
+
+session.new_window("logs", layout="main-horizontal")
+session.new_pane("journal", "journalctl -f")
+
+session.wait_for_output(server, r"Serving HTTP", timeout=10)
+session.attach()
+```
+
+Panes are named `window:pane`; anything that takes a pane also takes that
+name, its id (`%3`) or the `Pane`. Each pane's border shows its state
+(`server [running]`, `server [exited 3]`).
+
+## Pane modes
+
+| `mode=` | the command | exit status | interactive |
+|---|---|---|---|
+| `"shell"` (default) | is typed into bash | from `$?`: a signal death is *inferred* from 128+N | yes |
+| `"wrap"` | is typed as `lte-run <cmd>` | from `lte-run`, exact | yes |
+| `"exec"` | is the pane's process | from tmux, when tmux records it (see below) | no |
+
+**Use wrap** to monitor a process and get its exit status: exact, and the
+pane stays a shell you can type into. Shell mode is fine when 128+N is good
+enough.
+
+**Avoid exec mode for status.** tmux (3.3a, 3.4) sometimes never collects
+an exec pane's exited process, so the status is lost: `exit_status()`
+returns unknown. It is often lost for a pane stopped with Ctrl-C. tmux can
+also drop the last output printed just before such a process exits.
+Details: [docs/KNOWN_ISSUES.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/KNOWN_ISSUES.md).
+
+`create(mode=)` or `set_default_mode()` sets the default. Rerun a pane with
+`respawn_pane()`: the library tracks the new run (wrap mode also tracks
+reruns typed by hand).
+
+## API
+
+| method | |
+|---|---|
+| `TmuxSession.create(name, env=None, mode="shell", capture=None, status_file=None)` | a new session (replaces one of that name) |
+| `TmuxSession.current(env=None, mode="shell")` | adopt the session this process runs in |
+| `new_window(name, layout="tiled", env=None, capture=None)` | a window; the next panes go in it |
+| `new_pane(name, cmd, mode=None, on_exit=None, on_output=None, env=None, capture=None, tee=None)` | a pane running `cmd` |
+| `send_keys(cmd, target_pane=None)`, `send_command_before(cmd, window=None)` | type into a pane; set up every new pane |
+| `copy_environment(env=None)` | `env` (default `os.environ`) for every later pane |
+| `is_running(pane)`, `exit_status(pane)`, `pane_status(pane)`, `status()`, `print_status()` | state: `ExitStatus` (`.code`, `.signal`, `.ok`), `PaneStatus` (`.state`: running / stopped / ok / failed / unknown) |
+| `watch_pane(pane, on_exit)`, `wait_for_exit(pane, timeout)` | exit events |
+| `stop_pane(pane)`, `stop_all()` | SIGINT, then SIGTERM, then SIGKILL; `stop_all()` in parallel |
+| `respawn_pane(pane, cmd=None)` | rerun in place, any mode |
+| `capture(target, path)`, `search_output(target, pattern)`, `output_text(pane)` | output to files; grep them |
+| `watch_output(target, pattern, cb)`, `wait_for_output(target, pattern, timeout)`, `expect(target, pattern)` | output events |
+| `dashboard()`, `dashboard_pane(cmd)`, `close_dashboard()` | the dashboard |
+| `on_close(action)`, `close()`, `bind_close_key(key=None)` | graceful close |
+| `kill_session()`, `release(keep_windows=False)` | end, or let go and leave windows up |
+| `select_window()`, `select_pane()`, `attach()` | |
+
+`env=` (e.g. `os.environ`) works at session, window and pane level, later
+levels winning: panes otherwise get the tmux *server's* environment, which
+may predate an activated venv. `status_file=` writes `status()` as JSON on
+every change, for other programs.
+
+`kill_session()` only sends SIGHUP: `stop_all()` or `close()` first for a
+clean shutdown.
+
+## Output
+
+```python
+sess.new_pane("api", cmd, on_output={r"Traceback": on_crash})  # callback per matching line
+m = sess.wait_for_output("main:web", r"port (\d+)", timeout=10)  # what it printed already counts
+with sess.expect(pane, r"pong"):                               # watch first, then act
+    sess.send_keys("ping", target_pane=pane)
+
+cap = sess.capture("main", "/var/log/app")   # a window's panes to files, from now on
+sess.search_output("main", r"ERROR")         # [OutputMatch], later
+```
+
+`target` is a pane, a window, or `None` for the whole session (panes made
+later too). tmux pipes each captured pane to a file (`pipe-pane`); matching
+is on plain text, colors dropped. Unwatched panes cost nothing. Details:
+[docs/output-match.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/output-match.md).
+
+## Dashboard
+
+```python
+session.dashboard()                                       # window "dash", always first
+session.dashboard_pane("htop", title="load", size="30%")  # optional, beside the viewport
+```
+
+Left: a sidebar of every pane by window, with running / stopped / failed
+counts. Right: the selected pane itself, swapped in (`tmux swap-pane`), so
+it is fully interactive. `home` shows the script's stdout and logging.
+
+| key | action |
+|---|---|
+| `Up` / `Down`, `Enter` | browse (the viewport follows); focus the pane |
+| `g` | go to the pane in its own window; `prefix g` comes back |
+| `x` / `r` / `c` | stop / rerun the pane / copy its command |
+| `X` `X` / `Q` `Q` | stop all / close the session gracefully |
+| `[` / `]`, `?`, `q` | resize, help, quit |
+
+Needs Textual. Options: `width=`, `initial=pane`, `mouse=`. More:
+[docs/dashboard.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/dashboard.md).
+
+## Testing with pytest
+
+```python
+# conftest.py
+pytest_plugins = ["libtmux_easy.testing"]
+
+# test_web.py
+PROCESSES = {"servers:web": "python3 -m http.server 8000"}
+READY = {"servers:web": r"Serving HTTP"}  # optional: wait for it first
+FAIL_ON = {"*": r"Traceback"}             # optional: a match fails the test
+
+def test_serves(processes):
+    ...          # processes.output("servers:web"), .wait_for(name, pattern), .check()
+```
+
+`processes` (module scope) starts them and waits for `READY`. A test fails
+if a process exits early or prints a `FAIL_ON` line, even if the test never
+noticed. Teardown stops them, and errors unless each exited 0 on SIGINT.
+
+| `--lte-mode` | processes run as | after the run |
+|---|---|---|
+| `shell` | subprocesses, output prefixed `[name]` | stopped |
+| `tmux` | wrap panes in a detached session | kept on failure (`--lte-keep`) |
+| `dash` | panes in `lte-session`'s session and dashboard | kept with `lte-session --keep` |
+
+Default: dash under lte-session, else tmux, else shell. Fixtures to
+override, and `tmux_session` for a test's own session:
+[docs/pytest-plugin.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/pytest-plugin.md).
+
+## Closing a session
+
+tmux has no hook before a session closes, so a graceful close is a command:
+`lte-close` runs the close actions, stops every pane (Ctrl-C, then SIGTERM,
+SIGKILL) and kills the session, showing its progress in a `close` window.
+
+```python
+sess.on_close("./cleanup.sh")                         # shell: runs even if the script died
+sess.on_close(lambda s: save_logs(s), when="before")  # Python: while the script runs
+sess.close()                                          # or close from the script
+```
+
+`prefix Q` (sessions from `create()` or `lte-session`) and the dashboard's
+`Q` `Q` run `lte-close`. Every way to stop and close:
+[docs/session-close.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/session-close.md).
+
+## Commands
+
+| command | does |
+|---|---|
+| `lte-run [--tee FILE [-a] [--raw]] [--] CMD` | runs CMD, reporting its pid and exact status to the session (wrap mode); elsewhere just runs it. `--tee` also copies the output to FILE as plain text (`-a` appends) |
+| `lte-session [--keep] [--name N] [--no-dash] -- CMD` | runs CMD (e.g. `pytest -s`) in a new dashboard session's home pane: a real terminal, so `input()` and pdb work; panes its tests start appear in the sidebar. Exits with CMD's status |
+| `lte-close [-t SESSION]`, `lte-close add -- CMD` | close a session gracefully; add a close action |
+| `lte-dash` | the dashboard sidebar (started by `dashboard()`) |
+| `lte-key borrow KEY OPTION -- CMD` | bind `prefix KEY` in sessions where OPTION is set, the old binding elsewhere |
+| `lte-defaults` | print the starter tmux settings |
+
+`lte-run` keeps the command's terminal: Ctrl-C, Ctrl-Z and stdin work as
+usual. See [docs/wrap-mode.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/wrap-mode.md) and
+[docs/lte-session.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/lte-session.md).
+
+## tmux defaults
+
+A tmux server with **no config file** gets starter settings: vi copy mode,
+`prefix |` / `-` split, `prefix h j k l` move, `prefix C-x` kill-session,
+`mouse on`. `LTE_TMUX_DEFAULTS=0` turns them off; a server with a config is
+left alone. The library's own keys are borrowed only if unbound, and
+`~/.tmux.conf` can move them:
+
+| key | in lte sessions | to change |
+|---|---|---|
+| `prefix g` | back to the dashboard | `set -g @lte_key_dash G` |
+| `prefix Q` | close gracefully | `set -g @lte_key_close ""` (none) |
+
+[docs/tmux-defaults.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/tmux-defaults.md).
+
+## More
+
+- `demos/interactive/`: guided tours, one per feature; start with `01_session.py`.
+  `demos/examples/`: plain scripts.
+- `docs/`: how it works and why ([index](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/README.md)), and
+  [known issues](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/KNOWN_ISSUES.md).
+- Tested with libtmux 0.17 to 0.62, tmux 3.3a and 3.4, Python 3.8 to 3.13.
+  The `.deb`s need Ubuntu 24.04 or newer; on 22.04, use pipx or pip.
+
+## License
+
+Apache-2.0

libtmux_easy-0.2.0/README.md

@@ -0,0 +1,235 @@
+# libtmux-easy
+
+Build tmux sessions from Python and supervise what runs in them:
+
+- **exact exit status** for every pane, and an event the moment one exits;
+- panes stay **interactive**: attach, type, Ctrl-C, pdb;
+- a live **dashboard** of every pane;
+- **output** captured to files, searched, and watched for patterns;
+- a **pytest plugin** that launches the processes a test needs and fails
+  the test if one dies.
+
+Linux only.
+
+## Install
+
+| you want | install |
+|---|---|
+| library and commands, in a venv | `pip install 'libtmux-easy[dash]'` |
+| the commands only, any distro | `pipx install 'libtmux-easy[dash]'` |
+| Ubuntu system Python (ROS) | both `.deb`s from [Releases](https://github.com/nasa-jpl/libtmux_easy/releases) |
+| to develop | `uv sync` in a checkout |
+
+```bash
+pip install 'libtmux-easy[dash]'
+# not on PyPI yet:
+pip install 'libtmux-easy[dash] @ git+https://github.com/nasa-jpl/libtmux_easy'
+# Ubuntu:
+sudo apt install ./python3-libtmux-easy_0.2.0_all.deb ./libtmux-easy-dash_0.2.0_all.deb
+```
+
+- Needs tmux. `[dash]` adds Textual for the dashboard; everything else works without it.
+- Wrap-mode panes run `lte-run`: it must be on the panes' PATH, not only the
+  script's (the `.deb`, pipx, or `send_command_before("source .venv/bin/activate")`).
+- ROS: a venv made with `python3 -m venv --system-site-packages` sees `rclpy`.
+- More (pipx with the `.deb`, `--user` installs, building the `.deb`s):
+  [docs/packaging.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/packaging.md).
+
+## Quick start
+
+```python
+from libtmux_easy import TmuxSession
+
+session = TmuxSession.create("my-session")
+session.new_window("work")
+session.new_pane("editor", "nvim")
+server = session.new_pane("server", "python3 -m http.server", mode="wrap")
+
+session.new_window("logs", layout="main-horizontal")
+session.new_pane("journal", "journalctl -f")
+
+session.wait_for_output(server, r"Serving HTTP", timeout=10)
+session.attach()
+```
+
+Panes are named `window:pane`; anything that takes a pane also takes that
+name, its id (`%3`) or the `Pane`. Each pane's border shows its state
+(`server [running]`, `server [exited 3]`).
+
+## Pane modes
+
+| `mode=` | the command | exit status | interactive |
+|---|---|---|---|
+| `"shell"` (default) | is typed into bash | from `$?`: a signal death is *inferred* from 128+N | yes |
+| `"wrap"` | is typed as `lte-run <cmd>` | from `lte-run`, exact | yes |
+| `"exec"` | is the pane's process | from tmux, when tmux records it (see below) | no |
+
+**Use wrap** to monitor a process and get its exit status: exact, and the
+pane stays a shell you can type into. Shell mode is fine when 128+N is good
+enough.
+
+**Avoid exec mode for status.** tmux (3.3a, 3.4) sometimes never collects
+an exec pane's exited process, so the status is lost: `exit_status()`
+returns unknown. It is often lost for a pane stopped with Ctrl-C. tmux can
+also drop the last output printed just before such a process exits.
+Details: [docs/KNOWN_ISSUES.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/KNOWN_ISSUES.md).
+
+`create(mode=)` or `set_default_mode()` sets the default. Rerun a pane with
+`respawn_pane()`: the library tracks the new run (wrap mode also tracks
+reruns typed by hand).
+
+## API
+
+| method | |
+|---|---|
+| `TmuxSession.create(name, env=None, mode="shell", capture=None, status_file=None)` | a new session (replaces one of that name) |
+| `TmuxSession.current(env=None, mode="shell")` | adopt the session this process runs in |
+| `new_window(name, layout="tiled", env=None, capture=None)` | a window; the next panes go in it |
+| `new_pane(name, cmd, mode=None, on_exit=None, on_output=None, env=None, capture=None, tee=None)` | a pane running `cmd` |
+| `send_keys(cmd, target_pane=None)`, `send_command_before(cmd, window=None)` | type into a pane; set up every new pane |
+| `copy_environment(env=None)` | `env` (default `os.environ`) for every later pane |
+| `is_running(pane)`, `exit_status(pane)`, `pane_status(pane)`, `status()`, `print_status()` | state: `ExitStatus` (`.code`, `.signal`, `.ok`), `PaneStatus` (`.state`: running / stopped / ok / failed / unknown) |
+| `watch_pane(pane, on_exit)`, `wait_for_exit(pane, timeout)` | exit events |
+| `stop_pane(pane)`, `stop_all()` | SIGINT, then SIGTERM, then SIGKILL; `stop_all()` in parallel |
+| `respawn_pane(pane, cmd=None)` | rerun in place, any mode |
+| `capture(target, path)`, `search_output(target, pattern)`, `output_text(pane)` | output to files; grep them |
+| `watch_output(target, pattern, cb)`, `wait_for_output(target, pattern, timeout)`, `expect(target, pattern)` | output events |
+| `dashboard()`, `dashboard_pane(cmd)`, `close_dashboard()` | the dashboard |
+| `on_close(action)`, `close()`, `bind_close_key(key=None)` | graceful close |
+| `kill_session()`, `release(keep_windows=False)` | end, or let go and leave windows up |
+| `select_window()`, `select_pane()`, `attach()` | |
+
+`env=` (e.g. `os.environ`) works at session, window and pane level, later
+levels winning: panes otherwise get the tmux *server's* environment, which
+may predate an activated venv. `status_file=` writes `status()` as JSON on
+every change, for other programs.
+
+`kill_session()` only sends SIGHUP: `stop_all()` or `close()` first for a
+clean shutdown.
+
+## Output
+
+```python
+sess.new_pane("api", cmd, on_output={r"Traceback": on_crash})  # callback per matching line
+m = sess.wait_for_output("main:web", r"port (\d+)", timeout=10)  # what it printed already counts
+with sess.expect(pane, r"pong"):                               # watch first, then act
+    sess.send_keys("ping", target_pane=pane)
+
+cap = sess.capture("main", "/var/log/app")   # a window's panes to files, from now on
+sess.search_output("main", r"ERROR")         # [OutputMatch], later
+```
+
+`target` is a pane, a window, or `None` for the whole session (panes made
+later too). tmux pipes each captured pane to a file (`pipe-pane`); matching
+is on plain text, colors dropped. Unwatched panes cost nothing. Details:
+[docs/output-match.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/output-match.md).
+
+## Dashboard
+
+```python
+session.dashboard()                                       # window "dash", always first
+session.dashboard_pane("htop", title="load", size="30%")  # optional, beside the viewport
+```
+
+Left: a sidebar of every pane by window, with running / stopped / failed
+counts. Right: the selected pane itself, swapped in (`tmux swap-pane`), so
+it is fully interactive. `home` shows the script's stdout and logging.
+
+| key | action |
+|---|---|
+| `Up` / `Down`, `Enter` | browse (the viewport follows); focus the pane |
+| `g` | go to the pane in its own window; `prefix g` comes back |
+| `x` / `r` / `c` | stop / rerun the pane / copy its command |
+| `X` `X` / `Q` `Q` | stop all / close the session gracefully |
+| `[` / `]`, `?`, `q` | resize, help, quit |
+
+Needs Textual. Options: `width=`, `initial=pane`, `mouse=`. More:
+[docs/dashboard.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/dashboard.md).
+
+## Testing with pytest
+
+```python
+# conftest.py
+pytest_plugins = ["libtmux_easy.testing"]
+
+# test_web.py
+PROCESSES = {"servers:web": "python3 -m http.server 8000"}
+READY = {"servers:web": r"Serving HTTP"}  # optional: wait for it first
+FAIL_ON = {"*": r"Traceback"}             # optional: a match fails the test
+
+def test_serves(processes):
+    ...          # processes.output("servers:web"), .wait_for(name, pattern), .check()
+```
+
+`processes` (module scope) starts them and waits for `READY`. A test fails
+if a process exits early or prints a `FAIL_ON` line, even if the test never
+noticed. Teardown stops them, and errors unless each exited 0 on SIGINT.
+
+| `--lte-mode` | processes run as | after the run |
+|---|---|---|
+| `shell` | subprocesses, output prefixed `[name]` | stopped |
+| `tmux` | wrap panes in a detached session | kept on failure (`--lte-keep`) |
+| `dash` | panes in `lte-session`'s session and dashboard | kept with `lte-session --keep` |
+
+Default: dash under lte-session, else tmux, else shell. Fixtures to
+override, and `tmux_session` for a test's own session:
+[docs/pytest-plugin.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/pytest-plugin.md).
+
+## Closing a session
+
+tmux has no hook before a session closes, so a graceful close is a command:
+`lte-close` runs the close actions, stops every pane (Ctrl-C, then SIGTERM,
+SIGKILL) and kills the session, showing its progress in a `close` window.
+
+```python
+sess.on_close("./cleanup.sh")                         # shell: runs even if the script died
+sess.on_close(lambda s: save_logs(s), when="before")  # Python: while the script runs
+sess.close()                                          # or close from the script
+```
+
+`prefix Q` (sessions from `create()` or `lte-session`) and the dashboard's
+`Q` `Q` run `lte-close`. Every way to stop and close:
+[docs/session-close.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/session-close.md).
+
+## Commands
+
+| command | does |
+|---|---|
+| `lte-run [--tee FILE [-a] [--raw]] [--] CMD` | runs CMD, reporting its pid and exact status to the session (wrap mode); elsewhere just runs it. `--tee` also copies the output to FILE as plain text (`-a` appends) |
+| `lte-session [--keep] [--name N] [--no-dash] -- CMD` | runs CMD (e.g. `pytest -s`) in a new dashboard session's home pane: a real terminal, so `input()` and pdb work; panes its tests start appear in the sidebar. Exits with CMD's status |
+| `lte-close [-t SESSION]`, `lte-close add -- CMD` | close a session gracefully; add a close action |
+| `lte-dash` | the dashboard sidebar (started by `dashboard()`) |
+| `lte-key borrow KEY OPTION -- CMD` | bind `prefix KEY` in sessions where OPTION is set, the old binding elsewhere |
+| `lte-defaults` | print the starter tmux settings |
+
+`lte-run` keeps the command's terminal: Ctrl-C, Ctrl-Z and stdin work as
+usual. See [docs/wrap-mode.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/wrap-mode.md) and
+[docs/lte-session.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/lte-session.md).
+
+## tmux defaults
+
+A tmux server with **no config file** gets starter settings: vi copy mode,
+`prefix |` / `-` split, `prefix h j k l` move, `prefix C-x` kill-session,
+`mouse on`. `LTE_TMUX_DEFAULTS=0` turns them off; a server with a config is
+left alone. The library's own keys are borrowed only if unbound, and
+`~/.tmux.conf` can move them:
+
+| key | in lte sessions | to change |
+|---|---|---|
+| `prefix g` | back to the dashboard | `set -g @lte_key_dash G` |
+| `prefix Q` | close gracefully | `set -g @lte_key_close ""` (none) |
+
+[docs/tmux-defaults.md](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/tmux-defaults.md).
+
+## More
+
+- `demos/interactive/`: guided tours, one per feature; start with `01_session.py`.
+  `demos/examples/`: plain scripts.
+- `docs/`: how it works and why ([index](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/README.md)), and
+  [known issues](https://github.com/nasa-jpl/libtmux_easy/blob/main/docs/KNOWN_ISSUES.md).
+- Tested with libtmux 0.17 to 0.62, tmux 3.3a and 3.4, Python 3.8 to 3.13.
+  The `.deb`s need Ubuntu 24.04 or newer; on 22.04, use pipx or pip.
+
+## License
+
+Apache-2.0

libtmux_easy-0.2.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "libtmux-easy"
+version = "0.2.0"
+description = "tmux sessions from Python: exact pane exit status, a live dashboard, pytest fixtures"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+authors = [
+    { name = "Spencer Diehl", email = "docdiehl@gmail.com" }
+]
+keywords = ["tmux", "terminal", "multiplexer", "session", "dashboard", "pytest"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Shells",
+    "Topic :: Terminals",
+]
+requires-python = ">=3.8.1"
+dependencies = [
+    "libtmux>=0.17",
+    "psutil",
+    "packaging",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0",
+]
+# lte-dash, the dashboard sidebar. Ubuntu's python3-textual is too old, so the
+# libtmux-easy-dash .deb bundles this from uv.lock (debian/dash-requirements.txt).
+dash = [
+    "textual>=1.0",
+]
+
+# 'uv sync' installs this group by default: a development environment with
+# the dashboard and the tests. Not part of the package (pip, the .deb).
+[dependency-groups]
+dev = ["libtmux-easy[dash,test]"]
+
+[project.scripts]
+lte-run = "libtmux_easy.wrap:main"
+lte-dash = "libtmux_easy.dash.cli:main"
+lte-session = "libtmux_easy.launch:main"
+lte-key = "libtmux_easy.dash.keys:main"
+lte-close = "libtmux_easy.close:main"
+lte-defaults = "libtmux_easy.starter:main"
+
+# setuptools rather than a newer backend: it is packaged for Ubuntu 24.04, so
+# the .deb (debian/) builds from this same file with apt-only dependencies.
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+"Homepage" = "https://github.com/nasa-jpl/libtmux_easy"
+"Bug Tracker" = "https://github.com/nasa-jpl/libtmux_easy/issues"
+"Repository" = "https://github.com/nasa-jpl/libtmux_easy"

libtmux_easy-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

libtmux_easy-0.2.0/src/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))