Events (xonsh.events
)¶
Events for xonsh.
In all likelihood, you want builtins.events
The best way to “declare” an event is something like:
events.doc('on_spam', "Comes with eggs")
-
class
xonsh.events.
AbstractEvent
[source]¶ A given event that handlers can register against.
Acts as a
MutableSet
for registered handlers.Note that ordering is never guaranteed.
-
abstract
add
(value)¶ Add an element.
-
clear
()¶ This is slow (creates N new iterators!) but effective.
-
abstract
discard
(value)¶ Remove an element. Do not raise an exception if absent.
-
abstract
fire
(**kwargs)[source]¶ Fires an event, calling registered handlers with the given arguments.
- Parameters
- **kwargs :
Keyword arguments to pass to each handler
-
isdisjoint
(other)¶ Return True if two sets have a null intersection.
-
pop
()¶ Return the popped value. Raise KeyError if empty.
-
remove
(value)¶ Remove an element. If not a member, raise a KeyError.
-
property
species
¶ The species (basically, class) of the event
-
abstract
-
class
xonsh.events.
Event
[source]¶ An event species for notify and scatter-gather events.
-
clear
()¶ This is slow (creates N new iterators!) but effective.
-
discard
(item)[source]¶ Remove an element from a set if it is a member.
If the element is not a member, do nothing.
-
fire
(**kwargs)[source]¶ Fires an event, calling registered handlers with the given arguments. A non-unique iterable of the results is returned.
Each handler is called immediately. Exceptions are turned in to warnings.
- Parameters
- **kwargs :
Keyword arguments to pass to each handler
- Returns
- valsiterable
Return values of each handler. If multiple handlers return the same value, it will appear multiple times.
-
isdisjoint
(other)¶ Return True if two sets have a null intersection.
-
pop
()¶ Return the popped value. Raise KeyError if empty.
-
remove
(value)¶ Remove an element. If not a member, raise a KeyError.
-
property
species
¶ The species (basically, class) of the event
-
-
class
xonsh.events.
EventManager
[source]¶ Container for all events in a system.
Meant to be a singleton, but doesn’t enforce that itself.
Each event is just an attribute. They’re created dynamically on first use.
-
doc
(name, docstring)[source]¶ Applies a docstring to an event.
- Parameters
- namestr
The name of the event, eg “on_precommand”
- docstringstr
The docstring to apply to the event
-
exists
(name)[source]¶ Checks if an event with a given name exist. If it does not exist, it will not be created. That is what makes this different than
hasattr(events, name)
, which will create the event.
-
transmogrify
(name, species)[source]¶ Converts an event from one species to another, preserving handlers and docstring.
Please note: Some species maintain specialized state. This is lost on transmogrification.
- Parameters
- namestr
The name of the event, eg “on_precommand”
- speciessubclass of AbstractEvent
The type to turn the event in to.
-
-
class
xonsh.events.
LoadEvent
[source]¶ An event species where each handler is called exactly once, shortly after either the event is fired or the handler is registered (whichever is later). Additional firings are ignored.
Note: Does not support scatter/gather, due to never knowing when we have all the handlers.
Note: Maintains a strong reference to pargs/kwargs in case of the addition of future handlers.
Note: This is currently NOT thread safe.
-
clear
()¶ This is slow (creates N new iterators!) but effective.
-
discard
(item)[source]¶ Remove an element from a set if it is a member.
If the element is not a member, do nothing.
-
fire
(**kwargs)[source]¶ Fires an event, calling registered handlers with the given arguments.
- Parameters
- **kwargs :
Keyword arguments to pass to each handler
-
isdisjoint
(other)¶ Return True if two sets have a null intersection.
-
pop
()¶ Return the popped value. Raise KeyError if empty.
-
remove
(value)¶ Remove an element. If not a member, raise a KeyError.
-
property
species
¶ The species (basically, class) of the event
-