Skip to content
Back to top
View this page
Edit this page

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

    This has no effect if the element is already present.

  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:
      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.

  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:
      name str

        The name of the event, eg “on_precommand”

      docstring str

        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:
      name str

        The name of the event, eg “on_precommand”

      species subclass 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.

    This has no effect if the element is already present.

  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)