EventTarget

Event handling of WebRTC objects.

Events are delivered in order on the loop an object is bound to; handlers run on the loop they were registered from.

webrtc.utils.events.Handler

A handler, which is a function or a coroutine function called with the webrtc.Event of an event

alias of Callable[[webrtc.Event], object]

webrtc.utils.events.AnyHandler

Any handler, which takes the event class of its event, like webrtc.RTCTrackEvent

alias of Callable[[Never], object]

class webrtc.utils.events.HandlerDecorator(*args, **kwargs)

The decorator returned by on() and once() without a handler, which registers the decorated one.

webrtc.utils.events.call_handler(loop, handler, event, *, message)

Calls a handler; exceptions, async ones too, go to the loop’s exception handler.

class webrtc.utils.events.EventTarget

The base class of objects that emit events.

Handlers are registered with on() or once() by event name, from a running asyncio event loop, and are called on that loop with one event object. They can be functions or coroutine functions, and a coroutine is run as a task. An exception in a handler goes to the exception handler of the loop, and doesn’t stop the other handlers. A handler registered twice for an event is called once.

An object with handlers stays alive while it can still fire them; handlers go when their loop closes.

See MDN: EventTarget.

Example:

@pc.on('icecandidate')
async def on_candidate(event):
    await signaling.send(event.candidate)


pc.on('track', lambda event: print(event.track))
off(name=None, handler=None)

Removes one handler or all of them, for one event or for all events.

See MDN: EventTarget/removeEventListener.

Parameters:

  • name (str, optional) – The name of the event. If omitted, every event.

  • handler (callable, optional) – The handler to remove. If omitted, every handler.

Raises:

ValueError – If the object has no such event.

remove_listener(name, handler)

Removes a handler of an event. Removing one that isn’t registered does nothing.

See MDN: EventTarget/removeEventListener.

Parameters:

  • name (str) – The name of the event.

  • handler (callable) – The handler to remove.

Raises:

ValueError – If the object has no such event.

remove_all_listeners(name=None)

Removes every handler of an event, or of all events.

Parameters:

name (str, optional) – The name of the event. If omitted, every event.

Raises:

ValueError – If the object has no such event.

listeners(name)

Returns the handlers of an event, in the order they were registered.

Parameters:

name (str) – The name of the event.

Returns:

list of callable – The handlers.

Raises:

ValueError – If the object has no such event.

Return type:

list[Callable[[Never], object]]

event_names()

Returns the names of the events that have handlers.

Returns:

set of str – The names.

Return type:

set[str]

class webrtc.utils.events.UniformEventTarget

An EventTarget whose events all have the same event class, which typed handlers take.

on(name: _N_contra, handler: None = None) → HandlerDecorator[_E]
on(name: _N_contra, handler: Callable[[_E], _R]) → Callable[[_E], _R]

Registers a handler of an event. Can be used as a decorator.

See MDN: EventTarget/addEventListener.

Parameters:

  • name (str) – The name of the event, like 'icecandidate'.

  • handler (callable, optional) – A function or a coroutine function called with the event object. If omitted, a decorator is returned.

Returns:

callable – The handler, or a decorator registering it.

Raises:
Return type:

object

once(name: _N_contra, handler: None = None) → HandlerDecorator[_E]
once(name: _N_contra, handler: Callable[[_E], _R]) → Callable[[_E], _R]

Registers a handler that is removed before its first call. Can be used as a decorator.

See MDN: EventTarget/addEventListener.

Parameters:

  • name (str) – The name of the event.

  • handler (callable, optional) – A function or a coroutine function called with the event object. If omitted, a decorator is returned.

Returns:

callable – The handler, or a decorator registering it.

Raises:
Return type:

object