Connection

class i3ipc.Connection(socket_path=None, auto_reconnect=False)

A connection to the i3 ipc used for querying window manager state and listening to events.

The Connection class is the entry point into all features of the library.

Example

i3 = Connection()
workspaces = i3.get_workspaces()
i3.command('focus left')
Parameters

  • socket_path (str) – A path to the i3 ipc socket path to connect to. If not given, find the socket path through the default search path.

  • auto_reconnect (bool) – Whether to attempt to reconnect if the connection to the socket is broken when i3 restarts.

Raises

Exception – If the connection to i3 cannot be established.

property auto_reconnect

Whether this Connection will attempt to reconnect when the connection to the socket is broken.

Return type

bool

command(payload: str) → List[i3ipc.replies.CommandReply]

Sends a command to i3.

See also

https://i3wm.org/docs/userguide.html#list_of_commands

Parameters

cmd (str) – The command to send to i3.

Returns

A list of replies that contain info for the result of each command given.

Return type

list(CommandReply)

get_bar_config(bar_id: str = None) → Optional[i3ipc.replies.BarConfigReply]

Gets the bar configuration specified by the id.

Parameters

bar_id (str) – The bar id to get the configuration for. If not given, get the configuration for the first bar id.

Returns

The bar configuration for the bar id.

Return type

BarConfigReply or None if no bar configuration is found.

get_bar_config_list() → List[str]

Gets the names of all bar configurations.

Returns

A list of all bar configurations.

Return type

list(str)

get_binding_modes() → List[str]

Gets the names of all currently configured binding modes

Returns

A list of binding modes

Return type

list(str)

get_config() → i3ipc.replies.ConfigReply

Returns the last loaded i3 config.

Returns

A class containing the config.

Return type

i3ipc.ConfigReply

get_inputs() → List[i3ipc.replies.InputReply]

(sway only) Gets the inputs connected to the compositor.

Returns

The reply to the inputs command

Return type

list(i3ipc.InputReply)

get_marks() → List[str]

Gets the names of all currently set marks.

Returns

A list of currently set marks.

Return type

list(str)

get_outputs() → List[i3ipc.replies.OutputReply]

Gets the list of current outputs.

Returns

A list of current outputs.

Return type

list(i3ipc.OutputReply)

get_seats() → List[i3ipc.replies.SeatReply]

(sway only) Gets the seats configured on the compositor

Returns

The reply to the seats command

Return type

list(i3ipc.SeatReply)

get_tree() → i3ipc.con.Con

Gets the root container of the i3 layout tree.

Returns

The root container of the i3 layout tree.

Return type

i3ipc.Con

get_version() → i3ipc.replies.VersionReply

Gets the i3 version.

Returns

The i3 version.

Return type

i3ipc.VersionReply

get_workspaces() → List[i3ipc.replies.WorkspaceReply]

Gets the list of current workspaces.

Returns

A list of current workspaces

Return type

list(i3ipc.WorkspaceReply)

main(timeout: float = 0.0)

Starts the main loop for this connection to start handling events.

Parameters

timeout (float) – If given, quit the main loop after timeout seconds.

main_quit()

Quits the running main loop for this connection.

off(handler: Callable[[Connection, i3ipc.events.IpcBaseEvent], None])

Unsubscribe the handler from being called on ipc events.

Parameters

handler (Callable) – The handler that was previously attached with on().

on(event: Union[i3ipc.events.Event, str], handler: Callable[[Connection, i3ipc.events.IpcBaseEvent], None])

Subscribe to the event and call the handler when it is emitted by the i3 ipc.

Parameters

  • event (Event or str) – The event to subscribe to.

  • handler (Callable) – The event handler to call.

send_tick(payload: str = '') → i3ipc.replies.TickReply

Sends a tick with the specified payload.

Returns

The reply to the tick command

Return type

i3ipc.TickReply

property socket_path

The path of the socket this Connection is connected to.

Return type

str