asphalt.core.event

class asphalt.core.event.Event(source, topic)

The base class for all events.

Parameters:
  • source – the object where this event originated from
  • topic (str) – the event topic
Variables:
  • source – the object where this event was dispatched from
  • topic (str) – the topic
  • time (float) – event creation time as seconds from the UNIX epoch
  • monotime (float) – event creation time, as returned by time.monotonic()
utc_timestamp

Return a timezone aware datetime corresponding to the time variable, using the UTC timezone.

Return type:datetime
exception asphalt.core.event.EventDispatchError(event, exceptions)

Raised when one or more event listener callbacks raise an exception.

The tracebacks of all the exceptions are displayed in the exception message.

Variables:
  • event (Event) – the event
  • exceptions (Sequence[Tuple[Callable, Exception]]) – a sequence containing tuples of (callback, exception) for each exception that was raised by a listener callback
class asphalt.core.event.Signal(event_class, *, source=None, topic=None)

Declaration of a signal that can be used to dispatch events.

This is a descriptor that returns itself on class level attribute access and a bound version of itself on instance level access. Connecting listeners and dispatching events only works with these bound instances.

Each signal must be assigned to a class attribute, but only once. Assigning the same Signal instance to more than one attribute will raise a LookupError on attribute access.

Parameters:event_class (type) – an event class
connect(callback)

Connect a callback to this signal.

Each callable can only be connected once. Duplicate registrations are ignored.

If you need to pass extra arguments to the callback, you can use functools.partial() to wrap the callable.

Parameters:callback (Callable[[Event], Any]) – a callable that will receive an event object as its only argument.
Return type:Callable[[Event], Any]
Returns:the value of callback argument
disconnect(callback)

Disconnects the given callback.

The callback will no longer receive events from this signal.

No action is taken if the callback is not on the list of listener callbacks.

Parameters:callback (Callable) – the callable to remove
Return type:None
dispatch(*args, return_future=False, **kwargs)

Create and dispatch an event.

This method constructs an event object and then passes it to dispatch_event() for the actual dispatching.

Parameters:
  • args – positional arguments to the constructor of the associated event class.
  • return_future (bool) –

    If True, return a Future that completes when all the listener callbacks have been processed. If any one of them raised an exception, the future will have an EventDispatchError exception set in it which contains all of the exceptions raised in the callbacks.

    If set to False, then None will be returned, and any exceptions raised in listener callbacks will be logged instead.
Return type:

Optional[Future]
Returns:

a future or None, depending on the return_future argument
dispatch_event(event, *, return_future=False)

Dispatch the given event to all listeners.

Creates a new task in which all listener callbacks are called with the given event as the only argument. Coroutine callbacks are converted to their own respective tasks and waited for concurrently.

Parameters:
  • event (Event) – the event object to dispatch
  • return_future (bool) –

    If True, return a Future that completes when all the listener callbacks have been processed. If any one of them raised an exception, the future will have an EventDispatchError exception set in it which contains all of the exceptions raised in the callbacks.

    If set to False, then None will be returned, and any exceptions raised in listener callbacks will be logged instead.
Return type:

Optional[Future]
Returns:

a future or None, depending on the return_future argument
stream_events(max_queue_size=0)

Shortcut for calling stream_events() with this signal as the argument.

wait_event()

Shortcut for calling wait_event() with this signal as the argument.

Return type:coroutine
coroutine asphalt.core.event.wait_event(*signals)

Return the first event dispatched from any of the given signals.

Return type:Event
asphalt.core.event.stream_events(*signals, max_queue_size=0)

Generate event objects to the consumer as they’re dispatched.

This function is meant for use with async for.

Parameters:
  • signals (Signal) – one or more signals to get events from
  • max_queue_size (int) – maximum size of the queue, after which it will start to drop events