Server Modules
**************

The base set of objects used by Wayland servers.


Client
======

class pywayland.server.Client(display: Display | None = None, fd: int | None = None, ptr: <MagicMock name = 'mock.ffi.ClientCData.__or__()' id='140737181137280'> = 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.

   Parameters:
      * **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: 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='140737181137280'>) -> 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


Display
=======

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: "Display.add_destroy_listener()"

   property destroyed: bool

      Returns if the display has been destroyed

   flush_clients() -> None

      Flush client connections

   get_event_loop() -> 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


EventLoop
=========

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(*values)

   add_destroy_listener(listener)

      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

      Parameters:
         * **fd** (*int*) -- File descriptor

         * **callback** -- Callback function

         * **mask** -- File descriptor mask

         * **data** (*object*) -- User data to send to callback

      Returns:
         "EventSource" for specified callback

      See also: "pywayland.server.eventloop.EventSource.check()"

   add_idle(callback, data=None)

      Add idle callback

      Parameters:
         * **callback** (function with callback *void(void *data)*) --
           Callback function

         * **data** -- User data to send to callback

      Returns:
         "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

      Parameters:
         * **signal_number** (*int*) -- Signal number to trigger on

         * **callback** -- Callback function

         * **data** (*object*) -- User data to send to callback

      Returns:
         "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

      Parameters:
         * **callback** (function with callback *int(void *data)*) --
           Callback function

         * **data** (*object*) -- User data to send to callback

      Returns:
         "EventSource" for specified callback

      See also:

        "pywayland.server.eventloop.EventSource.timer_update()"

   destroy()

      Destroy the event loop

   dispatch(timeout)

      Dispatch callbacks on the event loop

   dispatch_idle()

      Dispatch idle callback on the event loop


Listener
========

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
