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.

add(value)

Add an element.

clear()

This is slow (creates N new iterators!) but effective.

discard(value)

Remove an element. Do not raise an exception if absent.

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.

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:

vals : iterable

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.

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:

name : str

The name of the event, eg “on_precommand”

docstring : str

The docstring to apply to 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:

name : str

The name of the event, eg “on_precommand”

species : sublcass 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]
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.

species

The species (basically, class) of the event

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