Events
======

LXD provides an `/events` endpoint that is upgraded to a streaming websocket
for getting LXD events in real-time. The :class:`~pylxd.Client`'s `events`
method will return a websocket client that can interact with the
web socket messages.

.. code-block:: python

    >>> ws_client = client.events()
    >>> ws_client.connect()
    >>> ws_client.run()

A default client class is provided, which will block indefinitely, and
collect all json messages in a `messages` attribute. An optional 
`websocket_client` parameter can be provided when more functionality is
needed. The `ws4py` library is used to establish the connection; please
see the `ws4py` documentation for more information.

The stream of events can be filtered to include only specific types of
events, as defined in the LXD /endpoint `documentation <https://documentation.ubuntu.com/lxd/en/latest/events/>`_.

To receive all events of type 'operation' or 'logging', generated by the
LXD server:

.. code-block:: python

   >>> types = set([EventType.Operation, EventType.Logging])
   >>> ws_client = client.events(event_types=types)

To receive only events pertaining to the lifecycle of the containers:

.. code-block:: python
		
   >>> types = set([EventType.Lifecycle])
   >>> ws_client = client.events(event_types=types)