qubes-events.rst 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170
  1. :py:mod:`qubes.events` -- Qubes events
  2. ======================================
  3. Some objects in qubes (most notably domains) emit events. You may hook them and
  4. execute your code when particular event is fired. Events in qubes are added
  5. class-wide -- it is not possible to add event handler to one instance only, you
  6. have to add handler for whole class.
  7. Firing events
  8. -------------
  9. Events are fired by calling :py:meth:`qubes.events.Emitter.fire_event`. The
  10. first argument is event name (a string). You can fire any event you wish, the
  11. names are not checked in any way, however each class' documentation tells what
  12. standard events will be fired on it. When firing an event, caller may specify
  13. some optional keyword arguments. Those are dependent on the particular event in
  14. question -- they are passed as-is to handlers.
  15. Event handlers are fired in reverse method resolution order, that is, first for
  16. parent class and then for it's child. For each class, first are called handlers
  17. defined in it's source, then handlers from extensions and last the callers added
  18. manually.
  19. There is second method, :py:meth:`qubes.events.Emitter.fire_event_pre`, which
  20. fires events in reverse order. It is suitable for events fired before some
  21. action is performed. You may at your own responsibility raise exceptions from
  22. such events to try to prevent such action.
  23. Events handlers may yield values. Those values are aggregated and returned
  24. to the caller as a list of those values. See below for details.
  25. Handling events
  26. ---------------
  27. There are several ways to handle events. In all cases you supply a callable
  28. (most likely function or method) that will be called when someone fires the
  29. event. The first argument passed to the callable will be the object instance on
  30. which the event was fired and the second one is the event name. The rest are
  31. passed from :py:meth:`qubes.events.Emitter.fire_event` as described previously.
  32. One callable can handle more than one event.
  33. The easiest way to hook an event is to invoke
  34. :py:meth:`qubes.events.Emitter.add_handler` classmethod.
  35. .. code-block:: python
  36. import qubes.events
  37. class MyClass(qubes.events.Emitter):
  38. pass
  39. def event_handler(subject, event):
  40. if event == 'event1':
  41. print('Got event 1')
  42. elif event == 'event2':
  43. print('Got event 2')
  44. MyClass.add_handler('event1', event_handler)
  45. MyClass.add_handler('event2', event_handler)
  46. o = MyClass()
  47. o.fire_event('event1')
  48. If you wish to define handler in the class definition, the best way is to use
  49. :py:func:`qubes.events.handler` decorator.
  50. .. code-block:: python
  51. import qubes.events
  52. class MyClass(qubes.events.Emitter):
  53. @qubes.events.handler('event1', 'event2')
  54. def event_handler(self, event):
  55. if event == 'event1':
  56. print('Got event 1')
  57. elif event == 'event2':
  58. print('Got event 2')
  59. o = MyClass()
  60. o.fire_event('event1')
  61. .. TODO: extensions
  62. Handling events with variable signature
  63. ---------------------------------------
  64. Some events are specified with variable signature (i.e. they may have different
  65. number of arguments on each call to handlers). You can write handlers just like
  66. every other python function with variable signature.
  67. .. code-block:: python
  68. import qubes
  69. def on_property_change(subject, event, name, newvalue, oldvalue=None):
  70. if oldvalue is None:
  71. print('Property {} initialised to {!r}'.format(name, newvalue))
  72. else:
  73. print('Property {} changed {!r} -> {!r}'.format(name, oldvalue, newvalue))
  74. qubes.Qubes.add_handler('property-set:default_netvm')
  75. If you expect :py:obj:`None` to be a reasonable value of the property, you have
  76. a problem. One way to solve it is to invent your very own, magic
  77. :py:class:`object` instance.
  78. .. code-block:: python
  79. import qubes
  80. MAGIC_NO_VALUE = object()
  81. def on_property_change(subject, event, name, newvalue, oldvalue=MAGIC_NO_VALUE):
  82. if oldvalue is MAGIC_NO_VALUE:
  83. print('Property {} initialised to {!r}'.format(name, newvalue))
  84. else:
  85. print('Property {} changed {!r} -> {!r}'.format(name, oldvalue, newvalue))
  86. qubes.Qubes.add_handler('property-set:default_netvm')
  87. There is no possible way of collision other than intentionally passing this very
  88. object (not even passing similar featureless ``object()``), because ``is``
  89. python syntax checks object's :py:meth:`id`\ entity, which will be different for
  90. each :py:class:`object` instance.
  91. Returning values from events
  92. ----------------------------
  93. Some events may be called to collect values from the handlers. For example the
  94. event ``is-fully-usable`` allows plugins to report a domain as not fully usable.
  95. Such handlers, instead of returning :py:obj:`None` (which is the default when
  96. the function does not include ``return`` statement), should return an iterable
  97. or itself be a generator. Those values are aggregated from all handlers and
  98. returned to the caller as list. The order of this list is undefined.
  99. .. code-block:: python
  100. import qubes.events
  101. class MyClass(qubes.events.Emitter):
  102. @qubes.events.handler('event1')
  103. def event1_handler1(self, event):
  104. # do not return anything, equivalent to "return" and "return None"
  105. pass
  106. @qubes.events.handler('event1')
  107. def event1_handler2(self, event):
  108. yield 'aqq'
  109. yield 'zxc'
  110. @qubes.events.handler('event1')
  111. def event1_handler3(self, event):
  112. return ('123', '456')
  113. o = MyClass()
  114. # returns ['aqq', 'zxc', '123', '456'], possibly not in order
  115. effect = o.fire_event('event1')
  116. Module contents
  117. ---------------
  118. .. automodule:: qubes.events
  119. :members:
  120. :show-inheritance:
  121. .. vim: ts=3 sw=3 et