0
# Connection Management
1
2
Core connection functionality for establishing and managing IPC communication with i3/sway window managers. Handles socket path discovery, connection establishment, message sending/receiving, and automatic reconnection.
3
4
## Capabilities
5
6
### Connection Initialization
7
8
```python { .api }
9
class Connection:
10
def __init__(self, socket_path=None, auto_reconnect=False):
11
"""
12
Create a connection to the i3/sway IPC socket.
13
14
Parameters:
15
- socket_path: Optional[str], path to IPC socket (auto-detected if None)
16
- auto_reconnect: bool, whether to reconnect automatically on disconnect
17
18
Raises:
19
Exception: if connection to i3/sway cannot be established
20
"""
21
```
22
23
### Connection Properties
24
25
```python { .api }
26
@property
27
def socket_path(self) -> str:
28
"""
29
Get the path to the IPC socket.
30
31
Returns:
32
str: absolute path to the IPC socket file
33
"""
34
35
@property
36
def auto_reconnect(self) -> bool:
37
"""
38
Get the auto-reconnect setting.
39
40
Returns:
41
bool: whether automatic reconnection is enabled
42
"""
43
```
44
45
### Command Execution
46
47
```python { .api }
48
def command(self, payload: str) -> List[CommandReply]:
49
"""
50
Execute i3/sway commands.
51
52
Parameters:
53
- payload: str, command string to execute (can contain multiple semicolon-separated commands)
54
55
Returns:
56
List[CommandReply]: results of command execution, one per command
57
"""
58
59
def send_tick(self, payload: str = "") -> TickReply:
60
"""
61
Send a tick event with optional payload.
62
63
Parameters:
64
- payload: str, optional data to include with tick event
65
66
Returns:
67
TickReply: confirmation of tick processing
68
"""
69
```
70
71
### Event Handling
72
73
```python { .api }
74
def on(self, event: Union[Event, str], handler: Callable[[Connection, IpcBaseEvent], None]) -> None:
75
"""
76
Subscribe to window manager events.
77
78
Parameters:
79
- event: Union[Event, str], event type to subscribe to
80
- handler: Callable, function called when event occurs (receives connection and event data)
81
"""
82
83
def off(self, handler: Callable[[Connection, IpcBaseEvent], None]) -> None:
84
"""
85
Remove event handler from all subscriptions.
86
87
Parameters:
88
- handler: Callable, handler function to remove
89
"""
90
91
def main(self, timeout: float = 0.0) -> None:
92
"""
93
Start the main event loop to process subscribed events.
94
95
Parameters:
96
- timeout: float, timeout in seconds (0 = run forever until main_quit called)
97
"""
98
99
def main_quit(self) -> None:
100
"""
101
Stop the main event loop and exit event processing.
102
"""
103
```
104
105
### Core Query Methods
106
107
```python { .api }
108
def get_version(self) -> VersionReply:
109
"""
110
Get i3/sway version information and configuration details.
111
112
Returns:
113
VersionReply: version numbers, human-readable string, and config file path
114
"""
115
116
def get_tree(self) -> Con:
117
"""
118
Get the complete window/container tree structure.
119
120
Returns:
121
Con: root container with full tree hierarchy
122
"""
123
124
def get_workspaces(self) -> List[WorkspaceReply]:
125
"""
126
Get information about all workspaces.
127
128
Returns:
129
List[WorkspaceReply]: workspace details including visibility and focus state
130
"""
131
132
def get_outputs(self) -> List[OutputReply]:
133
"""
134
Get information about all outputs/monitors.
135
136
Returns:
137
List[OutputReply]: output details including resolution and active status
138
"""
139
140
def get_marks(self) -> List[str]:
141
"""
142
Get all container marks currently set.
143
144
Returns:
145
List[str]: list of mark names
146
"""
147
148
def get_binding_modes(self) -> List[str]:
149
"""
150
Get all available binding modes.
151
152
Returns:
153
List[str]: list of binding mode names
154
"""
155
156
def get_config(self) -> ConfigReply:
157
"""
158
Get the current configuration file contents.
159
160
Returns:
161
ConfigReply: raw configuration file text
162
"""
163
```
164
165
### Sway-Specific Methods
166
167
```python { .api }
168
def get_inputs(self) -> List[InputReply]:
169
"""
170
Get information about input devices (sway only).
171
172
Returns:
173
List[InputReply]: input device details including type and capabilities
174
"""
175
176
def get_seats(self) -> List[SeatReply]:
177
"""
178
Get information about seats (sway only).
179
180
Returns:
181
List[SeatReply]: seat details including focus and attached devices
182
"""
183
```
184
185
### Bar Configuration
186
187
```python { .api }
188
def get_bar_config_list(self) -> List[str]:
189
"""
190
Get list of all bar configuration IDs.
191
192
Returns:
193
List[str]: bar ID strings
194
"""
195
196
def get_bar_config(self, bar_id: str = None) -> Optional[BarConfigReply]:
197
"""
198
Get bar configuration details.
199
200
Parameters:
201
- bar_id: Optional[str], specific bar ID (uses first bar if None)
202
203
Returns:
204
Optional[BarConfigReply]: bar configuration or None if not found
205
"""
206
```
207
208
### Version Reply Structure
209
210
```python { .api }
211
class VersionReply:
212
"""Response from GET_VERSION request."""
213
major: int # Major version number
214
minor: int # Minor version number
215
patch: int # Patch version number
216
human_readable: str # Human-readable version string
217
loaded_config_file_name: str # Path to loaded config file
218
ipc_data: dict # Raw IPC response data
219
```
220
221
### Config Reply Structure
222
223
```python { .api }
224
class ConfigReply:
225
"""Response from GET_CONFIG request."""
226
config: str # Complete configuration file contents
227
ipc_data: dict # Raw IPC response data
228
```
229
230
### Command Reply Structure
231
232
```python { .api }
233
class CommandReply:
234
"""Response from command execution."""
235
success: bool # Whether command executed successfully
236
error: str # Error message if command failed (None if successful)
237
ipc_data: dict # Raw IPC response data
238
```
239
240
### Tick Reply Structure
241
242
```python { .api }
243
class TickReply:
244
"""Response from tick event transmission."""
245
success: bool # Whether tick was processed successfully
246
ipc_data: dict # Raw IPC response data
247
```
248
249
### Bar Configuration Reply Structure
250
251
```python { .api }
252
class BarConfigReply:
253
"""Response from GET_BAR_CONFIG request."""
254
id: str # Bar configuration ID
255
mode: str # Bar mode (dock, hide, invisible)
256
position: str # Bar position (top, bottom)
257
status_command: str # Command for status line
258
font: str # Font specification
259
workspace_buttons: bool # Whether to show workspace buttons
260
binding_mode_indicator: bool # Whether to show binding mode indicator
261
verbose: bool # Verbose output setting
262
colors: dict # Color configuration mapping
263
separator_symbol: str # Workspace button separator
264
strip_workspace_numbers: bool # Whether to strip workspace numbers
265
ipc_data: dict # Raw IPC response data
266
```
267
268
### Input Reply Structure (Sway Only)
269
270
```python { .api }
271
class InputReply:
272
"""Response from GET_INPUTS request (sway only)."""
273
identifier: str # Unique device identifier
274
name: str # Human-readable device name
275
vendor: int # Vendor ID code
276
product: int # Product ID code
277
type: str # Device type (keyboard, pointer, touch, etc.)
278
xkb_active_layout_name: str # Active keyboard layout name
279
xkb_layout_names: List[str] # Available keyboard layout names
280
xkb_active_layout_index: int # Index of active layout
281
libinput: dict # Libinput configuration settings
282
ipc_data: dict # Raw IPC response data
283
```
284
285
### Seat Reply Structure (Sway Only)
286
287
```python { .api }
288
class SeatReply:
289
"""Response from GET_SEATS request (sway only)."""
290
name: str # Seat name
291
capabilities: int # Seat capabilities bitmask
292
focus: int # ID of focused container
293
devices: List[InputReply] # Input devices attached to this seat
294
ipc_data: dict # Raw IPC response data
295
```