cozmo.event¶

Event dispatch system.

The SDK is based around the dispatch and observation of events. Objects inheriting from the Dispatcher generate and dispatch events as the state of the robot and its world are updated.

For example the cozmo.objects.LightCube class generates an EvtObjectTapped event anytime the cube the object represents is tapped.

The event can be observed in a number of different ways:

By calling the wait_for() method on the object to observe. This will wait until the specific event has been sent to that object and return the generated event.
By calling add_event_handler() on the object to observe, which will cause the supplied function to be called every time the specified event occurs (use the oneshot() decorator to only have the handler called once)
By sub-classing a type and implementing a receiver method. For example, subclass the cozmo.objects.LightCube type and implement evt_object_tapped. Note that the factory attribute would need to be updated on the generating class for your type to be used by the SDK. For example, light_cube_factory in this example.
By subclassing a type and implementing a default receiver method. Events not dispatched to an explicit receiver method are dispatched to recv_default_handler.

Events are dispatched to a target object (by calling dispatch_event() on the receiving object). In line with the above, upon receiving an event, the object will:

Dispatch the event to any handlers which have explicitly registered interest in the event (or a superclass of the event) via add_event_handler() or via Dispatcher.wait_for()
Dispatch the event to any “children” of the object (see below)
Dispatch the event to method handlers on the receiving object, or the recv_default_handler if it has no matching handler
Dispatch the event to the parent of the object (if any), and in turn onto the parent’s parents.

Any handler may raise a StopPropogation exception to prevent the event reaching any subsequent handlers (but generally should have no need to do so).

Child objects receive all events that are sent to the originating object (which may have multiple children).

Originating objects may have one parent object, which receives all events sent to its child.

For example, cozmo.robot.Robot creates a cozmo.world.World object and sets itself as a parent and the World as the child; both receive events sent to the other.

The World class creates individual cozmo.objects.ObservableObject objects as they are discovered and makes itself a parent, so as to receive all events sent to the child. However, it does not make those ObservableObject objects children for the sake of message dispatch as they only need to receive a small subset of messages the World object receives.

Functions

`filter_handler`(event, **filters)	Decorates a handler function or Future to only be called if a filter is matched.
`oneshot`(f)	Event handler decorator; causes the handler to only be dispatched to once.
`wait_for_first`(*futures[, …])	Wait the first of a set of futures to complete.

Classes

`Dispatcher`(*a[, dispatch_parent, loop])	Mixin to provide event dispatch handling.
`Event`(**kwargs)	An event representing an action that has occurred.
`Filter`(event, **filters)	Provides fine-grain filtering of events for dispatch.
`Handler`	A Handler is returned by `Dispatcher.add_event_handler()`
`NullHandler`
`docstr`

class cozmo.event.Event(**kwargs)¶

An event representing an action that has occurred.

Instances of an Event have attributes set to values passed to the event.

For example, cozmo.objects.EvtObjectTapped defines obj and tap_count parameters which can be accessed as evt.obj and evt.tap_count.

class cozmo.event.Dispatcher(*a, dispatch_parent=None, loop=None, **kw)¶

Mixin to provide event dispatch handling.

add_event_handler(event, f)¶

Register an event handler to be notified when this object receives a type of Event.

Expects a subclass of Event as the first argument. If the class has subclasses then the handler will be notified for events of that subclass too. For example, adding a handler for EvtActionCompleted will cause the handler to also be notified for EvtAnimationCompleted as it’s a subclass.

Callable handlers (e.g. functions) are called with a first argument containing an Event instance and the remaining keyword arguments set as the event parameters.

For example, def my_ontap_handler(evt, *, obj, tap_count, **kwargs) or def my_ontap_handler(evt, obj=None, tap_count=None, **kwargs)

It’s recommended that a **kwargs parameter be included in the definition so that future expansion of event parameters do not cause the handler to fail.

Callable handlers may raise an events.StopProgation exception to prevent other handlers listening to the same event from being triggered.

asyncio.Future handlers are called with a result set to the event.

Parameters:	event (`Event`) – A subclass of `Event` (not an instance of that class) f (callable) – A callable or `asyncio.Future` to execute when the event is received
Raises:	`TypeError` – An invalid event type was supplied

dispatch_event(event, **kw)¶

Dispatches a single event to registered handlers.

Not generally called from user-facing code.

Parameters:	event (`Event`) – An class or instance of `Event` kw (dict) – If a class is passed to event, then the remaining keywords are passed to it to create an instance of the event.
Returns:	A `asyncio.Task` or `asyncio.Future` that will complete once all event handlers have been called.
Raises:	`TypeError` if an invalid event is supplied.

remove_event_handler(event, f)¶

Remove an event handler for this object.

Parameters:	event (`Event`) – The event class, or an instance thereof, used with register_event_handler. f (callable or `Handler`) – The callable object that was passed as a handler to `add_event_handler()`, or a `Handler` instance that was returned by `add_event_handler()`.
Raises:	`ValueError` – No matching handler found.

wait_for(event_or_filter, timeout=30)¶

Waits for the specified event to be sent to the current object.

Parameters:	event_or_filter (`Event`) – Either a `Event` class or a `Filter` instance to wait to trigger timeout – Maximum time to wait for the event. Pass None to wait indefinitely.
Returns:	The `Event` instance that was dispatched
Raises:	`asyncio.TimeoutError`

class cozmo.event.Filter(event, **filters)¶

Provides fine-grain filtering of events for dispatch.

See the ::func::filter_handler method for further details.

class cozmo.event.Handler¶

A Handler is returned by Dispatcher.add_event_handler()

The handler can be disabled at any time by calling its disable() method.

disable()¶: Removes the handler from the object it was originally registered with.

oneshot¶

True if the wrapped handler function will only be called once.

Type:	bool

cozmo.event.oneshot(f)¶: Event handler decorator; causes the handler to only be dispatched to once.

cozmo.event.filter_handler(event, **filters)¶

Decorates a handler function or Future to only be called if a filter is matched.

A handler may apply multiple separate filters; the handlers will be called if any of those filters matches.

For example:

# Handle only if the anim_majorwin animation completed
@filter_handler(cozmo.anim.EvtAnimationCompleted, animation_name="anim_majorwin")

# Handle only when the observed object is a LightCube
@filter_handler(cozmo.objects.EvtObjectObserved, obj=lambda obj: isinstance(cozmo.objects.LightCube))

Parameters:	event (`Event`) – The event class to match on filters (dict) – Zero or more event parameters to filter on. Values may be either strings for exact matches, or functions which accept the value as the first argument and return a bool indicating whether the value passes the filter.

cozmo.event.wait_for_first(*futures, discard_remaining=True, loop=None)¶

Wait the first of a set of futures to complete.

Eg:

event = cozmo.event.wait_for_first(
    coz.world.wait_for_new_cube(),
    playing_anim.wait_for(cozmo.anim.EvtAnimationCompleted)
)

If more than one completes during a single event loop run, then if any of those results are not exception, one of them will be selected (at random, as determined by set.pop) to be returned, else one of the result exceptions will be raised instead.

Parameters:	futures (list of `asyncio.Future`) – The futures or coroutines to wait on. discard_remaining (bool) – Cancel or discard the results of the futures that did not return first. loop (`asyncio.BaseEventLoop`) – The event loop to wait on.
Returns:	The first result, or raised exception