Client Modules

The base set of objects used by Wayland clients. Users should only be directly creating Display and EventQueue objects. The Proxy objects to interfaces should be returned by making request calls.


class pywayland.client.Display(name_or_fd: int | str | None = None)

Represents a connection to the compositor

A Display object represents a client connection to a Wayland compositor. The connection and the corresponding Wayland object are created with Display.connect(). The display must be connected before it can be used. A connection is terminated using Display.disconnect().

A Display is also used as the Proxy for the pywayland.protocol.wayland.WlDisplay protocol object on the compositor side.

A Display object handles all the data sent from and to the compositor. When a Proxy marshals a request, it will write its wire representation to the display’s write buffer. The data is sent to the compositor when the client calls flush().

Incoming data is handled in two steps: queueing and dispatching. In the queue step, the data coming from the display fd is interpreted and added to a queue. On the dispatch step, the handler for the incoming event set by the client on the corresponding Proxy is called.

A Display has at least one event queue, called the default queue. Clients can create additional event queues with Display.create_queue() and assign Proxy’s to it. Events occurring in a particular proxy are always queued in its assigned queue. A client can ensure that a certain assumption, such as holding a lock or running from a given thread, is true when a proxy event handler is called by assigning that proxy to an event queue and making sure that this queue is only dispatched when the assumption holds.

The default queue is dispatched by calling Display.dispatch(). This will dispatch any events queued on the default queue and attempt to read from the display fd if it’s empty. Events read are then queued on the appropriate queues according to the proxy assignment.

A user created queue is dispatched with Display.dispatch_queue(). This function behaves exactly the same as Display.dispatch() but it dispatches given queue instead of the default queue.

A real world example of event queue usage is Mesa’s implementation of glSwapBuffers() for the Wayland platform. This function might need to block until a frame callback is received, but dispatching the default queue could cause an event handler on the client to start drawing gain. This problem is solved using another event queue, so that only the events handled by the EGL code are dispatched during the block.

Parameters:name_or_fd (int or str) – Either the name of the display to create or the file descriptor to connect the display to. If not specified, then use the default name, generally wayland-0
connect() → None

Connect to a Wayland display

Connect to the Wayland display by name of fd. An int parameter opens the connection using the file descriptor. The Display takes ownership of the fd and will close it when the display is destroyed. The fd will also be closed in case of failure. A string will open the display of the given name. If name is None, its value will be replaced with the WAYLAND_DISPLAY environment variable if it is set, otherwise display "wayland-0" will be used.

disconnect() → None

Close a connection to a Wayland display

Close the connection to display and free all resources associated with it.

dispatch(*, block: bool = False, queue: EventQueue | None = None) → int

Process incoming events

If block is False, it does not attempt to read the display fd or event queue and simply returns zero if the queue is empty.

If the given queue is empty and block is True, this function blocks until there are events to be read from the display fd. Events are read and queued on the appropriate event queues. Finally, events on the default event queue are dispatched.


It is not possible to check if there are events on the queue or not.

flush() → int

Send all buffered requests on the display to the server

Send all buffered data on the client side to the server. Clients should call this function before blocking. On success, the number of bytes sent to the server is returned. On failure, this function returns -1 and errno is set appropriately.

Display.flush() never blocks. It will write as much data as possible, but if all data could not be written, errno will be set to EAGAIN and -1 returned. In that case, use poll on the display file descriptor to wait for it to become writable again.

get_fd() → int

Get a display context’s file descriptor

Return the file descriptor associated with a display so it can be integrated into the client’s main loop.

read(*, queue: EventQueue | None = None) → None

Read events from display file descriptor

Calling this function will result in data available on the display file descriptor being read and read events will be queued on their corresponding event queues.

Parameters:queue – If specified, queue the events onto the given event queue, otherwise the default display queue will be used.
roundtrip(*, queue: EventQueue | None = None) → int

Block until all pending request are processed by the server

This function blocks until the server has processed all currently issued requests by sending a request to the display server and waiting for a reply before returning.

This function uses wl_display_dispatch_queue() internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock.


This function may dispatch other events being received on the default queue.

Parameters:queue (EventQueue) – The queue on which to run the roundtrip, if not given, uses the default queue.
Returns:The number of dispatched events on success or -1 on failure


class pywayland.client.EventQueue(display: Display)

A queue for wl_proxy object events.

Event queues allows the events on a display to be handled in a thread-safe manner. See Display for details.

Parameters:display (Display) – The display object that the event queue is connected to.
destroy() → None

Destroy an event queue

Destroy the given event queue. Any pending event on that queue is discarded.

The wl_display object used to create the queue should not be destroyed until all event queues created with it are destroyed with this function.


Determine the state of the event queue