# 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`](models/events.md#webrtc.models.events.Event) of an event

alias of `Callable`[[[`webrtc.Event`](models/events.md#webrtc.models.events.Event)], [`object`](https://docs.python.org/3/builtins/functions.html#object)]

### webrtc.utils.events.AnyHandler

Any handler, which takes the event class of its event, like [`webrtc.RTCTrackEvent`](models/events.md#webrtc.models.events.RTCTrackEvent)

alias of `Callable`[[[`Never`](https://docs.python.org/3/library/typing.html#typing.Never)], [`object`](https://docs.python.org/3/builtins/functions.html#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](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget).

Example:

```default
@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](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener).

* **Parameters:**
  * **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str), optional) – The name of the event. If omitted, every event.
  * **handler** ([`callable`](https://docs.python.org/3/builtins/functions.html#callable), optional) – The handler to remove. If omitted, every handler.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#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](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener).

* **Parameters:**
  * **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the event.
  * **handler** ([`callable`](https://docs.python.org/3/builtins/functions.html#callable)) – The handler to remove.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#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`](https://docs.python.org/3/builtins/stdtypes.html#str), optional) – The name of the event. If omitted, every event.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#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`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the event.
* **Returns:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`callable`](https://docs.python.org/3/builtins/functions.html#callable) – The handlers.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the object has no such event.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable)[[[*Never*](https://docs.python.org/3/library/typing.html#typing.Never)], [object](https://docs.python.org/3/builtins/functions.html#object)]]

#### event_names()

Returns the names of the events that have handlers.

* **Returns:**
  [`set`](https://docs.python.org/3/builtins/stdtypes.html#set) of [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) – The names.
* **Return type:**
  [set](https://docs.python.org/3/builtins/stdtypes.html#set)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]

### *class* webrtc.utils.events.UniformEventTarget

An [`EventTarget`](#webrtc.utils.events.EventTarget) whose events all have the same event class, which typed handlers take.

#### on(name: \_N_contra, handler: [None](https://docs.python.org/3/builtins/constants.html#None) = None) → [HandlerDecorator](#webrtc.utils.events.HandlerDecorator)[\_E]

#### on(name: \_N_contra, handler: [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[\_E], \_R]) → [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[\_E], \_R]

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

See [MDN: EventTarget/addEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener).

* **Parameters:**
  * **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the event, like `'icecandidate'`.
  * **handler** ([`callable`](https://docs.python.org/3/builtins/functions.html#callable), optional) – A function or a coroutine function called with the event object.
    If omitted, a decorator is returned.
* **Returns:**
  [`callable`](https://docs.python.org/3/builtins/functions.html#callable) – The handler, or a decorator registering it.
* **Raises:**
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the object has no such event.
  * [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If called outside of a running event loop.
* **Return type:**
  [object](https://docs.python.org/3/builtins/functions.html#object)

#### once(name: \_N_contra, handler: [None](https://docs.python.org/3/builtins/constants.html#None) = None) → [HandlerDecorator](#webrtc.utils.events.HandlerDecorator)[\_E]

#### once(name: \_N_contra, handler: [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[\_E], \_R]) → [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[\_E], \_R]

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

See [MDN: EventTarget/addEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener).

* **Parameters:**
  * **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the event.
  * **handler** ([`callable`](https://docs.python.org/3/builtins/functions.html#callable), optional) – A function or a coroutine function called with the event object.
    If omitted, a decorator is returned.
* **Returns:**
  [`callable`](https://docs.python.org/3/builtins/functions.html#callable) – The handler, or a decorator registering it.
* **Raises:**
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the object has no such event.
  * [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If called outside of a running event loop.
* **Return type:**
  [object](https://docs.python.org/3/builtins/functions.html#object)