154 lines
5.2 KiB
ReStructuredText
154 lines
5.2 KiB
ReStructuredText
:py:mod:`qubes.events` -- Qubes events
|
|
======================================
|
|
|
|
Some objects in qubes (most notably domains) emit events. You may hook them and
|
|
execute your code when particular event is fired. Events in qubes are added
|
|
class-wide -- it is not possible to add event handler to one instance only, you
|
|
have to add handler for whole class.
|
|
|
|
|
|
Firing events
|
|
-------------
|
|
|
|
Events are fired by calling :py:meth:`qubes.events.Emitter.fire_event`. The
|
|
first argument is event name (a string). You can fire any event you wish, the
|
|
names are not checked in any way, however each class' documentation tells what
|
|
standard events will be fired on it. When firing an event, caller may specify
|
|
some optional keyword arguments. Those are dependent on the particular event in
|
|
question -- they are passed as-is to handlers.
|
|
|
|
Event handlers are fired in reverse method resolution order, that is, first for
|
|
parent class and then for it's child. For each class, first are called handlers
|
|
defined in it's source, then handlers from extensions and last the callers added
|
|
manually.
|
|
|
|
There is second method, :py:meth:`qubes.events.Emitter.fire_event_pre`, which
|
|
fires events in reverse order. It is suitable for events fired before some
|
|
action is performed. You may at your own responsibility raise exceptions from
|
|
such events to try to prevent such action.
|
|
|
|
Events handlers may yield values. Those values are aggregated and returned
|
|
to the caller as a list of those values. See below for details.
|
|
|
|
Handling events
|
|
---------------
|
|
|
|
There are several ways to handle events. In all cases you supply a callable
|
|
(most likely function or method) that will be called when someone fires the
|
|
event. The first argument passed to the callable will be the object instance on
|
|
which the event was fired and the second one is the event name. The rest are
|
|
passed from :py:meth:`qubes.events.Emitter.fire_event` as described previously.
|
|
One callable can handle more than one event.
|
|
|
|
The easiest way to hook an event is to use
|
|
:py:func:`qubes.events.handler` decorator.
|
|
|
|
.. code-block:: python
|
|
|
|
import qubes.events
|
|
|
|
class MyClass(qubes.events.Emitter):
|
|
@qubes.events.handler('event1', 'event2')
|
|
def event_handler(self, event):
|
|
if event == 'event1':
|
|
print('Got event 1')
|
|
elif event == 'event2':
|
|
print('Got event 2')
|
|
|
|
o = MyClass()
|
|
o.fire_event('event1')
|
|
|
|
Note that your handler will be called for all instances of this class.
|
|
|
|
.. TODO: extensions
|
|
.. TODO: add/remove_handler
|
|
|
|
|
|
Handling events with variable signature
|
|
---------------------------------------
|
|
|
|
Some events are specified with variable signature (i.e. they may have different
|
|
number of arguments on each call to handlers). You can write handlers just like
|
|
every other python function with variable signature.
|
|
|
|
.. code-block:: python
|
|
|
|
import qubes
|
|
|
|
def on_property_change(subject, event, name, newvalue, oldvalue=None):
|
|
if oldvalue is None:
|
|
print('Property {} initialised to {!r}'.format(name, newvalue))
|
|
else:
|
|
print('Property {} changed {!r} -> {!r}'.format(name, oldvalue, newvalue))
|
|
|
|
app = qubes.Qubes()
|
|
app.add_handler('property-set:default_netvm')
|
|
|
|
If you expect :py:obj:`None` to be a reasonable value of the property, you have
|
|
a problem. One way to solve it is to invent your very own, magic
|
|
:py:class:`object` instance.
|
|
|
|
.. code-block:: python
|
|
|
|
import qubes
|
|
|
|
MAGIC_NO_VALUE = object()
|
|
def on_property_change(subject, event, name, newvalue, oldvalue=MAGIC_NO_VALUE):
|
|
if oldvalue is MAGIC_NO_VALUE:
|
|
print('Property {} initialised to {!r}'.format(name, newvalue))
|
|
else:
|
|
print('Property {} changed {!r} -> {!r}'.format(name, oldvalue, newvalue))
|
|
|
|
app = qubes.Qubes()
|
|
app.add_handler('property-set:default_netvm')
|
|
|
|
There is no possible way of collision other than intentionally passing this very
|
|
object (not even passing similar featureless ``object()``), because ``is``
|
|
python syntax checks object's :py:meth:`id`\ entity, which will be different for
|
|
each :py:class:`object` instance.
|
|
|
|
|
|
Returning values from events
|
|
----------------------------
|
|
|
|
Some events may be called to collect values from the handlers. For example the
|
|
event ``is-fully-usable`` allows plugins to report a domain as not fully usable.
|
|
Such handlers, instead of returning :py:obj:`None` (which is the default when
|
|
the function does not include ``return`` statement), should return an iterable
|
|
or itself be a generator. Those values are aggregated from all handlers and
|
|
returned to the caller as list. The order of this list is undefined.
|
|
|
|
.. code-block:: python
|
|
|
|
import qubes.events
|
|
|
|
class MyClass(qubes.events.Emitter):
|
|
@qubes.events.handler('event1')
|
|
def event1_handler1(self, event):
|
|
# do not return anything, equivalent to "return" and "return None"
|
|
pass
|
|
|
|
@qubes.events.handler('event1')
|
|
def event1_handler2(self, event):
|
|
yield 'aqq'
|
|
yield 'zxc'
|
|
|
|
@qubes.events.handler('event1')
|
|
def event1_handler3(self, event):
|
|
return ('123', '456')
|
|
|
|
o = MyClass()
|
|
|
|
# returns ['aqq', 'zxc', '123', '456'], possibly not in order
|
|
effect = o.fire_event('event1')
|
|
|
|
|
|
Module contents
|
|
---------------
|
|
|
|
.. automodule:: qubes.events
|
|
:members:
|
|
:show-inheritance:
|
|
|
|
.. vim: ts=3 sw=3 et
|