Skip to content

Commit fb190f9

Browse files
committed
docs: Update doctests
1 parent f7151c8 commit fb190f9

File tree

4 files changed

+97
-164
lines changed

4 files changed

+97
-164
lines changed

README.md

Lines changed: 16 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,9 @@ Connect to a live tmux session:
5353

5454
```python
5555
>>> import libtmux
56-
>>> server = libtmux.Server()
57-
>>> server
58-
<libtmux.server.Server object at 0x7fbd622c1dd0>
56+
>>> s = libtmux.Server()
57+
>>> s
58+
<libtmux.server.Server object at ...>
5959
```
6060

6161
Tip: You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your
@@ -70,32 +70,30 @@ List sessions:
7070

7171
```python
7272
>>> server.list_sessions()
73-
[Session($3 foo), Session($1 libtmux)]
73+
[Session($... libtmux_...), Session($... ...)]
7474
```
7575

7676
Find session:
7777

7878
```python
79-
>>> server.get_by_id('$3')
80-
Session($3 foo)
79+
>>> server.get_by_id('$0')
80+
Session($... ...)
8181
```
8282

8383
Find session by dict lookup:
8484

8585
```python
86+
>>> server.sessions[0].rename_session('foo')
87+
Session($... foo)
8688
>>> server.find_where({ "session_name": "foo" })
87-
Session($3 foo)
88-
```
89-
90-
Assign session to `session`:
91-
92-
```python
93-
>>> session = server.find_where({ "session_name": "foo" })
89+
Session($... foo)
9490
```
9591

9692
Control your session:
9793

9894
```python
95+
# Assign session to `session`:
96+
>>> session = server.find_where({ "session_name": "foo" })
9997
>>> session.new_window(attach=False, window_name="ha in the bg")
10098
Window(@8 2:ha in the bg, Session($3 foo))
10199
>>> session.kill_window("ha in")
@@ -104,13 +102,14 @@ Window(@8 2:ha in the bg, Session($3 foo))
104102
Create new window in the background (don't switch to it):
105103

106104
```python
107-
>>> w = session.new_window(attach=False, window_name="ha in the bg")
108-
Window(@11 3:ha in the bg, Session($3 foo))
105+
>>> session.new_window(attach=False, window_name="ha in the bg")
106+
Window(@... ...:ha in the bg, Session($... libtmux_...))
109107
```
110108

111109
Close window:
112110

113111
```python
112+
>>> w = session.attached_window
114113
>>> w.kill_window()
115114
```
116115

@@ -119,89 +118,14 @@ Grab remaining tmux window:
119118
```python
120119
>>> window = session.attached_window
121120
>>> window.split_window(attach=False)
122-
Pane(%23 Window(@10 1:bar, Session($3 foo)))
121+
Pane(%... Window(@... ...:..., Session($... libtmux_...)))
123122
```
124123

125124
Rename window:
126125

127126
```python
128127
>>> window.rename_window('libtmuxower')
129-
Window(@10 1:libtmuxower, Session($3 foo))
128+
Window(@... ...:libtmuxower, Session($... ...))
130129
```
131130

132131
Split window (create a new pane):
133-
134-
```python
135-
>>> pane = window.split_window()
136-
>>> pane = window.split_window(attach=False)
137-
>>> pane.select_pane()
138-
>>> window = session.new_window(attach=False, window_name="test")
139-
>>> pane = window.split_window(attach=False)
140-
```
141-
142-
Type inside the pane (send key strokes):
143-
144-
```python
145-
>>> pane.send_keys('echo hey send now')
146-
147-
>>> pane.send_keys('echo hey', enter=False)
148-
>>> pane.enter()
149-
```
150-
151-
Grab the output of pane:
152-
153-
```python
154-
>>> pane.clear() # clear the pane
155-
>>> pane.send_keys('cowsay hello')
156-
>>> print('\n'.join(pane.cmd('capture-pane', '-p').stdout))
157-
```
158-
159-
sh-3.2$ cowsay 'hello'
160-
_______
161-
< hello >
162-
-------
163-
\ ^__^
164-
\ (oo)\_______
165-
(__)\ )\/\
166-
||----w |
167-
|| ||
168-
169-
Traverse and navigate:
170-
171-
```python
172-
>>> pane.window
173-
Window(@10 1:libtmuxower, Session($3 foo))
174-
>>> pane.window.session
175-
Session($3 foo)
176-
```
177-
178-
# Python support
179-
180-
Unsupported / no security releases or bug fixes:
181-
182-
- Python 2.x: The backports branch is
183-
[`v0.8.x`](https://github.com/tmux-python/libtmux/tree/v0.8.x).
184-
185-
# Donations
186-
187-
Your donations fund development of new features, testing and support.
188-
Your money will go directly to maintenance and development of the
189-
project. If you are an individual, feel free to give whatever feels
190-
right for the value you get out of the project.
191-
192-
See donation options at <https://git-pull.com/support.html>.
193-
194-
# Project details
195-
196-
- tmux support: 1.8+
197-
- python support: >= 3.7, pypy, pypy3
198-
- Source: <https://github.com/tmux-python/libtmux>
199-
- Docs: <https://libtmux.git-pull.com>
200-
- API: <https://libtmux.git-pull.com/api.html>
201-
- Changelog: <https://libtmux.git-pull.com/history.html>
202-
- Issues: <https://github.com/tmux-python/libtmux/issues>
203-
- Test Coverage: <https://codecov.io/gh/tmux-python/libtmux>
204-
- pypi: <https://pypi.python.org/pypi/libtmux>
205-
- Open Hub: <https://www.openhub.net/p/libtmux-python>
206-
- Repology: <https://repology.org/project/python:libtmux/versions>
207-
- License: [MIT](http://opensource.org/licenses/MIT).

docs/quickstart.md

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ First, we can grab a {class}`Server`.
108108
>>> import libtmux
109109
>>> server = libtmux.Server()
110110
>>> server
111-
<libtmux.server.Server object at 0x7fbd622c1dd0>
111+
<libtmux.server.Server object at ...>
112112
```
113113

114114
:::{tip}
@@ -139,14 +139,15 @@ We can list sessions with {meth}`Server.list_sessions`:
139139

140140
```python
141141
>>> server.list_sessions()
142-
[Session($3 foo), Session($1 libtmux)]
142+
[Session($... ...), Session($... ...)]
143143
```
144144

145145
This returns a list of {class}`Session` objects you can grab. We can
146146
find our current session with:
147147

148148
```python
149149
>>> server.list_sessions()[0]
150+
Session($... ...)
150151
```
151152

152153
However, this isn't guaranteed, libtmux works against current tmux information, the
@@ -157,20 +158,24 @@ so {meth}`Server.get_by_id` and {meth}`Server.find_where` exists as a lookup.
157158

158159
tmux sessions use the `$[0-9]` convention as a way to identify sessions.
159160

160-
`$3` is whatever the ID `list_sessions()` returned above.
161+
`$1` is whatever the ID `list_sessions()` returned above.
161162

162163
```python
163-
>>> server.get_by_id('$3')
164-
Session($3 foo)
164+
>>> server.get_by_id('$1')
165+
Session($... ...)
165166
```
166167

167168
You may `session = server.get_by_id('$<yourId>')` to use the session object.
168169

169170
## Get session by name / other properties
170171

171172
```python
173+
# Just for setting up the example:
174+
>>> server.sessions[0].rename_session('foo')
175+
Session($... foo)
176+
172177
>>> server.find_where({ "session_name": "foo" })
173-
Session($3 foo)
178+
Session($... foo)
174179
```
175180

176181
With `find_where`, pass in a dict and return the first object found. In
@@ -181,7 +186,13 @@ through Windows and Panes, respectively.
181186
So you may now use:
182187

183188
```python
189+
# Prepping the example:
190+
>>> server.sessions[0].rename_session('foo')
191+
Session($... foo)
192+
184193
>>> session = server.find_where({ "session_name": "foo" })
194+
>>> session
195+
Session($... foo)
185196
```
186197

187198
to give us a `session` object to play with.
@@ -195,7 +206,7 @@ Let's make a {meth}`Session.new_window`, in the background:
195206

196207
```python
197208
>>> session.new_window(attach=False, window_name="ha in the bg")
198-
Window(@8 2:ha in the bg, Session($3 foo))
209+
Window(@... ...:ha in the bg, Session($... ...))
199210
```
200211

201212
So a few things:
@@ -214,7 +225,7 @@ Let's delete that window ({meth}`Session.kill_window`).
214225
Method 1: Use passthrough to tmux's `target` system.
215226

216227
```python
217-
>>> session.kill_window("ha in")
228+
>>> session.kill_window(window.id)
218229
```
219230

220231
The window in the bg dissappeared. This was the equivalent of
@@ -234,21 +245,26 @@ should have history, so navigate up with the arrow key.
234245

235246
```python
236247
>>> session.new_window(attach=False, window_name="ha in the bg")
237-
Window(@11 3:ha in the bg, Session($3 foo))
248+
Window(@... ...:ha in the bg, Session($... ...))
238249
```
239250

240251
Try to kill the window by the matching id `@[0-9999]`.
241252

242253
```python
254+
# Setup
243255
>>> session.new_window(attach=False, window_name="ha in the bg")
244-
Window(@12 3:ha in the bg, Session($3 foo))
256+
Window(@... ...:ha in the bg, Session($... ...))
257+
258+
>>> session.kill_window('ha in the bg')
245259
```
246260

247261
In addition, you could also `.kill_window` direction from the {class}`Window`
248262
object:
249263

250264
```python
251265
>>> window = session.new_window(attach=False, window_name="check this out")
266+
>>> window
267+
Window(@... ...:check this out, Session($... ...))
252268
```
253269

254270
And kill:
@@ -266,7 +282,7 @@ Now that we know how to create windows, let's use one. Let's use {meth}`Session.
266282
to grab our current window.
267283

268284
```python
269-
>>> window = session.attached_window()
285+
>>> window = session.attached_window
270286
```
271287

272288
`window` now has access to all of the objects inside of {class}`Window`.
@@ -275,7 +291,7 @@ Let's create a pane, {meth}`Window.split_window`:
275291

276292
```python
277293
>>> window.split_window(attach=False)
278-
Pane(%23 Window(@10 1:bar, Session($3 foo)))
294+
Pane(%... Window(@... ...:..., Session($... ...)))
279295
```
280296

281297
Powered up. Let's have a break down:
@@ -288,7 +304,7 @@ Also, since you are aware of this power, let's commemorate the experience:
288304

289305
```python
290306
>>> window.rename_window('libtmuxower')
291-
Window(@10 1:libtmuxower, Session($3 foo))
307+
Window(@... ...:..., Session($... ...))
292308
```
293309

294310
You should have noticed {meth}`Window.rename_window` renamed the window.
@@ -313,6 +329,7 @@ can also use the `.select_*` available on the object, in this case the pane has
313329

314330
```python
315331
>>> pane.select_pane()
332+
Pane(%... Window(@... ...:..., Session($... ...)))
316333
```
317334

318335
```{eval-rst}
@@ -331,6 +348,8 @@ As long as you have the object, or are iterating through a list of them, you can
331348
>>> window = session.new_window(attach=False, window_name="test")
332349
>>> pane = window.split_window(attach=False)
333350
>>> pane.send_keys('echo hey', enter=False)
351+
352+
334353
```
335354

336355
See the other window, notice that {meth}`Pane.send_keys` has "`echo hey`" written,

0 commit comments

Comments
 (0)