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.

add(item)[source]#

Add an element to a set.

This has no effect if the element is already present.

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.

add(item)[source]#

Add an element to a set.

This has no effect if the element is already present.

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

xonsh.events.debug_level()[source]#

xonsh.events.has_kwargs(func)[source]#