i3ipc-python

The window manager's layout is represented by a tree of Con (container) objects. You can retrieve the root container using get_tree(), find specific windows by class or focus status, and issue commands directly to specific containers.

# get_tree() returns the root container
tree = await i3.get_tree()

# get some information about the focused window
focused = tree.find_focused()
print(f'Focused window: {focused.name}')
workspace = focused.workspace()
print(f'Focused workspace: {workspace.name}')

# focus firefox and set it to fullscreen mode
ff = tree.find_classed('Firefox')[0]
await ff.command('focus')
await ff.command('fullscreen')

# iterate through all the container windows (or use tree.leaves() for just
# application windows)
for container in workspace:
    print(f'On the focused workspace: {container.name}')

The Connection class is the main entry point for the library. It manages a Unix socket connection to the IPC interface of i3 or sway. By default, it attempts to connect using environment information or the running X11 display. For asynchronous usage, use i3ipc.aio.Connection.

from i3ipc.aio import Connection

i3 = await Connection().connect()

The i3ipc-python library uses a class hierarchy to represent different types of IPC events. All events inherit from the base i3ipc.Event class. When subscribing to events, you will receive specific subclasses depending on the event type triggered by i3 or Sway.

Key event subclasses include:

• i3ipc.WorkspaceEvent: Triggered when workspaces change.
• i3ipc.WindowEvent: Triggered when windows are created, moved, or changed.
• i3ipc.BindingEvent: Triggered when a key binding is executed.
• i3ipc.ModeEvent: Triggered when the i3 mode changes.
• i3ipc.OutputEvent: Triggered when monitor/output configurations change.
• i3ipc.ShutdownEvent: Triggered when the window manager is shutting down.
• i3ipc.TickEvent: Triggered on periodic timer ticks.
• i3ipc.InputEvent: Triggered by input device changes.
• i3ipc.BarconfigUpdateEvent: Triggered when bar configuration updates.

You can install the i3ipc library using pip3. This library allows you to control i3wm and sway via their interprocess communication (IPC) interface.

pip3 install i3ipc

Install the library using PyPi with the following command:

pip3 install i3ipc

The standard i3ipc.Connection object is used to send commands to the window manager and subscribe to events. It provides a blocking interface for interacting with the IPC socket.

Common tasks include:

• Querying the window tree (get_tree()).
• Finding the focused window (find_focused()).
• Sending commands (command()).
• Subscribing to events (on()).
• Running the event loop (main()).

from i3ipc import Connection, Event

# Create the Connection object
i3 = Connection()

# Send a command synchronously
i3.command('focus left')

# Subscribe to an event with a callback
def on_workspace_focus(i3, e):
    print('Workspace changed')

i3.on(Event.WORKSPACE_FOCUS, on_workspace_focus)

# Start the main loop to wait for events
i3.main()

For asynchronous applications, use the i3ipc.aio package. The interface is similar to the blocking version, but methods that interact with the socket are coroutines and must be awaited.

from i3ipc.aio import Connection
from i3ipc import Event
import asyncio

async def main():
    # Connect to the IPC
    c = await Connection(auto_reconnect=True).connect()

    # Await coroutines for IPC interaction
    workspaces = await c.get_workspaces()

    # Register event handlers
    c.on(Event.WINDOW, lambda i3, e: print(e))

    # Run the async main loop
    await c.main()

asyncio.run(main())

The library uses the standard Python logging module under the i3ipc namespace. You can enable debug logging by configuring the root logger.

import logging
logging.basicConfig(level=logging.DEBUG)

Use the Connection object to retrieve information about the current state of the window manager, such as workspaces and outputs.

workspaces = await i3.get_workspaces()
outputs = await i3.get_outputs()

for workspace in workspaces:
    print(f'workspace: {workspace.name}')

for output in outputs:
    print(f'output: {output.name}')

The i3ipc.Connection class is the primary entry point for interacting with the i3 or Sway IPC (Inter-Process Communication). It allows you to send commands to the window manager and subscribe to various events. You must create a Connection instance to perform any IPC operations.

import i3ipc

# Create a connection to the i3/Sway IPC
connection = i3ipc.Connection()

The i3ipc.aio.Connection class is the primary interface for interacting with the i3 (or Sway) IPC via Python's asyncio framework. It allows you to send commands to the window manager and subscribe to events asynchronously. Use this class when building non-blocking applications that need to react to window manager changes or execute commands without stalling the event loop.

import i3ipc.aio

async def main():
    # Create an asynchronous connection
    async with i3ipc.aio.Connection() as conn:
        # Use the connection to interact with i3/Sway
        pass

import asyncio
asyncio.run(main())