tessl/pypi-i3ipc
Python library for controlling the i3 window manager and sway compositor through their IPC interface
—
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Pending
The risk profile of this skill
index.mddocs/
i3ipc
A comprehensive Python library for controlling the i3 window manager and sway compositor through their IPC (Inter-Process Communication) interface. Provides complete access to window manager functionality including workspace management, window manipulation, event subscriptions, and real-time monitoring of window manager state.
Package Information
- Package Name: i3ipc
- Language: Python
- Installation:
pip install i3ipc
Core Imports
import i3ipcFor connection-based usage:
from i3ipc import Connection, Event, ConFor async usage:
from i3ipc.aio import Connection, Con
from i3ipc import EventBasic Usage
import i3ipc
# Connect to i3/sway
i3 = i3ipc.Connection()
# Get and display workspace information
workspaces = i3.get_workspaces()
for ws in workspaces:
print(f"Workspace {ws.name}: {'visible' if ws.visible else 'hidden'}")
# Navigate the window tree
tree = i3.get_tree()
focused = tree.find_focused()
if focused:
print(f"Focused window: {focused.name}")
# Execute window manager commands
i3.command('workspace 2')
i3.command('split horizontal')
i3.command('exec firefox')
# Subscribe to events
def on_window_focus(i3, event):
print(f"Window focused: {event.container.name}")
i3.on(i3ipc.Event.WINDOW_FOCUS, on_window_focus)
i3.main() # Start event loopArchitecture
The i3ipc library is built around a central Connection class that communicates with i3/sway via Unix domain sockets. It uses the IPC protocol to send commands and receive structured responses. The library provides both synchronous and asynchronous interfaces, comprehensive event handling, and object-oriented representations of window manager entities like containers, workspaces, and outputs.
Capabilities
Connection Management
Establish and manage connections to i3/sway, handle reconnection, and execute core IPC operations.
class Connection:
def __init__(self, socket_path=None, auto_reconnect=False):
"""
Create a connection to the i3/sway IPC socket.
Parameters:
- socket_path: Optional[str], path to IPC socket (auto-detected if None)
- auto_reconnect: bool, whether to reconnect automatically on disconnect
"""
def command(self, payload: str) -> List[CommandReply]:
"""
Execute i3/sway commands.
Parameters:
- payload: str, command string to execute
Returns:
List[CommandReply]: results of command execution
"""
def get_version(self) -> VersionReply:
"""
Get i3/sway version information.
Returns:
VersionReply: version details and config file path
"""Container Tree Navigation
Navigate and search the hierarchical window/container tree structure.
class Con:
def find_focused(self) -> Optional[Con]:
"""
Find the currently focused container.
Returns:
Optional[Con]: focused container or None
"""
def find_by_id(self, id: int) -> Optional[Con]:
"""
Find container by unique ID.
Parameters:
- id: int, container ID to search for
Returns:
Optional[Con]: matching container or None
"""
def find_titled(self, pattern: str) -> List[Con]:
"""
Find containers by window title pattern.
Parameters:
- pattern: str, regex pattern to match against titles
Returns:
List[Con]: containers with matching titles
"""Event Handling
Subscribe to window manager events for real-time monitoring and automation.
def on(self, event: Union[Event, str], handler: Callable) -> None:
"""
Subscribe to window manager events.
Parameters:
- event: Union[Event, str], event type to subscribe to
- handler: Callable, function to call when event occurs
"""
def main(self, timeout: float = 0.0) -> None:
"""
Start the event loop to process subscribed events.
Parameters:
- timeout: float, optional timeout in seconds (0 = run forever)
"""
class Event(Enum):
"""Event type enumeration for subscription."""
WORKSPACE = 'workspace'
WINDOW = 'window'
OUTPUT = 'output'
# ... additional event typesWorkspace Operations
Query and manipulate workspace state and configuration.
def get_workspaces(self) -> List[WorkspaceReply]:
"""
Get information about all workspaces.
Returns:
List[WorkspaceReply]: workspace details including visibility and focus state
"""
class WorkspaceReply:
"""Workspace information from GET_WORKSPACES response."""
num: int # Logical workspace number
name: str # Workspace name
visible: bool # Whether workspace is currently visible
focused: bool # Whether workspace has focusOutput Management
Query output (monitor) information and configuration.
def get_outputs(self) -> List[OutputReply]:
"""
Get information about all outputs/monitors.
Returns:
List[OutputReply]: output details including resolution and status
"""
class OutputReply:
"""Output information from GET_OUTPUTS response."""
name: str # Output name
active: bool # Whether output is currently active
primary: bool # Whether output is primary display
rect: Rect # Output dimensions and positionCommand Execution
Execute i3/sway commands and handle responses.
class CommandReply:
"""Response from command execution."""
success: bool # Whether command succeeded
error: str # Error message if command failed
def send_tick(self, payload: str = "") -> TickReply:
"""
Send a tick event with optional payload.
Parameters:
- payload: str, optional data to include with tick
Returns:
TickReply: confirmation of tick processing
"""Async API
Asynchronous versions of all functionality for non-blocking operation.
from i3ipc.aio import Connection
class Connection:
async def connect(self) -> Connection:
"""
Establish async connection to i3/sway.
Returns:
Connection: connected instance ready for use
"""
async def command(self, cmd: str) -> List[CommandReply]:
"""
Execute commands asynchronously.
Parameters:
- cmd: str, command to execute
Returns:
List[CommandReply]: command execution results
"""