Skip to content

Commit db84b74

Browse files
tonytony
committed
docs(README) Rephrasing
1 parent 3d8cdd9 commit db84b74

File tree

1 file changed

+129
-133
lines changed

1 file changed

+129
-133
lines changed

‎README.md

Lines changed: 129 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -1,195 +1,190 @@
1-
# libtmux
1+
# libtmux: Powerful Python Control for tmux
22

33
[![Python Package](https://img.shields.io/pypi/v/libtmux.svg)](https://pypi.org/project/libtmux/)
44
[![Docs](https://github.com/tmux-python/libtmux/workflows/docs/badge.svg)](https://libtmux.git-pull.com/)
55
[![Build Status](https://github.com/tmux-python/libtmux/workflows/tests/badge.svg)](https://github.com/tmux-python/libtmux/actions?query=workflow%3A%22tests%22)
66
[![Code Coverage](https://codecov.io/gh/tmux-python/libtmux/branch/master/graph/badge.svg)](https://codecov.io/gh/tmux-python/libtmux)
77
[![License](https://img.shields.io/github/license/tmux-python/libtmux.svg)](https://github.com/tmux-python/libtmux/blob/master/LICENSE)
88

9-
## TL;DR
9+
## What is libtmux?
1010

11-
`libtmux` is a typed Python API for controlling [tmux](https://github.com/tmux/tmux), letting you programmatically manage sessions, windows, and panes with an intuitive object-oriented interface.
11+
**libtmux** is a fully typed Python API that provides seamless control over [tmux](https://github.com/tmux/tmux), the popular terminal multiplexer. Design your terminal workflows in clean, Pythonic code with an intuitive object-oriented interface.
12+
13+
## Why Use libtmux?
14+
15+
- 💪 **Powerful Abstractions**: Manage tmux sessions, windows, and panes through a clean object model
16+
- 🎯 **Improved Productivity**: Automate repetitive tmux tasks with Python scripts
17+
- 🔍 **Smart Filtering**: Find and manipulate tmux objects with Django-inspired filtering queries
18+
- 🚀 **Versatile Applications**: Perfect for DevOps automation, development environments, and custom tooling
19+
- 🔒 **Type Safety**: Fully typed with modern Python typing annotations for IDE autocompletion
20+
21+
## Quick Example
1222

1323
```python
1424
import libtmux
1525

1626
# Connect to the tmux server
1727
server = libtmux.Server()
1828

19-
# Create or attach to a session
20-
session = server.new_session(session_name="my_session")
29+
# Create a development session with multiple windows
30+
session = server.new_session(session_name="dev")
2131

22-
# Create a new window
23-
window = session.new_window(window_name="my_window")
32+
# Create organized windows for different tasks
33+
editor = session.new_window(window_name="editor")
34+
terminal = session.new_window(window_name="terminal")
35+
logs = session.new_window(window_name="logs")
2436

25-
# Split the window into panes
26-
pane1 = window.split_window(vertical=True)
27-
pane2 = window.split_window(vertical=False)
37+
# Split the editor into code and preview panes
38+
code_pane = editor.split_window(vertical=True)
39+
preview_pane = editor.split_window(vertical=False)
2840

29-
# Send commands to panes
30-
pane1.send_keys("echo 'Hello from pane 1'")
31-
pane2.send_keys("ls -la", enter=True)
41+
# Start your development environment
42+
code_pane.send_keys("cd ~/projects/my-app", enter=True)
43+
code_pane.send_keys("vim .", enter=True)
44+
preview_pane.send_keys("python -m http.server", enter=True)
3245

33-
# Capture pane output
34-
output = pane2.capture_pane()
46+
# Set up terminal window for commands
47+
terminal.send_keys("git status", enter=True)
48+
49+
# Start monitoring logs
50+
logs.send_keys("tail -f /var/log/application.log", enter=True)
51+
52+
# Switch back to the editor window to start working
53+
editor.select_window()
3554
```
3655

37-
## Overview
56+
## Architecture: Clean Hierarchical Design
3857

39-
`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.
58+
libtmux mirrors tmux's natural hierarchy with a clean object model:
4059

4160
```
4261
┌─────────────────────────┐
43-
│ Server │
62+
│ Server │ ← Connect to local or remote tmux servers
4463
└───────────┬─────────────┘
4564
│
4665
┌───────────▼─────────────┐
47-
│ Sessions │
66+
│ Sessions │ ← Organize work into logical sessions
4867
└───────────┬─────────────┘
4968
│
5069
┌───────────▼─────────────┐
51-
│ Windows │
70+
│ Windows │ ← Create task-specific windows (like browser tabs)
5271
└───────────┬─────────────┘
5372
│
5473
┌───────────▼─────────────┐
55-
│ Panes │
74+
│ Panes │ ← Split windows into multiple views
5675
└─────────────────────────┘
5776
```
5877

59-
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.
60-
6178
## Installation
6279

6380
```console
64-
$ pip install --user libtmux
65-
```
66-
67-
## Quick Start Guide
68-
69-
### 1. Open a tmux session
81+
# Basic installation
82+
$ pip install libtmux
7083

71-
```console
72-
$ tmux new-session -s foo -n bar
84+
# With development tools
85+
$ pip install libtmux[dev]
7386
```
7487

75-
### 2. Connect to your tmux session with Python
88+
## Getting Started
7689

77-
Start an interactive Python shell:
90+
### 1. Create or attach to a tmux session
7891

7992
```console
80-
$ python
93+
$ tmux new-session -s my-session
8194
```
8295

83-
For a better experience with autocompletions:
84-
85-
```console
86-
$ pip install --user ptpython # or ipython
87-
$ ptpython
88-
```
89-
90-
Connect to a live tmux session:
96+
### 2. Connect with Python
9197

9298
```python
93-
>>> import libtmux
94-
>>> server = libtmux.Server()
95-
>>> server
96-
Server(socket_path=/tmp/tmux-.../default)
97-
```
98-
99-
**Tip**: You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your current tmux server/session/window/pane.
100-
101-
## Core Features
102-
103-
### Working with the Server
99+
import libtmux
104100

105-
```python
106-
# Connect with custom socket
107-
server = libtmux.Server(socket_name='libtmux_doctest')
101+
# Connect to running tmux server
102+
server = libtmux.Server()
108103

109-
# Send tmux commands directly
110-
server.cmd('display-message', 'hello world')
104+
# Access existing session
105+
session = server.sessions.get(session_name="my-session")
111106

112-
# Create a new session
113-
server.cmd('new-session', '-d', '-P', '-F#{session_id}').stdout[0] # '$2'
107+
# Or create a new one
108+
if not session:
109+
session = server.new_session(session_name="my-session")
110+
111+
print(f"Connected to: {session}")
114112
```
115113

116-
### Managing Sessions
114+
## Key Features
117115

118-
```python
119-
# List all sessions
120-
server.sessions # [Session($1 ...), Session($0 ...)]
121-
122-
# Filter sessions by attribute
123-
server.sessions.filter(history_limit='2000')
124-
125-
# Direct lookup
126-
server.sessions.get(session_id="$1")
116+
### Smart Session Management
127117

128-
# Rename a session
129-
session = server.sessions[0]
130-
session.rename_session('my-session') # Session($1 my-session)
118+
```python
119+
# Find sessions with powerful filtering
120+
dev_sessions = server.sessions.filter(session_name__contains="dev")
121+
122+
# Create a session with context manager for auto-cleanup
123+
with server.new_session(session_name="temp-session") as session:
124+
# Session will be automatically killed when exiting the context
125+
window = session.new_window(window_name="test")
126+
window.split_window().send_keys("echo 'This is a temporary workspace'", enter=True)
131127
```
132128

133-
### Working with Windows
129+
### Flexible Window Operations
134130

135131
```python
136-
# Create a new window (without switching to it)
137-
bg_window = session.new_window(attach=False, window_name="background")
138-
139-
# Find windows by name
140-
session.windows.filter(window_name__startswith="back")
141-
session.windows.get(window_name__startswith="back")
142-
143-
# Rename a window
144-
window = session.active_window
145-
window.rename_window('my-project')
146-
147-
# Close a window
148-
window.kill()
132+
# Create windows programmatically
133+
for project in ["api", "frontend", "database"]:
134+
window = session.new_window(window_name=project)
135+
window.send_keys(f"cd ~/projects/{project}", enter=True)
136+
137+
# Find windows with powerful queries
138+
api_window = session.windows.get(window_name__exact="api")
139+
frontend_windows = session.windows.filter(window_name__contains="front")
140+
141+
# Manipulate window layouts
142+
window.select_layout("main-vertical")
149143
```
150144

151-
### Managing Panes
145+
### Precise Pane Control
152146

153147
```python
154-
# Split window to create panes
155-
pane = window.split() # Horizontal split (attach=True by default)
156-
pane = window.split(attach=False) # Don't switch to the new pane
148+
# Create complex layouts
149+
main_pane = window.active_pane
150+
side_pane = window.split_window(vertical=True, percent=30)
151+
bottom_pane = main_pane.split_window(vertical=False, percent=20)
152+
153+
# Send commands to specific panes
154+
main_pane.send_keys("vim main.py", enter=True)
155+
side_pane.send_keys("git log", enter=True)
156+
bottom_pane.send_keys("python -m pytest", enter=True)
157+
158+
# Capture and analyze output
159+
test_output = bottom_pane.capture_pane()
160+
if "FAILED" in "\n".join(test_output):
161+
print("Tests are failing!")
162+
```
157163

158-
# Select a pane
159-
pane.select()
164+
### Direct Command Access
160165

161-
# Send commands to a pane
162-
pane.send_keys('echo "Hello, world!"')
163-
pane.send_keys('echo "No enter"', enter=False)
164-
pane.enter() # Press Enter key
166+
For advanced needs, send commands directly to tmux:
165167

166-
# Clear a pane
167-
pane.clear()
168+
```python
169+
# Execute any tmux command directly
170+
server.cmd("set-option", "-g", "status-style", "bg=blue")
168171

169-
# Capture pane output
170-
output = pane.cmd('capture-pane', '-p').stdout
171-
print('\n'.join(output))
172+
# Access low-level command output
173+
version_info = server.cmd("list-commands").stdout
172174
```
173175

174-
### Navigate the tmux Object Hierarchy
176+
## Powerful Use Cases
175177

176-
```python
177-
# Traverse from pane up to session
178-
pane.window # Window(@1 1:..., Session($1 ...))
179-
pane.window.session # Session($1 ...)
180-
```
178+
- **Development Environment Automation**: Script your perfect development setup
179+
- **CI/CD Integration**: Create isolated testing environments
180+
- **DevOps Tooling**: Manage multiple terminal sessions in server environments
181+
- **Custom Terminal UIs**: Build terminal-based dashboards and monitoring
182+
- **Remote Session Control**: Programmatically control remote terminal sessions
181183

182184
## Compatibility
183185

184-
### Python Support
185-
186-
- Supported: Python 3.9+, pypy, pypy3
187-
- Unsupported (no security releases or bug fixes):
188-
- Python 2.x: The backports branch is [`v0.8.x`](https://github.com/tmux-python/libtmux/tree/v0.8.x).
189-
190-
### tmux Support
191-
192-
- Supported: tmux 1.8+
186+
- **Python**: 3.9+ (including PyPy)
187+
- **tmux**: 1.8+ (fully tested against latest versions)
193188

194189
## Documentation & Resources
195190

@@ -198,24 +193,25 @@ pane.window.session # Session($1 ...)
198193
- [Architecture Details](https://libtmux.git-pull.com/about.html)
199194
- [Changelog](https://libtmux.git-pull.com/history.html)
200195

196+
## Project Information
197+
198+
- **Source**: [GitHub](https://github.com/tmux-python/libtmux)
199+
- **Issues**: [GitHub Issues](https://github.com/tmux-python/libtmux/issues)
200+
- **PyPI**: [Package](https://pypi.python.org/pypi/libtmux)
201+
- **License**: [MIT](http://opensource.org/licenses/MIT)
202+
203+
## Related Projects
204+
205+
- [tmuxp](https://tmuxp.git-pull.com/): A tmux session manager built on libtmux
206+
- Try `tmuxp shell` to drop into a Python shell with your current tmux session loaded
207+
201208
## Support Development
202209

203-
Your donations fund development of new features, testing and support.
204-
Your contributions directly support maintenance and development of the project.
210+
Your donations and contributions directly support maintenance and development of this project.
205211

206-
See donation options at <https://git-pull.com/support.html>.
212+
- [Support Options](https://git-pull.com/support.html)
213+
- [Contributing Guidelines](https://libtmux.git-pull.com/contributing.html)
207214

208-
## Project Information
215+
---
209216

210-
- Source: <https://github.com/tmux-python/libtmux>
211-
- Issues: <https://github.com/tmux-python/libtmux/issues>
212-
- Test Coverage: <https://codecov.io/gh/tmux-python/libtmux>
213-
- PyPI Package: <https://pypi.python.org/pypi/libtmux>
214-
- Open Hub: <https://www.openhub.net/p/libtmux-python>
215-
- Repology: <https://repology.org/project/python:libtmux/versions>
216-
- License: [MIT](http://opensource.org/licenses/MIT)
217-
218-
[tmuxp]: https://tmuxp.git-pull.com/
219-
[`tmuxp shell`]: https://tmuxp.git-pull.com/cli/shell.html
220-
[ptpython]: https://github.com/prompt-toolkit/ptpython
221-
[ipython]: https://ipython.org/
217+
Built with ❤️ by the tmux-python team

0 commit comments

Comments
 (0)