+
-`libtmux` is a [typed](https://docs.python.org/3/library/typing.html) Python library that provides a wrapper for interacting programmatically with tmux, a terminal multiplexer. You can use it to manage tmux servers,
-sessions, windows, and panes. Additionally, `libtmux` powers [tmuxp], a tmux workspace manager.
+## 🐍 What is libtmux?
-[](https://pypi.org/project/libtmux/)
-[](https://libtmux.git-pull.com/)
-[](https://github.com/tmux-python/tmux-python/actions?query=workflow%3A%22tests%22)
-[](https://codecov.io/gh/tmux-python/libtmux)
-[](https://github.com/tmux-python/libtmux/blob/master/LICENSE)
+libtmux is a typed Python API over [tmux], the terminal multiplexer. Stop shelling out and parsing `tmux ls`. Instead, interact with real Python objects: `Server`, `Session`, `Window`, and `Pane`. The same API powers [tmuxp], so it stays battle-tested in real-world workflows.
-libtmux builds upon tmux's
-[target](http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#COMMANDS) and
-[formats](http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#FORMATS) to
-create an object mapping to traverse, inspect and interact with live
-tmux sessions.
+### ✨ Features
-View the [documentation](https://libtmux.git-pull.com/),
-[API](https://libtmux.git-pull.com/api.html) information and
-[architectural details](https://libtmux.git-pull.com/about.html).
+- Typed, object-oriented control of tmux state
+- Query and [traverse](https://libtmux.git-pull.com/topics/traversal.html) live sessions, windows, and panes
+- Raw escape hatch via `.cmd(...)` on any object
+- Works with multiple tmux sockets and servers
+- [Context managers](https://libtmux.git-pull.com/topics/context_managers.html) for automatic cleanup
+- [pytest plugin](https://libtmux.git-pull.com/pytest-plugin/index.html) for isolated tmux fixtures
+- Proven in production via tmuxp and other tooling
-# Install
+## Requirements & support
-```console
-$ pip install --user libtmux
+- tmux: >= 3.2a
+- Python: >= 3.10 (CPython and PyPy)
+
+Maintenance-only backports (no new fixes):
+
+- Python 2.x: [`v0.8.x`](https://github.com/tmux-python/libtmux/tree/v0.8.x)
+- tmux 1.8-3.1c: [`v0.48.x`](https://github.com/tmux-python/libtmux/tree/v0.48.x)
+
+## 📦 Installation
+
+Stable release:
+
+```bash
+pip install libtmux
```
-# Open a tmux session
+With pipx:
-Session name `foo`, window name `bar`
+```bash
+pipx install libtmux
+```
-```console
-$ tmux new-session -s foo -n bar
+With uv / uvx:
+
+```bash
+uv add libtmux
+uvx --from "libtmux" python
```
-# Pilot your tmux session via python
+From the main branch (bleeding edge):
-```console
-$ python
+```bash
+pip install 'git+https://github.com/tmux-python/libtmux.git'
+```
+
+Tip: libtmux is pre-1.0. Pin a range in projects to avoid surprises:
+
+requirements.txt:
+
+```ini
+libtmux==0.50.*
```
-Use [ptpython], [ipython], etc. for a nice shell with autocompletions:
+pyproject.toml:
+
+```toml
+libtmux = "0.50.*"
+```
+
+## 🚀 Quickstart
+
+### Open a tmux session
+
+First, start a tmux session to connect to:
```console
-$ pip install --user ptpython
+$ tmux new-session -s foo -n bar
```
+### Pilot your tmux session via Python
+
+Use [ptpython], [ipython], etc. for a nice REPL with autocompletions:
+
```console
+$ pip install --user ptpython
$ ptpython
```
@@ -53,168 +101,223 @@ Connect to a live tmux session:
```python
>>> import libtmux
->>> s = libtmux.Server()
->>> s
+>>> svr = libtmux.Server()
+>>> svr
Server(socket_path=/tmp/tmux-.../default)
```
-Tip: You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your
-current tmux server / session / window pane.
+**Tip:** You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your
+current tmux server / session / window / pane.
-[tmuxp]: https://tmuxp.git-pull.com/
-[`tmuxp shell`]: https://tmuxp.git-pull.com/cli/shell.html
[ptpython]: https://github.com/prompt-toolkit/ptpython
[ipython]: https://ipython.org/
+[`tmuxp shell`]: https://tmuxp.git-pull.com/cli/shell.html
-List sessions:
+### Run any tmux command
-```python
->>> server.sessions
-[Session($1 ...), Session($0 ...)]
-```
-
-Filter sessions by attribute:
+Every object has a `.cmd()` escape hatch that honors socket name and path:
```python
->>> server.sessions.filter(history_limit='2000')
-[Session($1 ...), Session($0 ...)]
+>>> server = Server(socket_name='libtmux_doctest')
+>>> server.cmd('display-message', 'hello world')
+⚙️ libtmux
+Drive tmux from Python: typed, object-oriented control over servers, sessions, windows, and panes.
+
+ 
+
+ 
+ 
+ 
+ 
+ 
+
The book!
The Tao of tmux is available on Leanpub and Kindle (Amazon).
Read and browse the book for free on the web.
-
+
diff --git a/docs/_templates/sidebar/projects.html b/docs/_templates/sidebar/projects.html
index 217e41800..7b46e0bce 100644
--- a/docs/_templates/sidebar/projects.html
+++ b/docs/_templates/sidebar/projects.html
@@ -1,7 +1,7 @@
```
-## Table of Contents
-
-:hidden:
-
```{toctree}
:maxdepth: 2
+:hidden:
quickstart
about
-topics/traversal
-reference/index
+topics/index
+api/index
pytest-plugin/index
+test-helpers/index
```
```{toctree}
diff --git a/docs/internals/constants.md b/docs/internals/constants.md
new file mode 100644
index 000000000..65059ce94
--- /dev/null
+++ b/docs/internals/constants.md
@@ -0,0 +1,15 @@
+# Internal Constants - `libtmux._internal.constants`
+
+:::{warning}
+Be careful with these! These constants are private, internal as they're **not** covered by version policies. They can break or be removed between minor versions!
+
+If you need a data structure here made public or stabilized please [file an issue](https://github.com/tmux-python/libtmux/issues).
+:::
+
+```{eval-rst}
+.. automodule:: libtmux._internal.constants
+ :members:
+ :undoc-members:
+ :inherited-members:
+ :show-inheritance:
+```
diff --git a/docs/internals/index.md b/docs/internals/index.md
index 09d4a1d6f..0d19d3763 100644
--- a/docs/internals/index.md
+++ b/docs/internals/index.md
@@ -11,6 +11,8 @@ If you need an internal API stabilized please [file an issue](https://github.com
```{toctree}
dataclasses
query_list
+constants
+sparse_array
```
## Environmental variables
diff --git a/docs/internals/sparse_array.md b/docs/internals/sparse_array.md
new file mode 100644
index 000000000..74ea7892d
--- /dev/null
+++ b/docs/internals/sparse_array.md
@@ -0,0 +1,14 @@
+# Internal Sparse Array - `libtmux._internal.sparse_array`
+
+:::{warning}
+Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!
+
+If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/libtmux/issues).
+:::
+
+```{eval-rst}
+.. automodule:: libtmux._internal.sparse_array
+ :members:
+ :undoc-members:
+ :show-inheritance:
+```
diff --git a/docs/pytest-plugin/index.md b/docs/pytest-plugin/index.md
index 2cbb599fc..82d55dd2f 100644
--- a/docs/pytest-plugin/index.md
+++ b/docs/pytest-plugin/index.md
@@ -7,15 +7,13 @@ independent tmux server.
```{seealso} Using the pytest plugin?
-Do you want more flexbility? Correctness? Power? Defaults changed? [Connect with us] on the tracker, we want to know
+Do you want more flexibility? Correctness? Power? Defaults changed? [Connect with us] on the tracker, we want to know
your case, we won't stabilize APIs until we're sure everything is by the book.
[connect with us]: https://github.com/tmux-python/libtmux/discussions
-```
-
```{module} libtmux.pytest_plugin
-
+:no-index:
```
## Usage
@@ -33,7 +31,7 @@ The pytest plugin will be automatically detected via pytest, and the fixtures wi
View libtmux's own [tests/](https://github.com/tmux-python/libtmux/tree/master/tests) as well as
tmuxp's [tests/](https://github.com/tmux-python/tmuxp/tree/master/tests).
-libtmux's tests `autouse` the {ref}`recommended-fixtures` above to ensure stable, assertions and
+libtmux's tests `autouse` the {ref}`recommended-fixtures` above to ensure stable test execution, assertions and
object lookups in the test grid.
## pytest-tmux
@@ -41,14 +39,14 @@ object lookups in the test grid.
`pytest-tmux` works through providing {ref}`pytest fixtures