herocode/herolib_python
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
herolib_python/aiprompts/libtmux_python.md
despiegk bc0d90d41a ...
2025-08-22 13:11:04 +02:00

51 KiB
Raw Permalink Blame History

======================== 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