mirror of
https://github.com/xonsh/xonsh.git
synced 2025-03-04 08:24:40 +01:00
42 lines
1.7 KiB
ReStructuredText
42 lines
1.7 KiB
ReStructuredText
.. _events:
|
|
|
|
********************
|
|
Advanced Events
|
|
********************
|
|
|
|
If you havent, go read the `events tutorial <tutorial_events.rst>`_ first. This documents the messy
|
|
details of the event system.
|
|
|
|
You may also find the `events API reference <api/events.html>`_ useful.
|
|
|
|
Why Unordered?
|
|
==============
|
|
Yes, handler call order is not guarenteed. Please don't file bugs about this.
|
|
|
|
This was chosen because the order of handler registration is dependant on load order, which is
|
|
stable in a release but not something generally reasoned about. In addition, xontribs mean that we
|
|
don't know what handlers could be registered. So even an "ordered" event system would be unable to
|
|
make guarentees about ordering because of the larger system.
|
|
|
|
Because of this, the event system is not ordered; this is a form of abstraction. Order-dependant
|
|
semantics are not encouraged by the built-in methods.
|
|
|
|
So how do I handle results?
|
|
===========================
|
|
``Event.fire()`` returns a list of the returns from the handlers. You should merge this list in an
|
|
appropriate way.
|
|
|
|
What are Species?
|
|
=================
|
|
In xonsh, events come in species. Each one may look like an event and quack like an event, but they
|
|
behave differently.
|
|
|
|
This was done because load hooks look like events and quack like events, but they have different
|
|
semantics. See `LoadEvents <api/events.html#xonsh.events.LoadEvent>`_ for details.
|
|
|
|
In order to turn an event from the default ``Event``, you must transmogrify it, using
|
|
``events.transmogrify()``. The class the event is turned in to must be a subclass of ``AbstractEvent``.
|
|
|
|
(Under the hood, transmogrify creates a new instance and copies the handlers and docstring from the
|
|
old instance to the new one.)
|
|
|