1762 lines
51 KiB
Markdown
1762 lines
51 KiB
Markdown
|
|
========================
|
|
CODE SNIPPETS
|
|
========================
|
|
TITLE: Initial Project Setup and Dependency Installation
|
|
DESCRIPTION: Steps to clone the `libtmux` repository, navigate into the project directory, and install all development dependencies using the `uv` package manager, including optional extras.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/developing.md#_snippet_0
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ git clone https://github.com/tmux-python/libtmux.git
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ cd libtmux
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ uv sync --all-extras --dev
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Install libtmux via pip
|
|
DESCRIPTION: Installs the libtmux library for the current user using pip. This is the standard installation method for stable releases.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_0
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ pip install --user libtmux
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Install libtmux developmental releases
|
|
DESCRIPTION: Installs pre-release versions (alpha, beta, release candidates) of libtmux using pip. This command is useful for testing new features before their general availability.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_1
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ pip install --user --upgrade --pre libtmux
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Install ptpython for command-line completion
|
|
DESCRIPTION: Installs ptpython, an interactive Python shell, to provide enhanced command-line completion for Python development. This is particularly useful when interacting with libtmux.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_4
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ pip install --user ptpython
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Install libtmux from Git trunk
|
|
DESCRIPTION: Installs libtmux directly from its Git repository's trunk in editable mode. This provides the very latest, potentially unstable, development version for active development or testing.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_2
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ pip install --user -e git+https://github.com/tmux-python/libtmux.git#egg=libtmux
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Building and Serving Project Documentation
|
|
DESCRIPTION: Instructions for generating and serving the project documentation using Sphinx and `sphinx-autobuild`. Commands cover starting a preview server, manual builds, and continuous rebuilding with a watch mode (requires `entr`).
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/developing.md#_snippet_2
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make start_docs
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make start
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ cd docs/
|
|
$ make html
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make serve
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make build_docs
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make serve_docs
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make watch_docs
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make dev_docs
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Start a new tmux session
|
|
DESCRIPTION: Initiates a new tmux session with a specified session name ('foo') and window name ('bar'). This command creates the initial environment for subsequent libtmux interactions.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_3
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ tmux new-session -n bar -s foo
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Starting tmux and Python for libtmux interaction
|
|
DESCRIPTION: This snippet demonstrates the initial setup required to interact with libtmux. It involves starting a tmux server in one terminal and then launching a Python interpreter in another to import the libtmux library.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/api/properties.md#_snippet_0
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ tmux
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ python
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> import libtmux
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Launch ptpython interactive shell
|
|
DESCRIPTION: Starts the ptpython interactive Python shell. This shell offers features like command-line completion for a more efficient and user-friendly development experience.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_5
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ ptpython
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: libtmux Python API Reference
|
|
DESCRIPTION: Key methods for interacting with tmux sessions, windows, and panes using the libtmux library.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_21
|
|
|
|
LANGUAGE: APIDOC
|
|
CODE:
|
|
```
|
|
Session Class Methods:
|
|
new_window(attach=True, window_name=None)
|
|
- Creates a new tmux window.
|
|
- Parameters:
|
|
- attach: (bool) If False, creates in background.
|
|
- window_name: (str) Optional name for the window.
|
|
- Returns: Window object.
|
|
|
|
kill_window(target)
|
|
- Kills a tmux window.
|
|
- Parameters:
|
|
- target: (str) Can be window_id (e.g., @2) or window_name (e.g., 'ha in the bg').
|
|
|
|
active_window()
|
|
- Returns the currently active Window object.
|
|
|
|
windows
|
|
- Property to access a list of Window objects.
|
|
|
|
windows.filter()
|
|
- Method to filter the list of Window objects.
|
|
|
|
Window Class Methods:
|
|
kill()
|
|
- Kills the specific window object.
|
|
|
|
split(attach=True)
|
|
- Splits the window into a new pane.
|
|
- Parameters:
|
|
- attach: (bool) If False, creates in background without switching cursor.
|
|
- Returns: Pane object.
|
|
|
|
rename_window(new_name)
|
|
- Renames the window.
|
|
- Parameters:
|
|
- new_name: (str) The new name for the window.
|
|
|
|
Pane Class Methods:
|
|
select()
|
|
- Selects (moves cursor to) the pane.
|
|
|
|
send_keys(keys, enter=True, suppress_history=False)
|
|
- Sends keys to the pane.
|
|
- Parameters:
|
|
- keys: (str) The string of keys to send.
|
|
- enter: (bool) If True, presses Enter after sending keys.
|
|
- suppress_history: (bool) If True, prevents command from appearing in shell history.
|
|
|
|
enter()
|
|
- Sends an Enter keypress to the pane.
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Getting the active tmux window with libtmux
|
|
DESCRIPTION: Demonstrates how to retrieve the currently active `Window` object from the session using `session.active_window`. This allows for subsequent manipulation of the current window.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_16
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window = session.active_window
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Launch ptpython Interactive Shell
|
|
DESCRIPTION: Shows how to start the `ptpython` interactive shell after its installation. This command initiates the enhanced Python environment for interactive coding and testing.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_3
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
ptpython
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Install libtmux Python Library
|
|
DESCRIPTION: Instructions on how to install the `libtmux` Python library using pip. This command installs the package for the current user, making it available for Python scripts and interactive shells.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_0
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
pip install --user libtmux
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Initialize libtmux Server object
|
|
DESCRIPTION: Imports the libtmux library and creates a Server object. This object serves as the primary interface for interacting with the tmux server, allowing control over sessions, windows, and panes.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_6
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
import libtmux
|
|
server = libtmux.Server()
|
|
server
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Execute raw tmux commands and instantiate objects
|
|
DESCRIPTION: Illustrates direct execution of tmux commands via `cmd()` methods on `Server`, `Session`, and `Window` objects to create new sessions, windows, and panes. Also demonstrates how to construct `Window` and `Pane` objects from their respective IDs returned by these raw commands.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_7
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.cmd('new-session', '-d', '-P', '-F#{session_id}').stdout[0]
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session.cmd('new-window', '-P').stdout[0]
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
Window.from_window_id(window_id=session.cmd('new-window', '-P', '-F#{window_id}').stdout[0], server=session.server)
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0]
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
Pane.from_pane_id(pane_id=window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0], server=window.server)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Install libtmux Python package
|
|
DESCRIPTION: This console command uses `pip` to install the `libtmux` library, which includes the pytest plugin and its associated fixtures, making them available for use in Python testing environments.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/pytest-plugin/index.md#_snippet_0
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
pip install libtmux
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Killing a tmux window directly from its object
|
|
DESCRIPTION: Illustrates how to obtain a `Window` object and then call its `kill()` method directly to close it. This provides an object-oriented way to manage windows.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_15
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window = session.new_window(attach=False, window_name="check this out")
|
|
window
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.kill()
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: List all tmux sessions
|
|
DESCRIPTION: Retrieves a list of all active tmux sessions as `Session` objects using `server.sessions`. This provides an overview of currently running tmux environments accessible through the libtmux Server object.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_8
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.sessions
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Access a specific session from the list
|
|
DESCRIPTION: Demonstrates accessing a specific `Session` object from the list returned by `server.sessions`, typically the first one. Note that the index is not guaranteed to be consistent if sessions are created or destroyed.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_9
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.sessions[0]
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Install ptpython for Enhanced Python Shell
|
|
DESCRIPTION: Provides the command to install `ptpython`, an interactive Python shell. `ptpython` offers advanced features like autocompletion and syntax highlighting, enhancing the development experience.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_2
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
pip install --user ptpython
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Renaming a tmux window with libtmux
|
|
DESCRIPTION: Shows how to rename the current tmux window using the `window.rename_window()` method. This updates the window's display name within tmux.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_18
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.rename_window('libtmuxower')
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Start tmux Server in Console
|
|
DESCRIPTION: Initiates a new tmux server instance in the console, typically run in a separate terminal to host sessions.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md#_snippet_0
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ tmux
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Accessing libtmux Pane Properties
|
|
DESCRIPTION: This section demonstrates how to get a `Pane` object from an active window and inspect its properties. It includes examples for `pane_current_command`, `pane_height`, `pane_width`, and `pane_index`, along with type checking.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/api/properties.md#_snippet_4
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> pane = window.active_pane
|
|
|
|
>>> pane
|
|
Pane(%1 Window(@1 ...:..., Session($1 libtmux_...)))
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> pane.pane_current_command
|
|
'...'
|
|
|
|
>>> type(pane.pane_current_command)
|
|
<class 'str'>
|
|
|
|
>>> pane.pane_height
|
|
'...'
|
|
|
|
>>> pane.pane_width
|
|
'...'
|
|
|
|
>>> pane.pane_index
|
|
'0'
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Assign a retrieved session to a variable
|
|
DESCRIPTION: Demonstrates the common pattern of renaming a session and then retrieving it by its new name to assign it to a variable for further manipulation. This establishes a working `Session` object for subsequent operations.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_12
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.sessions[0].rename_session('foo')
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session = server.sessions.get(session_name="foo")
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Tagging and Releasing New Versions
|
|
DESCRIPTION: Steps for preparing a new release, including updating version information in `CHANGES` and `__init__.py`, committing changes with a specific message, and creating Git tags. These actions trigger CI/CD for deployment to PyPI.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/developing.md#_snippet_6
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ git commit -m 'Tag v0.9.1'
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ git tag v0.9.1
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ git push
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ git push --tags
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
git commit -m 'build(libtmux): Tag v0.1.1'
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
git tag v0.1.1
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Creating a new tmux window with libtmux
|
|
DESCRIPTION: Demonstrates how to create a new tmux window using `session.new_window()`. The `attach=False` argument creates the window in the background without switching to it. A custom `window_name` can be specified. The method returns the created `Window` object.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_13
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session.new_window(attach=False, window_name="ha in the bg")
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Rename and retrieve sessions by name
|
|
DESCRIPTION: Shows how to rename a tmux session using `rename_session()` and subsequently retrieve it using `server.sessions.filter()` or `server.sessions.get()` with the new session name. This illustrates session management by name.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_11
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.sessions[0].rename_session('foo')
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.sessions.filter(session_name="foo")[0]
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.sessions.get(session_name="foo")
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Launch Python Interpreter
|
|
DESCRIPTION: Starts the Python interpreter in the console, enabling execution of Python code. Can be `python` or `ptpython`.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md#_snippet_1
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ python
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Running Project Tests
|
|
DESCRIPTION: Commands to execute the test suite using `pytest` via `uv` or `make`. Includes a helper command for basic test execution and a watch mode for continuous testing on file changes (requires `entr`).
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/developing.md#_snippet_1
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ uv run py.test
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make test
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make watch_test
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Start tmux session in console
|
|
DESCRIPTION: Initiates a new tmux server session in the console, providing the environment for libtmux interactions.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_0
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
tmux
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Formatting Code with Ruff Format
|
|
DESCRIPTION: Commands to automatically format Python code using `ruff format`. These can be run via `uv`, directly with `ruff format`, or through a `make` target.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/developing.md#_snippet_4
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ uv run ruff format .
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ ruff format .
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make ruff_format
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Splitting a tmux window into a new pane with libtmux
|
|
DESCRIPTION: Explains how to split the current window into a new pane using `window.split()`. The `attach=False` argument prevents the cursor from switching to the newly created pane. The method returns the new `Pane` object.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_17
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.split(attach=False)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Launch Python interpreter in console
|
|
DESCRIPTION: Starts the Python interpreter in the console, ready for interactive commands and libtmux script execution.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_1
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
python
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Filter sessions by ID
|
|
DESCRIPTION: Filters the list of sessions to find a specific session using its tmux ID (e.g., '$1') via `server.sessions.filter()`. This provides a reliable way to retrieve a session by its unique identifier.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_10
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.sessions.filter(session_id='$1')[0]
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Killing a tmux window by ID or name using libtmux
|
|
DESCRIPTION: Shows how to terminate a tmux window using `session.kill_window()`. This method accepts either the window's ID (e.g., `@2`) or its name as a target. It's equivalent to the `tmux kill-window -t` command.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_14
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session.kill_window(window.window_id)
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session.kill_window('ha in the bg')
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Moving cursor across tmux windows and panes with libtmux
|
|
DESCRIPTION: Illustrates how to control cursor movement when creating new panes or explicitly selecting existing ones. Omitting `attach=False` in `window.split()` moves the cursor, or `pane.select()` can be used for explicit selection.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_19
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
pane = window.split()
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
pane = window.split(attach=False)
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
pane.select()
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Get all tmux windows from libtmux Server
|
|
DESCRIPTION: Retrieves a list of all tmux windows across all sessions managed by the libtmux server object.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_5
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.windows
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Get all tmux panes from libtmux Server
|
|
DESCRIPTION: Retrieves a list of all tmux panes across all windows managed by the libtmux server object.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_6
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.panes
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Sending commands to tmux panes remotely with libtmux
|
|
DESCRIPTION: Details how to send keyboard inputs and commands to a tmux pane using `pane.send_keys()`. It covers sending keys without pressing Enter (`enter=False`), explicitly pressing Enter (`pane.enter()`), and suppressing commands from shell history (`suppress_history=True`).
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md#_snippet_20
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window = session.new_window(attach=False, window_name="test")
|
|
pane = window.split(attach=False)
|
|
pane.send_keys('echo hey', enter=False)
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
pane.enter()
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
pane.send_keys('echo Howdy', enter=True, suppress_history=True)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Get windows within a tmux session
|
|
DESCRIPTION: Retrieves a list of all windows belonging to a specific libtmux session object, enabling navigation within that session.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_8
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session.windows
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Linting and Fixing Code with Ruff
|
|
DESCRIPTION: Commands to perform code linting and automatic fixes using the `ruff` tool. This includes execution via `uv`, direct `ruff` commands, `make` targets, and a watch mode for continuous linting (requires `entr`).
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/developing.md#_snippet_3
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ uv run ruff
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ ruff check .
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make ruff
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make watch_ruff
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ uv run ruff check . --fix
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ ruff check . --fix
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Create a New tmux Session via Console
|
|
DESCRIPTION: Demonstrates how to create a new tmux session directly from the terminal using the `tmux` command-line utility. This example sets the session name to 'foo' and the initial window name to 'bar'.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_1
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
tmux new-session -s foo -n bar
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Performing Static Type Checks with Mypy
|
|
DESCRIPTION: Commands to run static type analysis on the project using `mypy`. Options include running via `uv`, direct `mypy` commands, `make` targets, and a watch mode for continuous type checking (requires `entr`).
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/developing.md#_snippet_5
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ uv run mypy .
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ mypy .
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make mypy
|
|
```
|
|
|
|
LANGUAGE: console
|
|
CODE:
|
|
```
|
|
$ make watch_mypy
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Get panes within a tmux window
|
|
DESCRIPTION: Retrieves a list of all panes belonging to a specific libtmux window object, enabling navigation within that window.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_12
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.panes
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Get active pane in a tmux window
|
|
DESCRIPTION: Retrieves the currently active pane within a specific libtmux window object, indicating the current focus.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_13
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.active_pane
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Get all tmux sessions from libtmux Server
|
|
DESCRIPTION: Retrieves a list of all active tmux sessions managed by the libtmux server object, allowing iteration and access to individual sessions.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_4
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.sessions
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Get active window and pane in a tmux session
|
|
DESCRIPTION: Retrieves the currently active window and pane within a specific libtmux session object, useful for understanding the current focus.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_9
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session.active_window
|
|
|
|
>>> session.active_pane
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Get specific tmux pane by ID
|
|
DESCRIPTION: Retrieves a specific pane from a window's panes collection using its unique 'pane_id', allowing direct access to a pane.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_16
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.panes.get(pane_id=pane.pane_id)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Create and manage temporary tmux servers in pytest
|
|
DESCRIPTION: The `TestServer` fixture provides a factory for creating independent, temporary tmux server instances with unique socket names. This allows testing scenarios involving multiple servers or custom configurations, ensuring automatic cleanup after tests. The second example shows how to use it with a custom configuration file.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/pytest-plugin/index.md#_snippet_2
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
def test_something(TestServer):
|
|
Server = TestServer() # Get unique partial'd Server
|
|
server = Server() # Create server instance
|
|
|
|
session = server.new_session()
|
|
assert server.is_alive()
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
def test_with_config(TestServer, tmp_path):
|
|
config_file = tmp_path / "tmux.conf"
|
|
config_file.write_text("set -g status off")
|
|
|
|
Server = TestServer()
|
|
server = Server(config_file=str(config_file))
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Connecting to a libtmux Server
|
|
DESCRIPTION: This snippet shows how to establish a connection to the default tmux server using `libtmux.Server()`. It initializes a Server object, which then allows interaction with tmux sessions, windows, and panes.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/api/properties.md#_snippet_1
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> import libtmux
|
|
>>> t = libtmux.Server()
|
|
>>> t
|
|
Server(socket_path=/tmp/tmux-.../default)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: libtmux.Session Class API Reference
|
|
DESCRIPTION: Comprehensive API documentation for the `libtmux.Session` class, which represents a tmux session. This class manages windows and panes, and provides methods for interacting with a tmux session programmatically. It exists within a `libtmux.Server` instance and is identified by a '$' prefix.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/api/sessions.md#_snippet_0
|
|
|
|
LANGUAGE: APIDOC
|
|
CODE:
|
|
```
|
|
libtmux.Session Class:
|
|
Represents a tmux session, a fundamental unit within the tmux terminal multiplexer.
|
|
|
|
Inheritance:
|
|
- Inherits from `libtmux.common.TMUX` (implied by context and typical libtmux structure)
|
|
|
|
Attributes:
|
|
- id (str): The unique identifier for the session, typically prefixed with '$' (e.g., '$313').
|
|
- server (libtmux.Server): A reference to the parent `libtmux.Server` instance that contains this session.
|
|
- windows (list[libtmux.Window]): A list of `libtmux.Window` objects currently open within this session.
|
|
- name (str): The name of the session.
|
|
|
|
Methods (common examples, full list generated by autoclass):
|
|
- attach(): Attaches the current terminal to this tmux session.
|
|
- kill_session(): Terminates and removes this tmux session.
|
|
- new_window(attach: bool = True, window_name: str = None, start_directory: str = None) -> libtmux.Window:
|
|
Creates a new window within this session.
|
|
- attach (bool): If True, attach to the new window immediately.
|
|
- window_name (str): Optional name for the new window.
|
|
- start_directory (str): Optional starting directory for the new window.
|
|
- Returns: The newly created `libtmux.Window` object.
|
|
- find_where(attribute: str, value: str) -> Union[libtmux.Window, libtmux.Pane, None]:
|
|
Finds a window or pane within the session based on an attribute and its value.
|
|
- select_window(target_window: Union[str, int, libtmux.Window]):
|
|
Selects a specific window within the session by name, index, or object.
|
|
- rename_session(new_name: str):
|
|
Renames the current session to `new_name`.
|
|
- list_windows() -> list[libtmux.Window]:
|
|
Returns a list of all `libtmux.Window` objects in the session.
|
|
- find_window(target_window: Union[str, int]) -> Union[libtmux.Window, None]:
|
|
Finds a window by name or index within the session.
|
|
- attached_window() -> libtmux.Window:
|
|
Returns the currently attached window in the session.
|
|
- attached_pane() -> libtmux.Pane:
|
|
Returns the currently attached pane in the session.
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Split tmux Windows and Create Panes with libtmux
|
|
DESCRIPTION: Illustrates how to split a tmux window into new panes and create entirely new windows using `libtmux`. It covers creating panes both attached and detached, selecting panes, and initializing new windows with specific names.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_15
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> window = session.active_window
|
|
>>> window.split(attach=False)
|
|
Pane(%2 Window(@1 1:... Session($1 ...)))
|
|
>>> pane = window.split()
|
|
>>> pane = window.split(attach=False)
|
|
>>> pane.select()
|
|
Pane(%3 Window(@1 1:..., Session($1 ...)))
|
|
>>> window = session.new_window(attach=False, window_name="test")
|
|
>>> window
|
|
Window(@2 2:test, Session($1 ...))
|
|
>>> pane = window.split(attach=False)
|
|
>>> pane
|
|
Pane(%5 Window(@2 2:test, Session($1 ...)))
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: libtmux Server Context Manager Usage
|
|
DESCRIPTION: Demonstrates using `libtmux.Server()` as a context manager. A temporary tmux server is created and automatically killed upon exiting the `with` block, ensuring resource cleanup.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md#_snippet_3
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
with Server() as server:
|
|
session = server.new_session()
|
|
print(server.is_alive())
|
|
True
|
|
print(server.is_alive())
|
|
False
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Connect to tmux Server using libtmux in Python
|
|
DESCRIPTION: Illustrates how to import the `libtmux` library and establish a connection to the default tmux server. The `Server()` object represents the active tmux server instance, allowing for subsequent programmatic control.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_4
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
import libtmux
|
|
svr = libtmux.Server()
|
|
svr
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Split Window and Create Pane via libtmux Command
|
|
DESCRIPTION: Demonstrates how to split an existing tmux window and create a new pane using the `window.cmd()` method in `libtmux`. This command returns the ID of the newly created pane, which can then be used to interact with it programmatically.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_8
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0]
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Instantiate libtmux Window Object from ID
|
|
DESCRIPTION: Explains how to construct a `Window` object in `libtmux` directly from its window ID. This method is crucial for obtaining a rich, interactive object representation from raw command output, allowing for detailed control over specific windows.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_7
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
Window.from_window_id(window_id=session.cmd('new-window', '-P', '-F#{window_id}').stdout[0], server=session.server)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: libtmux Relational Object Model
|
|
DESCRIPTION: This documentation outlines the hierarchical relationships between the core `libtmux` objects: `Server`, `Session`, `Window`, and `Pane`. It illustrates how these objects are connected, defining their parent-child dependencies within the `libtmux` abstraction.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/about.md#_snippet_0
|
|
|
|
LANGUAGE: APIDOC
|
|
CODE:
|
|
```
|
|
Object | Child | Parent
|
|
---------------- | ---------------- | ----------------
|
|
{class}`Server` | {class}`Session` | None
|
|
{class}`Session` | {class}`Window` | {class}`Server`
|
|
{class}`Window` | {class}`Pane` | {class}`Session`
|
|
{class}`Pane` | None | {class}`Window`
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Execute Raw tmux Commands with libtmux Server
|
|
DESCRIPTION: Demonstrates how to execute arbitrary tmux commands using the `server.cmd()` method in `libtmux`. This method allows direct interaction with the tmux server, respecting the configured socket name, and can be used to display messages or create new sessions.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_5
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server = Server(socket_name='libtmux_doctest')
|
|
server.cmd('display-message', 'hello world')
|
|
server.cmd('new-session', '-d', '-P', '-F#{session_id}').stdout[0]
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Import libtmux Library
|
|
DESCRIPTION: Imports the `libtmux` library into a Python environment, making its functionalities available for use.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md#_snippet_2
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
import libtmux
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Send Keystrokes to tmux Panes with libtmux
|
|
DESCRIPTION: Explains how to send keyboard inputs to a tmux pane using `pane.send_keys()`. It covers sending a complete command with an implicit Enter, and sending parts of a command followed by an explicit `pane.enter()` call.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_16
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> pane.send_keys('echo hey send now')
|
|
|
|
>>> pane.send_keys('echo hey', enter=False)
|
|
>>> pane.enter()
|
|
Pane(%1 ...)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: libtmux Window Context Manager Usage
|
|
DESCRIPTION: Shows how to use `session.new_window()` as a context manager. A temporary tmux window is created and automatically closed upon exiting the `with` block.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md#_snippet_5
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server = Server()
|
|
session = server.new_session()
|
|
with session.new_window() as window:
|
|
print(window in session.windows)
|
|
pane = window.split()
|
|
True
|
|
print(window in session.windows)
|
|
False
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Dynamically Activate Sidebar Navigation Links
|
|
DESCRIPTION: This JavaScript snippet identifies sidebar navigation links that point to the current hostname. If a link is not already marked as 'active', it replaces the anchor tag with a `<span>` element, applying an 'active' class to visually indicate the current page without altering the URL.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/_templates/sidebar/projects.html#_snippet_0
|
|
|
|
LANGUAGE: javascript
|
|
CODE:
|
|
```
|
|
(() => {
|
|
const sidebar = document.getElementById("sidebar-projects");
|
|
sidebar.querySelectorAll(`a[href*="${window.location.hostname}"]`)
|
|
.forEach((link) => {
|
|
if (!link.classList.contains("active")) {
|
|
const d = document.createElement('span');
|
|
d.innerHTML = link.innerHTML;
|
|
d.classList.add("active");
|
|
link.parentNode.replaceChild(d, link);
|
|
}
|
|
});
|
|
})()
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Create New Window via Session Command in libtmux
|
|
DESCRIPTION: Shows how to create a new window within an existing tmux session using the `session.cmd()` method. This command returns the ID of the newly created window in a formatted string, enabling further programmatic manipulation.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_6
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session.cmd('new-window', '-P').stdout[0]
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Instantiate libtmux Pane Object from ID
|
|
DESCRIPTION: Illustrates how to create a `Pane` object in `libtmux` directly from its pane ID. This allows for programmatic interaction with a specific pane based on its identifier, providing a structured way to manage pane properties and content.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_9
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
Pane.from_pane_id(pane_id=window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0], server=window.server)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: libtmux Session Context Manager Usage
|
|
DESCRIPTION: Illustrates using `server.new_session()` as a context manager. A temporary tmux session is created and automatically killed when the `with` block is exited, ensuring proper cleanup.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md#_snippet_4
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server = Server()
|
|
with server.new_session() as session:
|
|
print(session in server.sessions)
|
|
window = session.new_window()
|
|
True
|
|
print(session in server.sessions)
|
|
False
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: libtmux Pane Context Manager Usage
|
|
DESCRIPTION: Demonstrates using `window.split()` as a context manager for a tmux pane. The pane is automatically killed and removed when the `with` block is exited.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md#_snippet_6
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server = Server()
|
|
session = server.new_session()
|
|
window = session.new_window()
|
|
with window.split() as pane:
|
|
print(pane in window.panes)
|
|
pane.send_keys('echo "Hello"')
|
|
True
|
|
print(pane in window.panes)
|
|
False
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Create New Background Window in libtmux Session
|
|
DESCRIPTION: Illustrates how to create a new tmux window within a session without immediately attaching to it, using `session.new_window(attach=False)`. It also shows how to search for and retrieve this newly created window using filtering methods.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_12
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
bg_window = session.new_window(attach=False, window_name="ha in the bg")
|
|
bg_window
|
|
session.windows.filter(window_name__startswith="ha")
|
|
session.windows.get(window_name__startswith="ha")
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Rename tmux Windows using libtmux
|
|
DESCRIPTION: Shows how to rename an existing tmux window programmatically using the `rename_window()` method of a window object in `libtmux`. This allows for dynamic naming of windows.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_14
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> window.rename_window('libtmuxower')
|
|
Window(@1 1:libtmuxower, Session($1 ...))
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Accessing libtmux Window Properties
|
|
DESCRIPTION: This snippet illustrates how to obtain a `Window` object from an active session and access its fundamental properties. It covers retrieving `window_name`, `window_id`, `window_height`, `window_width`, and `window_panes`.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/api/properties.md#_snippet_3
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> window = session.active_window
|
|
|
|
>>> window
|
|
Window(@1 ...:..., Session($1 ...))
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> window.window_name
|
|
'...'
|
|
|
|
>>> window.window_id
|
|
'@1'
|
|
|
|
>>> window.window_height
|
|
'...'
|
|
|
|
>>> window.window_width
|
|
'...'
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> window.window_panes
|
|
'1'
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Close tmux Windows using libtmux
|
|
DESCRIPTION: Demonstrates how to programmatically close or kill tmux windows using the `libtmux` Python library. This involves calling the `kill()` method on a window object to terminate it.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_13
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> bg_window.kill()
|
|
>>> w = session.active_window
|
|
>>> w.kill()
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: List and Filter tmux Sessions using libtmux
|
|
DESCRIPTION: Shows how to retrieve a list of all active tmux sessions via `server.sessions`. It also demonstrates filtering sessions by attributes like `history_limit` and performing direct lookups by `session_id` or `session_name` for precise session management.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_10
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server.sessions
|
|
server.sessions.filter(history_limit='2000')
|
|
server.sessions.get(session_id="$1")
|
|
server.sessions[0].rename_session('foo')
|
|
server.sessions.filter(session_name="foo")
|
|
server.sessions.get(session_name="foo")
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: libtmux.Pane Class API Documentation Directive
|
|
DESCRIPTION: This reStructuredText directive specifies the generation of comprehensive API documentation for the `libtmux.Pane` Python class. It instructs Sphinx to include all public, private, and inherited members, along with the class's inheritance hierarchy, ordered by source.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/api/panes.md#_snippet_0
|
|
|
|
LANGUAGE: APIDOC
|
|
CODE:
|
|
```
|
|
.. autoclass:: libtmux.Pane
|
|
:members:
|
|
:inherited-members:
|
|
:private-members:
|
|
:show-inheritance:
|
|
:member-order: bysource
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: tmux Object Identifiers and Lookup
|
|
DESCRIPTION: This section details the unique identifiers used by tmux for its various objects (Session, Window, Pane) and how `libtmux` utilizes these IDs for lookup and management. It also clarifies the distinction between unique IDs and positional indices within tmux.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/about.md#_snippet_1
|
|
|
|
LANGUAGE: APIDOC
|
|
CODE:
|
|
```
|
|
Object | Prefix | Example
|
|
---------------- | ------ | -----------------------------------------
|
|
{class}`Server` | N/A | N/A, uses `socket-name` and `socket-path`
|
|
{class}`Session` | `$` | `$13`
|
|
{class}`Window` | `@` | `@3243`
|
|
{class}`Pane` | `%` | `%5433`
|
|
|
|
Tmux has unique IDs for sessions, windows and panes.
|
|
panes use `%`, such as `%1234`
|
|
windows use `@`, such as `@2345`
|
|
sessions use `$`, such as `$13`
|
|
|
|
Tmux provides `window_id` as a unique identifier.
|
|
|
|
What is a {pane,window}_index vs a {pane,window,session}_id?
|
|
Pane index refers to the order of a pane on the screen.
|
|
Window index refers to the number of the window in the session.
|
|
To assert pane, window and session data, libtmux will use
|
|
{meth}`Server.sessions()`, {meth}`Session.windows()`,
|
|
{meth}`Window.panes()` to update objects.
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Traverse tmux Objects in libtmux
|
|
DESCRIPTION: Shows how to navigate the object hierarchy within `libtmux`, specifically accessing the parent window from a pane object and the parent session from a window object. This is useful for contextual operations.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_18
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> pane.window
|
|
Window(@1 1:..., Session($1 ...))
|
|
>>> pane.window.session
|
|
Session($1 ...)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Capture Output from tmux Panes using libtmux
|
|
DESCRIPTION: Demonstrates how to clear a tmux pane and then capture its output after executing a command. This involves using `pane.clear()` to reset the pane and `pane.cmd('capture-pane', '-p').stdout` to retrieve the pane's content.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_17
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> pane.clear() # clear the pane
|
|
Pane(%1 ...)
|
|
>>> pane.send_keys("cowsay 'hello'", enter=True)
|
|
>>> print('\n'.join(pane.cmd('capture-pane', '-p').stdout)) # doctest: +SKIP
|
|
$ cowsay 'hello'
|
|
_______
|
|
< hello >
|
|
-------
|
|
\ ^__^
|
|
\ (oo)\_______
|
|
(__)\ )\/\
|
|
||----w |
|
|
|| ||
|
|
...
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Accessing libtmux Session Properties
|
|
DESCRIPTION: This section demonstrates how to retrieve a `Session` object and access its basic attributes like `session_name` and `session_id`. It also shows how to inspect all available attributes using `Obj.__dataclass_fields__.keys()` and access `session_windows`.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/api/properties.md#_snippet_2
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> session = server.sessions[0]
|
|
>>> session
|
|
Session($1 libtmux_...)
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> session.session_name
|
|
'libtmux_...'
|
|
|
|
>>> session.session_id
|
|
'$1'
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
from libtmux.neo import Obj
|
|
|
|
>>> sorted(list(Obj.__dataclass_fields__.keys()))
|
|
['session_attached', 'session_created', ...]
|
|
```
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
>>> session.session_windows
|
|
'...'
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Control and Rename tmux Sessions using libtmux
|
|
DESCRIPTION: Demonstrates how to interact with a `Session` object in `libtmux`, specifically showing how to rename an existing tmux session programmatically. This allows for dynamic adjustment of session identifiers.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/README.md#_snippet_11
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session
|
|
session.rename_session('my-session')
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Set a temporary home directory for pytest tests
|
|
DESCRIPTION: This pytest fixture demonstrates how to temporarily set the `HOME` environment variable to a test-specific path. This is useful for isolating tests that rely on user-specific configuration files, such as `.tmux.conf`, ensuring a clean state for each test run by using `monkeypatch`.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/pytest-plugin/index.md#_snippet_3
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
import pathlib
|
|
import pytest
|
|
|
|
@pytest.fixture(autouse=True, scope="function")
|
|
def set_home(
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
user_path: pathlib.Path,
|
|
):
|
|
monkeypatch.setenv("HOME", str(user_path))
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Access and inspect first tmux session
|
|
DESCRIPTION: Accesses the first session from the list of server sessions and displays its object representation, demonstrating how to select a specific session.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_7
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session = server.sessions[0]
|
|
>>> session
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Access and inspect tmux window properties
|
|
DESCRIPTION: Accesses the first window from a session and displays its 'window_index' property, illustrating how to retrieve window-specific attributes.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_10
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window = session.windows[0]
|
|
>>> window.window_index
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Traverse up hierarchy from tmux pane
|
|
DESCRIPTION: Accesses the first pane from a window and demonstrates traversing up the object hierarchy to its parent window, session, and server, verifying their IDs and relationships.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_14
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
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
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Nested libtmux Context Managers for Cleanup
|
|
DESCRIPTION: Showcases nesting `libtmux` context managers (server, session, window, pane) for hierarchical cleanup. All tmux objects are automatically cleaned up in reverse order upon exiting the outermost `with` block.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md#_snippet_7
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
with Server() as server:
|
|
with server.new_session() as session:
|
|
with session.new_window() as window:
|
|
with window.split() as pane:
|
|
pane.send_keys('echo "Hello"')
|
|
# Do work with the pane
|
|
# Everything is cleaned up automatically when exiting contexts
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Inspect libtmux Server object
|
|
DESCRIPTION: Displays the representation of the libtmux server object, showing its current state and properties, such as the socket name.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_3
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
server
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Create new tmux session with libtmux
|
|
DESCRIPTION: Creates a new tmux session programmatically using the libtmux server object. This establishes a test session for further operations and object traversal.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_2
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session = server.new_session()
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Customize tmux session parameters in pytest
|
|
DESCRIPTION: This Python fixture demonstrates how to override default session parameters for a tmux session created by the libtmux pytest plugin. It sets the session's initial dimensions (x and y) which are then passed to `Server.new_session` when a new session is created.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/pytest-plugin/index.md#_snippet_1
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
import pytest
|
|
|
|
@pytest.fixture
|
|
def session_params():
|
|
return {
|
|
'x': 800,
|
|
'y': 600
|
|
}
|
|
|
|
|
|
def test_something(session):
|
|
assert session
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Filter tmux windows by index
|
|
DESCRIPTION: Filters the list of windows within a session to find specific windows based on their 'window_index' property, demonstrating object filtering capabilities.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_15
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
session.windows.filter(window_index=window.window_index)
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Check object relationships in libtmux hierarchy
|
|
DESCRIPTION: Verifies if a window is part of a session's windows, a pane is part of a window's panes, and a session is part of the server's sessions, confirming hierarchical integrity.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_17
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window in session.windows
|
|
True
|
|
>>> pane in window.panes
|
|
True
|
|
>>> session in server.sessions
|
|
True
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Access parent session from tmux window
|
|
DESCRIPTION: Retrieves the parent session object from a libtmux window and verifies its ID matches the original session, demonstrating upward traversal.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_11
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.session
|
|
>>> window.session.session_id == session.session_id
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Check if tmux window is active
|
|
DESCRIPTION: Compares a window's ID with the active window's ID in the current session to determine if it is the active window.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_18
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
window.window_id == session.active_window.window_id
|
|
```
|
|
|
|
----------------------------------------
|
|
|
|
TITLE: Check if tmux pane is active
|
|
DESCRIPTION: Compares a pane's ID with the active pane's ID in the current window to determine if it is the active pane.
|
|
|
|
SOURCE: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md#_snippet_19
|
|
|
|
LANGUAGE: python
|
|
CODE:
|
|
```
|
|
pane.pane_id == window.active_pane.pane_id
|
|
``` |