Skip to content

Commit

Permalink
docs: Update doctests
Browse files Browse the repository at this point in the history
  • Loading branch information
tony committed Sep 10, 2022
1 parent f7151c8 commit 416507d
Show file tree
Hide file tree
Showing 4 changed files with 106 additions and 92 deletions.
45 changes: 25 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,9 @@ Connect to a live tmux session:

```python
>>> import libtmux
>>> server = libtmux.Server()
>>> server
<libtmux.server.Server object at 0x7fbd622c1dd0>
>>> s = libtmux.Server()
>>> s
<libtmux.server.Server object at ...>
```

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

```python
>>> server.list_sessions()
[Session($3 foo), Session($1 libtmux)]
[Session($... libtmux_...), Session($... ...)]
```

Find session:

```python
>>> server.get_by_id('$3')
Session($3 foo)
>>> server.get_by_id('$0')
Session($... ...)
```

Find session by dict lookup:

```python
>>> server.sessions[0].rename_session('foo')
Session($... foo)
>>> server.find_where({ "session_name": "foo" })
Session($3 foo)
```

Assign session to `session`:

```python
>>> session = server.find_where({ "session_name": "foo" })
Session($... foo)
```

Control your session:

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

```python
>>> w = session.new_window(attach=False, window_name="ha in the bg")
Window(@11 3:ha in the bg, Session($3 foo))
>>> session.new_window(attach=False, window_name="ha in the bg")
Window(@... ...:ha in the bg, Session($... libtmux_...))
```

Close window:

```python
>>> w = session.attached_window
>>> w.kill_window()
```

Expand All @@ -119,14 +118,14 @@ Grab remaining tmux window:
```python
>>> window = session.attached_window
>>> window.split_window(attach=False)
Pane(%23 Window(@10 1:bar, Session($3 foo)))
Pane(%... Window(@... ...:..., Session($... libtmux_...)))
```

Rename window:

```python
>>> window.rename_window('libtmuxower')
Window(@10 1:libtmuxower, Session($3 foo))
Window(@... ...:libtmuxower, Session($... ...))
```

Split window (create a new pane):
Expand All @@ -135,8 +134,13 @@ Split window (create a new pane):
>>> pane = window.split_window()
>>> pane = window.split_window(attach=False)
>>> pane.select_pane()
Pane(%... Window(@... ...:..., Session($... libtmux_...)))
>>> window = session.new_window(attach=False, window_name="test")
>>> window
Window(@... ...:test, Session($...))
>>> pane = window.split_window(attach=False)
>>> pane
Pane(%... Window(@... ...:..., Session($... libtmux_...)))
```

Type inside the pane (send key strokes):
Expand All @@ -152,7 +156,8 @@ Grab the output of pane:

```python
>>> pane.clear() # clear the pane
>>> pane.send_keys('cowsay hello')
>>> pane.send_keys("cowsay 'hello'", enter=True)
>>> import time; time.sleep(1)
>>> print('\n'.join(pane.cmd('capture-pane', '-p').stdout))
```

Expand All @@ -170,9 +175,9 @@ Traverse and navigate:

```python
>>> pane.window
Window(@10 1:libtmuxower, Session($3 foo))
Window(@... ...:..., Session($... ...))
>>> pane.window.session
Session($3 foo)
Session($... ...)
```

# Python support
Expand Down
45 changes: 32 additions & 13 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ First, we can grab a {class}`Server`.
>>> import libtmux
>>> server = libtmux.Server()
>>> server
<libtmux.server.Server object at 0x7fbd622c1dd0>
<libtmux.server.Server object at ...>
```

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

```python
>>> server.list_sessions()
[Session($3 foo), Session($1 libtmux)]
[Session($... ...), Session($... ...)]
```

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

```python
>>> server.list_sessions()[0]
Session($... ...)
```

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

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

`$3` is whatever the ID `list_sessions()` returned above.
`$1` is whatever the ID `list_sessions()` returned above.

```python
>>> server.get_by_id('$3')
Session($3 foo)
>>> server.get_by_id('$1')
Session($... ...)
```

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

## Get session by name / other properties

```python
# Just for setting up the example:
>>> server.sessions[0].rename_session('foo')
Session($... foo)

>>> server.find_where({ "session_name": "foo" })
Session($3 foo)
Session($... foo)
```

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

```python
# Prepping the example:
>>> server.sessions[0].rename_session('foo')
Session($... foo)

>>> session = server.find_where({ "session_name": "foo" })
>>> session
Session($... foo)
```

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

```python
>>> session.new_window(attach=False, window_name="ha in the bg")
Window(@8 2:ha in the bg, Session($3 foo))
Window(@... ...:ha in the bg, Session($... ...))
```

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

```python
>>> session.kill_window("ha in")
>>> session.kill_window(window.id)
```

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

```python
>>> session.new_window(attach=False, window_name="ha in the bg")
Window(@11 3:ha in the bg, Session($3 foo))
Window(@... ...:ha in the bg, Session($... ...))
```

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

```python
# Setup
>>> session.new_window(attach=False, window_name="ha in the bg")
Window(@12 3:ha in the bg, Session($3 foo))
Window(@... ...:ha in the bg, Session($... ...))

>>> session.kill_window('ha in the bg')
```

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

```python
>>> window = session.new_window(attach=False, window_name="check this out")
>>> window
Window(@... ...:check this out, Session($... ...))
```

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

```python
>>> window = session.attached_window()
>>> window = session.attached_window
```

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

```python
>>> window.split_window(attach=False)
Pane(%23 Window(@10 1:bar, Session($3 foo)))
Pane(%... Window(@... ...:..., Session($... ...)))
```

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

```python
>>> window.rename_window('libtmuxower')
Window(@10 1:libtmuxower, Session($3 foo))
Window(@... ...:..., Session($... ...))
```

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

```python
>>> pane.select_pane()
Pane(%... Window(@... ...:..., Session($... ...)))
```

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


```

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

0 comments on commit 416507d

Please sign in to comment.