0
# i3ipc
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: i3ipc
7
- **Language**: Python  
8
- **Installation**: `pip install i3ipc`
9

10
## Core Imports
11

12
```python
13
import i3ipc
14
```
15

16
For connection-based usage:
17

18
```python
19
from i3ipc import Connection, Event, Con
20
```
21

22
For async usage:
23

24
```python
25
from i3ipc.aio import Connection, Con
26
from i3ipc import Event
27
```
28

29
## Basic Usage
30

31
```python
32
import i3ipc
33

34
# Connect to i3/sway
35
i3 = i3ipc.Connection()
36

37
# Get and display workspace information
38
workspaces = i3.get_workspaces()
39
for ws in workspaces:
40
    print(f"Workspace {ws.name}: {'visible' if ws.visible else 'hidden'}")
41

42
# Navigate the window tree
43
tree = i3.get_tree()
44
focused = tree.find_focused()
45
if focused:
46
    print(f"Focused window: {focused.name}")
47

48
# Execute window manager commands
49
i3.command('workspace 2')
50
i3.command('split horizontal')
51
i3.command('exec firefox')
52

53
# Subscribe to events
54
def on_window_focus(i3, event):
55
    print(f"Window focused: {event.container.name}")
56

57
i3.on(i3ipc.Event.WINDOW_FOCUS, on_window_focus)
58
i3.main()  # Start event loop
59
```
60

61
## Architecture
62

63
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.
64

65
## Capabilities
66

67
### Connection Management
68
Establish and manage connections to i3/sway, handle reconnection, and execute core IPC operations.
69

70
```python { .api }
71
class Connection:
72
    def __init__(self, socket_path=None, auto_reconnect=False):
73
        """
74
        Create a connection to the i3/sway IPC socket.
75
        
76
        Parameters:
77
        - socket_path: Optional[str], path to IPC socket (auto-detected if None)
78
        - auto_reconnect: bool, whether to reconnect automatically on disconnect
79
        """
80

81
    def command(self, payload: str) -> List[CommandReply]:
82
        """
83
        Execute i3/sway commands.
84
        
85
        Parameters:
86
        - payload: str, command string to execute
87
        
88
        Returns:
89
        List[CommandReply]: results of command execution
90
        """
91

92
    def get_version(self) -> VersionReply:
93
        """
94
        Get i3/sway version information.
95
        
96
        Returns:
97
        VersionReply: version details and config file path
98
        """
99
```
100

101
[Connection Management](./connection.md)
102

103
### Container Tree Navigation
104
Navigate and search the hierarchical window/container tree structure.
105

106
```python { .api }
107
class Con:
108
    def find_focused(self) -> Optional[Con]:
109
        """
110
        Find the currently focused container.
111
        
112
        Returns:
113
        Optional[Con]: focused container or None
114
        """
115

116
    def find_by_id(self, id: int) -> Optional[Con]:
117
        """
118
        Find container by unique ID.
119
        
120
        Parameters:
121
        - id: int, container ID to search for
122
        
123
        Returns:
124
        Optional[Con]: matching container or None
125
        """
126

127
    def find_titled(self, pattern: str) -> List[Con]:
128
        """
129
        Find containers by window title pattern.
130
        
131
        Parameters:
132
        - pattern: str, regex pattern to match against titles
133
        
134
        Returns:
135
        List[Con]: containers with matching titles
136
        """
137
```
138

139
[Container Tree Navigation](./containers.md)
140

141
### Event Handling
142
Subscribe to window manager events for real-time monitoring and automation.
143

144
```python { .api }
145
def on(self, event: Union[Event, str], handler: Callable) -> None:
146
    """
147
    Subscribe to window manager events.
148
    
149
    Parameters:
150
    - event: Union[Event, str], event type to subscribe to
151
    - handler: Callable, function to call when event occurs
152
    """
153

154
def main(self, timeout: float = 0.0) -> None:
155
    """
156
    Start the event loop to process subscribed events.
157
    
158
    Parameters:
159
    - timeout: float, optional timeout in seconds (0 = run forever)
160
    """
161

162
class Event(Enum):
163
    """Event type enumeration for subscription."""
164
    WORKSPACE = 'workspace'
165
    WINDOW = 'window'  
166
    OUTPUT = 'output'
167
    # ... additional event types
168
```
169

170
[Event Handling](./events.md)
171

172
### Workspace Operations
173
Query and manipulate workspace state and configuration.
174

175
```python { .api }
176
def get_workspaces(self) -> List[WorkspaceReply]:
177
    """
178
    Get information about all workspaces.
179
    
180
    Returns:
181
    List[WorkspaceReply]: workspace details including visibility and focus state
182
    """
183

184
class WorkspaceReply:
185
    """Workspace information from GET_WORKSPACES response."""
186
    num: int  # Logical workspace number
187
    name: str  # Workspace name
188
    visible: bool  # Whether workspace is currently visible
189
    focused: bool  # Whether workspace has focus
190
```
191

192
[Workspace Operations](./workspaces.md)
193

194
### Output Management
195
Query output (monitor) information and configuration.
196

197
```python { .api }
198
def get_outputs(self) -> List[OutputReply]:
199
    """
200
    Get information about all outputs/monitors.
201
    
202
    Returns:
203
    List[OutputReply]: output details including resolution and status
204
    """
205

206
class OutputReply:
207
    """Output information from GET_OUTPUTS response."""
208
    name: str  # Output name
209
    active: bool  # Whether output is currently active
210
    primary: bool  # Whether output is primary display
211
    rect: Rect  # Output dimensions and position
212
```
213

214
[Output Management](./outputs.md)
215

216
### Command Execution
217
Execute i3/sway commands and handle responses.
218

219
```python { .api }
220
class CommandReply:
221
    """Response from command execution."""
222
    success: bool  # Whether command succeeded
223
    error: str  # Error message if command failed
224

225
def send_tick(self, payload: str = "") -> TickReply:
226
    """
227
    Send a tick event with optional payload.
228
    
229
    Parameters:
230
    - payload: str, optional data to include with tick
231
    
232
    Returns:
233
    TickReply: confirmation of tick processing
234
    """
235
```
236

237
[Command Execution](./commands.md)
238

239
### Async API
240
Asynchronous versions of all functionality for non-blocking operation.
241

242
```python { .api }
243
from i3ipc.aio import Connection
244

245
class Connection:
246
    async def connect(self) -> Connection:
247
        """
248
        Establish async connection to i3/sway.
249
        
250
        Returns:
251
        Connection: connected instance ready for use
252
        """
253

254
    async def command(self, cmd: str) -> List[CommandReply]:
255
        """
256
        Execute commands asynchronously.
257
        
258
        Parameters:
259
        - cmd: str, command to execute
260
        
261
        Returns:
262
        List[CommandReply]: command execution results
263
        """
264
```
265

266
[Async API](./async.md)