tessl/pypi-libtmux

Typed library that provides an ORM wrapper for tmux, a terminal multiplexer.

—

Pending

Overview

Eval results

Files

Window Management

Name: tessl/pypi-libtmux
Author: tessl

Window management in libtmux handles tmux window operations, pane organization, layout management, and window-specific configuration. Windows contain collections of panes and provide the primary workspace organization within sessions.

Capabilities

Window Initialization and Context

Create and manage window instances with proper resource management and context support.

@dataclasses.dataclass()
class Window(Obj):
    """
    tmux Window object.
    
    Holds Pane objects and inherits from Obj.
    """
    
    server: Server

    def __enter__(self) -> Self:
        """Enter the context, returning self."""
        
    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc_value: BaseException | None,
        exc_tb: types.TracebackType | None
    ) -> None:
        """Exit the context, killing the window if it exists."""

    @classmethod
    def from_window_id(cls, server: Server, window_id: str) -> Window:
        """Create Window from existing window_id."""

Window Information and Refresh

Access and update window state, properties, and attributes from tmux.

def refresh(self) -> None:
    """Refresh window attributes from tmux."""

@property
def id(self) -> str | None:
    """Alias of Window.window_id."""

@property
def name(self) -> str | None:
    """Alias of Window.window_name."""

@property
def index(self) -> str | None:
    """Alias of Window.window_index."""

@property
def height(self) -> str | None:
    """Alias of Window.window_height."""

@property  
def width(self) -> str | None:
    """Alias of Window.window_width."""

@property
def session(self) -> Session:
    """Parent session of window."""

@property
def active_pane(self) -> Pane | None:
    """Return attached Pane."""

Command Execution

Execute tmux commands within the window context.

def cmd(
    self,
    cmd: str,
    *args: t.Any,
    target: str | int | None = None
) -> tmux_cmd:
    """
    Execute tmux subcommand within window context.
    
    Automatically binds target by adding -t for object's window ID to the command.
    Pass target to keyword arguments to override.
    
    Parameters:
    - cmd: The tmux command to execute
    - *args: Additional command arguments
    - target: Optional custom target override (defaults to window ID)
    
    Returns:
    tmux_cmd object with stdout, stderr, and return code
    """

Pane Operations

Create, manage, and query panes within the window.

def split(
    self,
    /,
    target: int | str | None = None,
    start_directory: StrPath | None = None,
    attach: bool = False,
    direction: PaneDirection | None = None,
    full_window_split: bool | None = None,
    zoom: bool | None = None,
    shell: str | None = None,
    size: str | int | None = None,
    environment: dict[str, str] | None = None
) -> Pane:
    """
    Split window on active pane and return the created Pane.
    
    Parameters:
    - target: Target pane to split
    - start_directory: Working directory for new pane (str or PathLike)
    - attach: Make new window the current window after creating (default False)
    - direction: Split direction (PaneDirection enum)
    - full_window_split: Split across full window width/height rather than active pane
    - zoom: Expand pane
    - shell: Execute command on splitting the window
    - size: Cell/row or percentage to occupy with respect to current window
    - environment: Environmental variables for new pane (tmux 3.0+)
    
    Returns:
    Pane object for the created pane
    """

def select_pane(self, target_pane: str | int) -> Pane | None:
    """
    Select pane and return selected Pane.
    
    Parameters:
    - target_pane: Target pane ('-U', '-D', '-L', '-R', '-l', or pane ID)
    
    Returns:
    Selected Pane object
    """

def last_pane(self) -> Pane | None:
    """Return last pane."""

Window Layout Management

Control window layout, pane arrangement, and display organization.

def select_layout(self, layout: str | None = None) -> Window:
    """
    Select layout for window.
    
    Wrapper for $ tmux select-layout <layout>.
    
    Parameters:
    - layout: Layout name ('even-horizontal', 'even-vertical', 'main-horizontal', 
              'main-vertical', 'tiled', 'custom') or None for most recent layout
    
    Returns:
    Window instance for method chaining
    """

def resize(
    self,
    /,
    # Adjustments
    adjustment_direction: ResizeAdjustmentDirection | None = None,
    adjustment: int | None = None,
    # Manual
    height: int | None = None,
    width: int | None = None,
    # Expand / Shrink
    expand: bool | None = None,
    shrink: bool | None = None
) -> Window:
    """
    Resize tmux window.
    
    Parameters:
    - adjustment_direction: Direction to adjust (Up, Down, Left, Right)
    - adjustment: Amount to adjust by
    - height: resize-window -y dimensions
    - width: resize-window -x dimensions
    - expand: Expand window
    - shrink: Shrink window
    
    Returns:
    Window instance for method chaining
    
    Raises:
    LibTmuxException, WindowAdjustmentDirectionRequiresAdjustment
    """

Window Control and Navigation

Control window state, selection, and navigation within session.

def select(self) -> Window:
    """
    Select window.
    
    To select a window object asynchronously. If a window object exists
    and is no longer the current window, w.select() will make w the current window.
    
    Returns:
    Window instance for method chaining
    """

def move_window(
    self,
    destination: str = "",
    session: str | None = None
) -> Window:
    """
    Move current Window object $ tmux move-window.
    
    Parameters:
    - destination: Target window or index to move the window to (default: empty string)
    - session: Target session or index to move the window to (default: current session)
    
    Returns:
    Window instance for method chaining
    """

def new_window(
    self,
    window_name: str | None = None,
    *,
    start_directory: None = None,
    attach: bool = False,
    window_index: str = "",
    window_shell: str | None = None,
    environment: dict[str, str] | None = None,
    direction: WindowDirection | None = None
) -> Window:
    """
    Create new window respective of current window's position.
    
    Parameters:
    - window_name: Name for the new window
    - start_directory: Working directory for new window
    - attach: Make new window active after creation
    - window_index: Index position for new window
    - window_shell: Shell command to run in new window
    - environment: Environment variables for window (tmux 3.0+)
    - direction: Direction to insert window (tmux 3.2+)
    
    Returns:
    Window object for the created window
    """

Window Lifecycle

Control window renaming, termination, and lifecycle operations.

def rename_window(self, new_name: str) -> Window:
    """
    Rename window.
    
    Parameters:
    - new_name: New name for the window
    
    Returns:
    Window instance for method chaining
    """

def kill(
    self,
    all_except: bool | None = None
) -> None:
    """
    Kill Window.
    
    $ tmux kill-window.
    
    Parameters:
    - all_except: Kill all windows except this one
    """

Window Options

Configure window-level tmux options and settings.

def set_window_option(self, option: str, value: int | str) -> Window:
    """
    Set option for tmux window.
    
    Wraps $ tmux set-window-option <option> <value>.
    
    Parameters:
    - option: Option to set (e.g., 'aggressive-resize')
    - value: Window option value (True/False becomes 'on'/'off')
    
    Returns:
    Window instance for method chaining
    
    Raises:
    OptionError, UnknownOption, InvalidOption, AmbiguousOption
    """

def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
    """
    Return dict of options for window.
    
    Parameters:
    - g: Pass -g flag for global variable (default False)
    
    Returns:
    Dictionary of window option names and values
    """

def show_window_option(
    self,
    option: str,
    g: bool = False
) -> str | int | None:
    """
    Return option value for the target window.
    
    Parameters:
    - option: Option name
    - g: Pass -g flag, global (default False)
    
    Returns:
    Option value (str, int, or None if not found)
    
    Raises:
    OptionError, UnknownOption, InvalidOption, AmbiguousOption
    """

Collection Properties

Access collections of panes and active pane within the window.

@property
def panes(self) -> QueryList[Pane]:
    """
    Panes contained by window.
    
    Can be accessed via .panes.get() and .panes.filter()
    """

Usage Examples

Basic Window Operations

import libtmux

server = libtmux.Server()
session = server.new_session('work')
window = session.new_window('main')

# Get window information
print(f"Window ID: {window.id}")
print(f"Window Name: {window.name}")
print(f"Window Size: {window.width}x{window.height}")

# Refresh window state
window.refresh()

Context Manager Usage

import libtmux

server = libtmux.Server()
session = server.new_session('temp')

with session.new_window('work') as window:
    # Work with window
    pane = window.split_window()
    # Window automatically cleaned up on exit

Pane Management

import libtmux

server = libtmux.Server()
session = server.new_session('dev')
window = session.new_window('editor')

# Split window into panes
right_pane = window.split_window(vertical=True)
bottom_pane = window.split_window(vertical=False, target_pane=window.active_pane.id)

# Query panes
for pane in window.panes:
    print(f"Pane: {pane.id}")

# Select specific pane
window.select_pane(right_pane.id)

Layout Management

import libtmux

server = libtmux.Server()
session = server.new_session('layout_test')
window = session.new_window('main')

# Create multiple panes
window.split_window(vertical=True)
window.split_window(vertical=False)
window.split_window(vertical=True)

# Apply different layouts
window.select_layout('tiled')
window.select_layout('main-vertical')
window.select_layout('even-horizontal')

# Manual resize
window.resize('right', 10)

Window Options

import libtmux

server = libtmux.Server()
session = server.new_session('configured')
window = session.new_window('main')

# Set window options
window.set_window_option('automatic-rename', 'off')
window.set_window_option('monitor-activity', 'on')

# Get options
auto_rename = window.show_window_option('automatic-rename')
all_options = window.show_window_options()

# Rename window
window.rename_window('editor')

Install with Tessl CLI