@@ -12,8 +12,8 @@ from inside a live tmux session.
12
12
13
13
## Requirements
14
14
15
- - [ tmux] [ tmux ]
16
- - [ pip] [ pip ] - for this handbook's examples
15
+ - [ tmux]
16
+ - [ pip] - for this handbook's examples
17
17
18
18
[ pip ] : https://pip.pypa.io/en/stable/installing/
19
19
@@ -26,9 +26,7 @@ from inside a live tmux session.
26
26
Next, ensure ` libtmux ` is installed:
27
27
28
28
``` console
29
-
30
29
$ pip install --user libtmux
31
-
32
30
```
33
31
34
32
(developmental-releases)=
@@ -106,13 +104,11 @@ $ ptpython
106
104
107
105
First, we can grab a {class}` Server ` .
108
106
109
- ``` {code-block} python
110
-
107
+ ``` python
111
108
>> > import libtmux
112
109
>> > server = libtmux.Server()
113
110
>> > server
114
111
< libtmux.server.Server object at 0x 7fbd622c1dd0>
115
-
116
112
```
117
113
118
114
:::{tip}
@@ -126,11 +122,9 @@ current tmux server / session / window pane.
126
122
:::
127
123
128
124
:::{note}
129
-
130
125
You can specify a ` socket_name ` , ` socket_path ` and ` config_file `
131
126
in your server object. ` libtmux.Server(socket_name='mysocket') ` is
132
127
equivalent to ` $ tmux -L mysocket ` .
133
-
134
128
:::
135
129
136
130
` server ` is now a living object bound to the tmux server's Sessions,
@@ -143,20 +137,16 @@ methods in {class}`Server` are available.
143
137
144
138
We can list sessions with {meth}` Server.list_sessions ` :
145
139
146
- ``` {code-block} python
147
-
140
+ ``` python
148
141
>> > server.list_sessions()
149
142
[Session($ 3 foo), Session($ 1 libtmux)]
150
-
151
143
```
152
144
153
145
This returns a list of {class}` Session ` objects you can grab. We can
154
146
find our current session with:
155
147
156
- ``` {code-block} python
157
-
148
+ ``` python
158
149
>> > server.list_sessions()[0 ]
159
-
160
150
```
161
151
162
152
However, this isn't guaranteed, libtmux works against current tmux information, the
@@ -169,22 +159,18 @@ tmux sessions use the `$[0-9]` convention as a way to identify sessions.
169
159
170
160
` $3 ` is whatever the ID ` list_sessions() ` returned above.
171
161
172
- ``` {code-block} python
173
-
162
+ ``` python
174
163
>> > server.get_by_id(' $3' )
175
164
Session($ 3 foo)
176
-
177
165
```
178
166
179
167
You may ` session = server.get_by_id('$<yourId>') ` to use the session object.
180
168
181
169
## Get session by name / other properties
182
170
183
- ``` {code-block} python
184
-
171
+ ``` python
185
172
>> > server.find_where({ " session_name" : " foo" })
186
173
Session($ 3 foo)
187
-
188
174
```
189
175
190
176
With ` find_where ` , pass in a dict and return the first object found. In
@@ -194,10 +180,8 @@ through Windows and Panes, respectively.
194
180
195
181
So you may now use:
196
182
197
- ``` {code-block} python
198
-
183
+ ``` python
199
184
>> > session = server.find_where({ " session_name" : " foo" })
200
-
201
185
```
202
186
203
187
to give us a ` session ` object to play with.
@@ -209,11 +193,9 @@ available in {class}`Session`.
209
193
210
194
Let's make a {meth}` Session.new_window ` , in the background:
211
195
212
- ``` {code-block} python
213
-
196
+ ``` python
214
197
>> > session.new_window(attach = False , window_name = " ha in the bg" )
215
198
Window(@ 8 2 :ha in the bg, Session($ 3 foo))
216
-
217
199
```
218
200
219
201
So a few things:
@@ -224,19 +206,15 @@ So a few things:
224
206
3 . Returns the {class}` Window ` object created.
225
207
226
208
:::{note}
227
-
228
209
Use the API reference {ref}` api ` for more commands.
229
-
230
210
:::
231
211
232
212
Let's delete that window ({meth}` Session.kill_window ` ).
233
213
234
214
Method 1: Use passthrough to tmux's ` target ` system.
235
215
236
- ``` {code-block} python
237
-
216
+ ``` python
238
217
>> > session.kill_window(" ha in" )
239
-
240
218
```
241
219
242
220
The window in the bg dissappeared. This was the equivalent of
@@ -254,37 +232,29 @@ target-window, or target-pane.
254
232
In this case, you can also go back in time and recreate the window again. The CLI
255
233
should have history, so navigate up with the arrow key.
256
234
257
- ``` {code-block} python
258
-
235
+ ``` python
259
236
>> > session.new_window(attach = False , window_name = " ha in the bg" )
260
237
Window(@ 11 3 :ha in the bg, Session($ 3 foo))
261
-
262
238
```
263
239
264
240
Try to kill the window by the matching id ` @[0-9999] ` .
265
241
266
- ``` {code-block} python
267
-
242
+ ``` python
268
243
>> > session.new_window(attach = False , window_name = " ha in the bg" )
269
244
Window(@ 12 3 :ha in the bg, Session($ 3 foo))
270
-
271
245
```
272
246
273
247
In addition, you could also ` .kill_window ` direction from the {class}` Window `
274
248
object:
275
249
276
- ``` {code-block} python
277
-
250
+ ``` python
278
251
>> > window = session.new_window(attach = False , window_name = " check this out" )
279
-
280
252
```
281
253
282
254
And kill:
283
255
284
- ``` {code-block} python
285
-
256
+ ``` python
286
257
>> > window.kill_window()
287
-
288
258
```
289
259
290
260
Use {meth}` Session.list_windows() ` and {meth}` Session.find_where() ` to list and sort
@@ -295,21 +265,17 @@ through active {class}`Window`'s.
295
265
Now that we know how to create windows, let's use one. Let's use {meth}` Session.attached_window() `
296
266
to grab our current window.
297
267
298
- ``` {code-block} python
299
-
268
+ ``` python
300
269
>> > window = session.attached_window()
301
-
302
270
```
303
271
304
272
` window ` now has access to all of the objects inside of {class}` Window ` .
305
273
306
274
Let's create a pane, {meth}` Window.split_window ` :
307
275
308
- ``` {code-block} python
309
-
276
+ ``` python
310
277
>> > window.split_window(attach = False )
311
278
Pane(% 23 Window(@ 10 1 :bar, Session($ 3 foo)))
312
-
313
279
```
314
280
315
281
Powered up. Let's have a break down:
@@ -320,11 +286,9 @@ Powered up. Let's have a break down:
320
286
321
287
Also, since you are aware of this power, let's commemorate the experience:
322
288
323
- ``` {code-block} python
324
-
289
+ ``` python
325
290
>> > window.rename_window(' libtmuxower' )
326
291
Window(@ 10 1 :libtmuxower, Session($ 3 foo))
327
-
328
292
```
329
293
330
294
You should have noticed {meth}` Window.rename_window ` renamed the window.
@@ -335,21 +299,20 @@ You have two ways you can move your cursor to new sessions, windows and panes.
335
299
336
300
For one, arguments such as ` attach=False ` can be omittted.
337
301
338
- ``` {code-block} python
339
-
302
+ ``` python
340
303
>> > pane = window.split_window()
341
-
342
304
```
343
305
344
306
This gives you the {class}` Pane ` along with moving the cursor to a new window. You
345
307
can also use the ` .select_* ` available on the object, in this case the pane has
346
308
{meth}` Pane.select_pane() ` .
347
309
348
- ``` {code-block} python
349
-
310
+ ``` python
350
311
>> > pane = window.split_window(attach = False )
351
- >>> pane.select_pane()
312
+ ```
352
313
314
+ ``` python
315
+ >> > pane.select_pane()
353
316
```
354
317
355
318
``` {eval-rst}
@@ -365,12 +328,10 @@ can also use the `.select_*` available on the object, in this case the pane has
365
328
You may send commands to panes, windows and sessions ** without** them being visible.
366
329
As long as you have the object, or are iterating through a list of them, you can use ` .send_keys ` .
367
330
368
- ``` {code-block} python
369
-
331
+ ``` python
370
332
>> > window = session.new_window(attach = False , window_name = " test" )
371
333
>> > pane = window.split_window(attach = False )
372
334
>> > pane.send_keys(' echo hey' , enter = False )
373
-
374
335
```
375
336
376
337
See the other window, notice that {meth}` Pane.send_keys ` has " ` echo hey ` " written,
@@ -380,10 +341,8 @@ _still in the prompt_. Note the leading space character so the command won't be
380
341
you may leave it to the user to press return himself, or complete a command
381
342
using {meth}` Pane.enter() ` :
382
343
383
- ``` {code-block} python
384
-
344
+ ``` python
385
345
>> > pane.enter()
386
-
387
346
```
388
347
389
348
## Final notes
@@ -398,7 +357,7 @@ sessions in the background. :)
398
357
:::{seealso}
399
358
400
359
If you want to dig deeper, check out {ref}` API ` , the code for
401
- and our [ test suite] [ test suite ] (see {ref}` developing ` .)
360
+ and our [ test suite] (see {ref}` developing ` .)
402
361
403
362
:::
404
363
0 commit comments