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]#