xonsh.events#
Events for xonsh.
In all likelihood, you want xonsh.built_ins.XSH.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
- 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.
- register(func)[source]#
wraps
EventManager.doc
- Parameters
- func
extract name and doc from the function
- 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