diff --git a/CHANGES b/CHANGES index a12f0acc5..9e359ca63 100644 --- a/CHANGES +++ b/CHANGES @@ -33,6 +33,11 @@ Add `TestServer` pytest fixture for creating temporary tmux servers (#565): - Includes comprehensive test coverage and documentation - Available in doctest namespace +### Documentation + +- Fix links to the "Topics" section +- More docs for "Traversal" Topic (#567) + ## libtmux 0.42.1 (2024-02-15) ### Bug fixes diff --git a/docs/topics/traversal.md b/docs/topics/traversal.md index e26b8477e..5493ae7c4 100644 --- a/docs/topics/traversal.md +++ b/docs/topics/traversal.md @@ -22,81 +22,159 @@ Terminal two, `python` or `ptpython` if you have it: $ python ``` -Import `libtmux`: +## Setup + +First, create a test session: + +```python +>>> session = server.new_session() # Create a test session using existing server +``` + +## Server Level + +View the server's representation: + +```python +>>> server # doctest: +ELLIPSIS +Server(socket_name=...) +``` + +Get all sessions in the server: ```python -import libtmux +>>> server.sessions # doctest: +ELLIPSIS +[Session($... ...)] ``` -Attach default tmux {class}`~libtmux.Server` to `t`: +Get all windows across all sessions: ```python ->>> import libtmux ->>> t = libtmux.Server(); ->>> t -Server(socket_path=/tmp/tmux-.../default) +>>> server.windows # doctest: +ELLIPSIS +[Window(@... ..., Session($... ...))] ``` -Get first session {class}`~libtmux.Session` to `session`: +Get all panes across all windows: + +```python +>>> server.panes # doctest: +ELLIPSIS +[Pane(%... Window(@... ..., Session($... ...)))] +``` + +## Session Level + +Get first session: ```python >>> session = server.sessions[0] ->>> session -Session($1 ...) +>>> session # doctest: +ELLIPSIS +Session($... ...) ``` -Get a list of sessions: +Get windows in a session: ```python ->>> server.sessions -[Session($1 ...), Session($0 ...)] +>>> session.windows # doctest: +ELLIPSIS +[Window(@... ..., Session($... ...))] ``` -Iterate through sessions in a server: +Get active window and pane: ```python ->>> for sess in server.sessions: -... print(sess) -Session($1 ...) -Session($0 ...) +>>> session.active_window # doctest: +ELLIPSIS +Window(@... ..., Session($... ...)) + +>>> session.active_pane # doctest: +ELLIPSIS +Pane(%... Window(@... ..., Session($... ...))) ``` -Grab a {class}`~libtmux.Window` from a session: +## Window Level + +Get a window and inspect its properties: ```python ->>> session.windows[0] -Window(@1 ...:..., Session($1 ...)) +>>> window = session.windows[0] +>>> window.window_index # doctest: +ELLIPSIS +'...' ``` -Grab the currently focused window from session: +Access the window's parent session: ```python ->>> session.active_window -Window(@1 ...:..., Session($1 ...)) +>>> window.session # doctest: +ELLIPSIS +Session($... ...) +>>> window.session.session_id == session.session_id +True ``` -Grab the currently focused {class}`Pane` from session: +Get panes in a window: ```python ->>> session.active_pane -Pane(%1 Window(@1 ...:..., Session($1 ...))) +>>> window.panes # doctest: +ELLIPSIS +[Pane(%... Window(@... ..., Session($... ...)))] ``` -Assign the attached {class}`~libtmux.Pane` to `p`: +Get active pane: ```python ->>> p = session.active_pane +>>> window.active_pane # doctest: +ELLIPSIS +Pane(%... Window(@... ..., Session($... ...))) ``` -Access the window/server of a pane: +## Pane Level + +Get a pane and traverse upwards: ```python ->>> p = session.active_pane ->>> p.window -Window(@1 ...:..., Session($1 ...)) +>>> pane = window.panes[0] +>>> pane.window.window_id == window.window_id +True +>>> pane.session.session_id == session.session_id +True +>>> pane.server is server +True +``` + +## Filtering and Finding Objects ->>> p.server -Server(socket_name=libtmux_test...) +Find windows by index: + +```python +>>> session.windows.filter(window_index=window.window_index) # doctest: +ELLIPSIS +[Window(@... ..., Session($... ...))] +``` + +Get a specific pane by ID: + +```python +>>> window.panes.get(pane_id=pane.pane_id) # doctest: +ELLIPSIS +Pane(%... Window(@... ..., Session($... ...))) +``` + +## Checking Relationships + +Check if objects are related: + +```python +>>> window in session.windows +True +>>> pane in window.panes +True +>>> session in server.sessions +True +``` + +Check if a window is active: + +```python +>>> window.window_id == session.active_window.window_id +True +``` + +Check if a pane is active: + +```python +>>> pane.pane_id == window.active_pane.pane_id +True ``` [target]: http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#COMMANDS