From 0f213bcfc7f7fc39481eeb7aaf9285af31cd2ebb Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 10 Sep 2022 04:04:58 -0500 Subject: [PATCH 1/2] docs: Update doctests --- README.md | 45 +++++++++++---------- docs/quickstart.md | 43 ++++++++++++++------ docs/reference/properties.md | 77 +++++++++++++++--------------------- docs/topics/traversal.md | 31 ++++++++------- 4 files changed, 104 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index b30c501dc..9c751f3dd 100644 --- a/README.md +++ b/README.md @@ -53,9 +53,9 @@ Connect to a live tmux session: ```python >>> import libtmux ->>> server = libtmux.Server() ->>> server - +>>> s = libtmux.Server() +>>> s + ``` Tip: You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your @@ -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") @@ -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() ``` @@ -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): @@ -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): @@ -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)) ``` @@ -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 diff --git a/docs/quickstart.md b/docs/quickstart.md index bc28cdb51..f2cef0b99 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -108,7 +108,7 @@ First, we can grab a {class}`Server`. >>> import libtmux >>> server = libtmux.Server() >>> server - + ``` :::{tip} @@ -139,7 +139,7 @@ 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 @@ -147,6 +147,7 @@ find our current session with: ```python >>> server.list_sessions()[0] +Session($... ...) ``` However, this isn't guaranteed, libtmux works against current tmux information, the @@ -157,11 +158,11 @@ 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('$')` to use the session object. @@ -169,8 +170,12 @@ You may `session = server.get_by_id('$')` 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 @@ -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. @@ -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: @@ -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 @@ -234,14 +245,17 @@ 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` @@ -249,6 +263,8 @@ object: ```python >>> window = session.new_window(attach=False, window_name="check this out") +>>> window +Window(@... ...:check this out, Session($... ...)) ``` And kill: @@ -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`. @@ -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: @@ -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. @@ -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} diff --git a/docs/reference/properties.md b/docs/reference/properties.md index e89e227b4..a2061fa12 100644 --- a/docs/reference/properties.md +++ b/docs/reference/properties.md @@ -24,15 +24,16 @@ $ python Import libtmux: ```python -import libtmux +>>> import libtmux ``` Attach default tmux {class}`~libtmux.Server` to `t`: ```python +>>> import libtmux >>> t = libtmux.Server() >>> t - + ``` ## Session @@ -40,36 +41,26 @@ Attach default tmux {class}`~libtmux.Server` to `t`: Get the {class}`~libtmux.Session` object: ```python ->>> session = t.sessions[0] +>>> session = server.sessions[0] >>> session -Session($0 libtmux) +Session($... libtmux_...) ``` Quick access to basic attributes: ```python >>> session.name -'libtmux' +'libtmux_...' >>> session.id -'$0' - ->>> session.width -'213' - ->>> session.height -'114' +'$...' ``` To see all attributes for a session: ```python ->>> session._info.keys() -['session_height', 'session_windows', 'session_width', 'session_id', 'session_created', 'session_attached', 'session_grouped', 'session_name'] - ->>> session._info -{'session_height': '114', 'session_windows': '3', 'session_width': '213', 'session_id': '$0', 'session_created': '1464905357', 'session_attached': '1', 'session_grouped': '0', 'session_name': 'libtmux'} - +>>> sorted(list(session._info.keys())) +['session_attached', 'session_created', ...] ``` Some may conflict with python API, to access them, you can use `.get()`, to get the count @@ -77,7 +68,7 @@ of sessions in a window: ```python >>> session.get('session_windows') -'3' +'...' ``` ## Windows @@ -88,40 +79,37 @@ The same concepts apply for {class}`~libtmux.Window`: >>> window = session.attached_window >>> window -Window(@2 2:docs, Session($0 libtmux)) +Window(@... ...:..., Session($... ...)) ``` Basics: ```python >>> window.name -'docs' +'...' >>> window.id -'@2' +'@...' >>> window.height -'114' +'...' >>> window.width -'213' +'...' ``` Everything available: ```python ->>> window._info -{'window_panes': '4', 'window_active': '1', 'window_height': '114', 'window_activity_flag': '0', 'window_width': '213', 'session_id': '$0', 'window_id': '@2', 'window_layout': 'dad5,213x114,0,0[213x60,0,0,4,213x53,0,61{70x53,0,61,5,70x53,71,61,6,71x53,142,61,7}]', 'window_silence_flag': '0', 'window_index': '2', 'window_bell_flag': '0', 'session_name': 'libtmux', 'window_flags': '*', 'window_name': 'docs'} - ->>> window.keys() -['window_panes', 'window_active', 'window_height', 'window_activity_flag', 'window_width', 'session_id', 'window_id', 'window_layout', 'window_silence_flag', 'window_index', 'window_bell_flag', 'session_name', 'window_flags', 'window_name'] +>>> sorted(list(window.keys())) +['session_id', 'session_name', 'window_active', ..., 'window_width'] ``` Use `get()` for details not accessible via properties: ```python ->>> pane.get('window_panes') -'4' +>>> window.get('window_panes') +'1' ``` ## Panes @@ -132,40 +120,39 @@ Get the {class}`~libtmux.Pane`: >>> pane = window.attached_pane >>> pane -Pane(%5 Window(@2 2:docs, Session($0 libtmux))) +Pane(%... Window(@... ...:..., Session($... libtmux_...))) ``` Basics: ```python >>> pane.current_command -'python' +'...' + +>>> type(pane.current_command) + >>> pane.height -'53' +'...' >>> pane.width -'70' +'...' >>> pane.index -'1' +'0' ``` Everything: -```python ->>> pane._info -{'alternate_saved_x': '0', 'alternate_saved_y': '0', 'cursor_y': '47', 'cursor_x': '0', 'pane_in_mode': '0', 'insert_flag': '0', 'keypad_flag': '0', 'cursor_flag': '1', 'pane_current_command': 'python', 'window_index': '2', 'history_size': '216', 'scroll_region_lower': '52', 'keypad_cursor_flag': '0', 'history_bytes': '38778', 'pane_active': '1', 'pane_dead': '0', 'pane_synchronized': '0', 'window_id': '@2', 'pane_index': '1', 'pane_width': '70', 'mouse_any_flag': '0', 'mouse_button_flag': '0', 'window_name': 'docs', 'pane_current_path': '/Users/me/work/python/libtmux/doc', 'pane_tty': '/dev/ttys007', 'pane_title': 'Python REPL (ptpython)', 'session_id': '$0', 'alternate_on': '0', 'mouse_standard_flag': '0', 'wrap_flag': '1', 'history_limit': '2000', 'pane_pid': '37172', 'pane_height': '53', 'session_name': 'libtmux', 'scroll_region_upper': '0', 'pane_id': '%5'} - ->>> pane._info.keys() -['alternate_saved_x', 'alternate_saved_y', 'cursor_y', 'cursor_x', 'pane_in_mode', 'insert_flag', 'keypad_flag', 'cursor_flag', 'pane_current_command', 'window_index', 'history_size', 'scroll_region_lower', 'keypad_cursor_flag', 'history_bytes', 'pane_active', 'pane_dead', 'pane_synchronized', 'window_id', 'pane_index', 'pane_width', 'mouse_any_flag', 'mouse_button_flag', 'window_name', 'pane_current_path', 'pane_tty', 'pane_title', 'session_id', 'alternate_on', 'mouse_standard_flag', 'wrap_flag', 'history_limit', 'pane_pid', 'pane_height', 'session_name', 'scroll_region_upper', 'pane_id'] -``` +````python +>>> sorted(list(pane._info.keys())) +['alternate_on', 'alternate_saved_x', ..., 'wrap_flag'] Use `get()` for details keys: ```python >>> pane.get('pane_width') -'70' -``` +'...' +```` [formats]: http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#FORMATS diff --git a/docs/topics/traversal.md b/docs/topics/traversal.md index 3d8864f2c..a03b515c0 100644 --- a/docs/topics/traversal.md +++ b/docs/topics/traversal.md @@ -31,53 +31,55 @@ import libtmux Attach default tmux {class}`~libtmux.Server` to `t`: ```python +>>> import libtmux >>> t = libtmux.Server(); >>> t - + ``` Get first session {class}`~libtmux.Session` to `session`: ```python ->>> session = t.sessions[0] +>>> session = server.sessions[0] >>> session -Session($0 libtmux) +Session($... ...) ``` Get a list of sessions: ```python ->>> t.sessions -[Session($0 libtmux), Session($1 tmuxp)] +>>> server.sessions +[Session($... ...), Session($... ...)] ``` Iterate through sessions in a server: ```python ->>> for sess in t.sessions: +>>> for sess in server.sessions: ... print(sess) - -Session($0 libtmux) -Session($1 tmuxp) +Session($... ...) +Session($... ...) ``` Grab a {class}`~libtmux.Window` from a session: ```python >>> session.windows[0] -Window(@1 1:libtmux, Session($0 libtmux)) +Window(@... ...:..., Session($... ...)) ``` Grab the currently focused window from session: ```python >>> session.attached_window ->>> Window(@2 2:docs, Session($0 libtmux))grab the currently focused {class}`Pane` from session: +Window(@... ...:..., Session($... ...)) ``` +Grab the currently focused {class}`Pane` from session: + ```python >>> session.attached_pane -Pane(%5 Window(@2 2:docs, Session($0 libtmux))) +Pane(%... Window(@... ...:..., Session($... ...))) ``` Assign the attached {class}`~libtmux.Pane` to `p`: @@ -89,11 +91,12 @@ Assign the attached {class}`~libtmux.Pane` to `p`: Access the window/server of a pane: ```python +>>> p = session.attached_pane >>> p.window -Window(@2 2:docs, Session($0 libtmux)) +Window(@... ...:..., Session($... ...)) >>> p.server - + ``` [target]: http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#COMMANDS From 6e5a6cb509d967544b29f5d32e9d26ec66ae94f0 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 10 Sep 2022 05:42:26 -0500 Subject: [PATCH 2/2] docs(CHANGES): Note doc updates --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index f8623b128..8f07354fa 100644 --- a/CHANGES +++ b/CHANGES @@ -28,6 +28,7 @@ $ pip install --user --upgrade --pre libtmux ### Documentation - Move to sphinx-autoissues, #406 +- Examples updated for correctness, #412 (cherry-picked from #410) ## libtmux 0.14.2 (2022-08-17)