Server Modules

The base set of objects used by Wayland servers.


class pywayland.server.Client(display: Display | None = None, fd: int | None = None, ptr: ffi.ClientCData | None = None)

Create a client for the given file descriptor

Given a file descriptor corresponding to one end of a socket, create a client struct and add the new client to the compositors client list. At that point, the client is initialized and ready to run, as if the client had connected to the servers listening socket. Alternatively, pass a pointer to an existing client and use that instead of creating a new one.

The other end of the socket can be passed to connect() on the client side or used with the WAYLAND_SOCKET environment variable on the client side.

  • display (Display) – The display object
  • fd (int) – The file descriptor for the socket to the client
  • ptr (ffi.ClientCData) – A pointer to an existing wl_client
add_destroy_listener(listener: pywayland.server.listener.Listener) → None

Add a listener for the destroy signal

Parameters:listener (Listener) – The listener object
destroy() → None

Destroy the client

flush() → None

Flush pending events to the client

Events sent to clients are queued in a buffer and written to the socket later - typically when the compositor has handled all requests and goes back to block in the event loop. This function flushes all queued up events for a client immediately.

classmethod from_resource(resource: <MagicMock name='mock.ffi.ResourceCData' id='140556454394384'>) → pywayland.server.client.Client

Look up the corresponding wl_client for a wl_resource

Parameters:resource (pywayland.protocol_core.Resource) – The wl_resource
Returns:A Client instance.
get_credentials() → tuple[int, int, int]

Return Unix credentials for the client.

This function returns the process ID, the user ID and the group ID for the given client. The credentials come from getsockopt() with SO_PEERCRED, on the client socket fd.

get_object(object_id: int) → Any

Look up an object in the client name space

This looks up an object in the client object name space by its object ID.

Parameters:object_id (int) – The object id
Returns:The object, or None if there is not object for the given ID


class pywayland.server.Display(ptr=None)

Create a Wayland Display object

add_shm_format(shm_format) → None

Add support for a Shm pixel format

Add the specified format format to the list of formats the WlShm object advertises when a client binds to it. Adding a format to the list means that clients will know that the compositor supports this format and may use it for creating WlShm buffers. The compositor must be able to handle the pixel format when a client requests it.

The compositor by default supports WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888.

Parameters:shm_format (format) – The shm pixel format to advertise
add_socket(name: str | None = None) → str

Add a socket to Wayland display for the clients to connect.

This adds a Unix socket to Wayland display which can be used by clients to connect to Wayland display.

If None is passed as name, then it would look for WAYLAND_DISPLAY environment variable for the socket name. If WAYLAND_DISPLAY is not set, then default wayland-0 is used.

The Unix socket will be created in the directory pointed to by environment variable XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not set, then this function throws an exception.

The length of socket path, i.e., the path set in XDG_RUNTIME_DIR and the socket name, must not exceed the maxium length of a Unix socket path. The function also fails if the user do not have write permission in the XDG_RUNTIME_DIR path or if the socket name is already in use.

Parameters:name (string or None) – Name of the Unix socket.
destroy() → None

Destroy Wayland display object.

This function emits the Display destroy signal, releases all the sockets added to this display, free’s all the globals associated with this display, free’s memory of additional shared memory formats and destroy the display object.

See also



Returns if the display has been destroyed

flush_clients() → None

Flush client connections

get_event_loop() → pywayland.server.eventloop.EventLoop

Get the event loop for the display

Returns:The EventLoop for the Display
get_serial() → int

Get the current serial number

This function returns the most recent serial number, but does not increment it.

init_shm() → None

Initialize shm for this display

next_serial() → int

Get the next serial

This function increments the display serial number and returns the new value.

run() → None

Run the display

terminate() → None

Stop the display from running


class pywayland.server.EventLoop(display: Display | None = None)

An event loop to add events to

Returns an event loop. Either returns the event loop of a given display (which will trigger when the Display is run), or creates a new event loop (which can be triggered by using EventLoop.dispatch()).

Parameters:display (Display) – The display to create the EventLoop on (default to None)
class FdMask

An enumeration.


Add a listener for the destroy signal

Parameters:listener (Listener) – The listener object
add_fd(fd, callback, mask=<FdMask.WL_EVENT_READABLE: 1>, data=None)

Add file descriptor callback

Triggers function call when file descriptor state matches the mask.

The callback should take three arguments:

  • fd - file descriptor (int)
  • mask - file descriptor mask (uint)
  • data - any object
  • fd (int) – File descriptor
  • callback – Callback function
  • mask – File descriptor mask
  • data (object) – User data to send to callback

EventSource for specified callback

See also


add_idle(callback, data=None)

Add idle callback

  • callback (function with callback void(void *data)) – Callback function
  • data – User data to send to callback

EventSource for specified callback

add_signal(signal_number, callback, data=None)

Add signal callback

Triggers function call signal is received.

The callback should take three arguments:

  • signal_number - signal (int)
  • data - any object
  • signal_number (int) – Signal number to trigger on
  • callback – Callback function
  • data (object) – User data to send to callback

EventSource for specified callback

add_timer(callback, data=None)

Add timer callback

Triggers function call after a specified time.

The callback should take one argument:

  • data - any object
  • callback (function with callback int(void *data)) – Callback function
  • data (object) – User data to send to callback

EventSource for specified callback

See also



Destroy the event loop


Dispatch callbacks on the event loop


Dispatch idle callback on the event loop


class pywayland.server.Listener(function: Callable)

A single listener for Wayland signals

Provides the means to listen for wl_listener signal notifications. Many Wayland objects use wl_listener for notification of significant events like object destruction.

Clients should create Listener objects manually and can register them as listeners to objects destroy events using the object’s .add_destroy_listener() method. A listener can only listen to one signal at a time.

Parameters:function (callable) – callback function for the Listener
remove() → None

Remove the listener