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

A given event that handlers can register against.

Acts as a MutableSet for registered handlers.

Note that ordering is never guaranteed.

abstractmethod add(value)

Add an element.

clear()

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

abstractmethod discard(value)

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

abstractmethod fire(**kwargs)

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

An event species for notify and scatter-gather events.

add(item)

Add an element to a set.

If a handler with the same key is already present, it is replaced.

clear()

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

discard(item)

Remove an element from a set if it is a member.

If the element is not a member, do nothing.

fire(**kwargs)

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.

fire_iter(**kwargs)

Iterator variant of fire().

Yields (handler, return_value) lazily as each registered, validation-passing handler runs. Mirrors fire()’s exception handling — handlers that raise are logged and skipped (no pair is yielded for them).

Use this when the caller needs to correlate each result with the handler that produced it (e.g. to trace which handler vetoed in a scatter-gather event).

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

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)

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)

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.

handlers(name=None)

Returns a dictionary of all registered events and their handlers. If name is provided, returns handlers only for that event.

register(func)

wraps EventManager.doc

Parameters:

func

extract name and doc from the function

transmogrify(name, species)

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

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)

Add an element to a set.

If a handler with the same key is already present, it is replaced.

clear()

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

discard(item)

Remove an element from a set if it is a member.

If the element is not a member, do nothing.

fire(**kwargs)

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()

xonsh.events.has_kwargs(func)