Events that fire when voice state changes.

This module

Expand source code
Browse git
# -*- coding: utf-8 -*-
# cython: language_level=3
# Copyright (c) 2020 Nekokatt
# Copyright (c) 2021-present davfsa
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""Events that fire when voice state changes."""

from __future__ import annotations

__all__: typing.Sequence[str] = ("VoiceEvent", "VoiceStateUpdateEvent", "VoiceServerUpdateEvent")

import abc
import typing

import attr

from hikari import intents
from hikari.events import base_events
from hikari.events import shard_events
from hikari.internal import attr_extensions

if typing.TYPE_CHECKING:
    from hikari import snowflakes
    from hikari import traits
    from hikari import voices
    from hikari.api import shard as gateway_shard


class VoiceEvent(shard_events.ShardEvent, abc.ABC):
    """Base for any voice-related event."""

    __slots__: typing.Sequence[str] = ()

    @property
    @abc.abstractmethod
    def guild_id(self) -> snowflakes.Snowflake:
        """ID of the guild this event is for.

        Returns
        -------
        hikari.snowflakes.Snowflake
            The guild ID of the guild this event relates to.
        """


@base_events.requires_intents(intents.Intents.GUILD_VOICE_STATES)
@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
class VoiceStateUpdateEvent(VoiceEvent):
    """Event fired when a user changes their voice state.

    Sent when a user joins, leaves or moves voice channel(s).

    This is also fired for the application user, and is used when preparing
    to connect to the voice gateway to stream audio or video content.
    """

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring>>.

    old_state: typing.Optional[voices.VoiceState] = attr.field(repr=True)
    """The old voice state.

    This will be `builtins.None` if the voice state missing from the cache.
    """

    state: voices.VoiceState = attr.field(repr=True)
    """Voice state that this update contained.

    Returns
    -------
    hikari.voices.VoiceState
        The voice state that was updated.
    """

    @property
    def app(self) -> traits.RESTAware:
        # <<inherited docstring from Event>>.
        return self.state.app

    @property
    def guild_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from VoiceEvent>>
        return self.state.guild_id


@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
class VoiceServerUpdateEvent(VoiceEvent):
    """Event fired when a voice server is changed.

    Sent when initially connecting to voice and when the current voice instance
    falls over to a new server.
    """

    app: traits.RESTAware = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from Event>>.

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from ShardEvent>>.

    guild_id: snowflakes.Snowflake = attr.field(repr=True)
    # <<inherited docstring from VoiceEvent>>

    token: str = attr.field(repr=False)
    """Token that should be used to authenticate with the voice gateway.

    Returns
    -------
    builtins.str
        The token to use to authenticate with the voice gateway.
    """

    raw_endpoint: typing.Optional[str] = attr.field(repr=True)
    """Raw endpoint URI that Discord sent.

    If this is `builtins.None`, it means that the server has been deallocated
    and you have to disconnect. You will later receive a new event specifying
    what endpoint to connect to.

    !!! warning
        This will not contain the scheme to use. Use the `endpoint` property
        to get a representation that has this prepended.

    Returns
    -------
    builtins.str
        A scheme-less endpoint URI for the endpoint to use for a new voice
        websocket.
    """

    @property
    def endpoint(self) -> typing.Optional[str]:
        """URI for this voice server host, with the correct scheme prepended.

        If this is `builtins.None`, it means that the server has been deallocated
        and you have to disconnect. You will later receive a new event specifying
        what endpoint to connect to.

        Returns
        -------
        typing.Optional[builtins.str]
            If not `builtins.None`, the URI to use to connect to the voice gateway.
        """
        if self.raw_endpoint is None:
            return None

        return f"wss://{self.raw_endpoint}"

Classes

class VoiceEvent

class VoiceEvent: ...

Base for any voice-related event.

Expand source code
Browse git
class VoiceEvent(shard_events.ShardEvent, abc.ABC):
    """Base for any voice-related event."""

    __slots__: typing.Sequence[str] = ()

    @property
    @abc.abstractmethod
    def guild_id(self) -> snowflakes.Snowflake:
        """ID of the guild this event is for.

        Returns
        -------
        hikari.snowflakes.Snowflake
            The guild ID of the guild this event relates to.
        """
Subclasses
dataclass VoiceServerUpdateEvent

Event fired when a voice server is changed …

dataclass VoiceStateUpdateEvent

Event fired when a user changes their voice state …

Method resolution order
abstract class VoiceEvent
That's this class!
abstract class ShardEvent

Base class for any event that was shard-specific.

abstract class Event

Base event type that all Hikari events should subclass.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
abstract property appRESTAware

App instance for this application.

Returns

RESTAware
The REST-aware app trait.
abstract property guild_idsnowflakes.Snowflake

ID of the guild this event is for.

Returns

Snowflake
The guild ID of the guild this event relates to.
abstract property shardgateway_shard.GatewayShard

Shard that received this event.

Returns

GatewayShard
The shard that triggered the event.
Methods
def bitmask() -> int: ...

Inherited from: ShardEvent.bitmask

Bitmask for this event.

def dispatches() -> Sequence[Type[Event]]: ...

Inherited from: ShardEvent.dispatches

Sequence of the event classes this event is dispatched as.

dataclass VoiceServerUpdateEvent

class VoiceServerUpdateEvent (
    *,
    app: traits.RESTAware,
    shard: gateway_shard.GatewayShard,
    guild_id: snowflakes.Snowflake,
    token: str,
    raw_endpoint: Optional[str],
): ...

Event fired when a voice server is changed.

Sent when initially connecting to voice and when the current voice instance falls over to a new server.

Method generated by attrs for class VoiceServerUpdateEvent.

Expand source code
Browse git
class VoiceServerUpdateEvent(VoiceEvent):
    """Event fired when a voice server is changed.

    Sent when initially connecting to voice and when the current voice instance
    falls over to a new server.
    """

    app: traits.RESTAware = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from Event>>.

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from ShardEvent>>.

    guild_id: snowflakes.Snowflake = attr.field(repr=True)
    # <<inherited docstring from VoiceEvent>>

    token: str = attr.field(repr=False)
    """Token that should be used to authenticate with the voice gateway.

    Returns
    -------
    builtins.str
        The token to use to authenticate with the voice gateway.
    """

    raw_endpoint: typing.Optional[str] = attr.field(repr=True)
    """Raw endpoint URI that Discord sent.

    If this is `builtins.None`, it means that the server has been deallocated
    and you have to disconnect. You will later receive a new event specifying
    what endpoint to connect to.

    !!! warning
        This will not contain the scheme to use. Use the `endpoint` property
        to get a representation that has this prepended.

    Returns
    -------
    builtins.str
        A scheme-less endpoint URI for the endpoint to use for a new voice
        websocket.
    """

    @property
    def endpoint(self) -> typing.Optional[str]:
        """URI for this voice server host, with the correct scheme prepended.

        If this is `builtins.None`, it means that the server has been deallocated
        and you have to disconnect. You will later receive a new event specifying
        what endpoint to connect to.

        Returns
        -------
        typing.Optional[builtins.str]
            If not `builtins.None`, the URI to use to connect to the voice gateway.
        """
        if self.raw_endpoint is None:
            return None

        return f"wss://{self.raw_endpoint}"
Method resolution order
dataclass VoiceServerUpdateEvent
That's this class!
abstract class VoiceEvent

Base for any voice-related event.

abstract class ShardEvent

Base class for any event that was shard-specific.

abstract class Event

Base event type that all Hikari events should subclass.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

App instance for this application.

Returns

RESTAware
The REST-aware app trait.
property endpoint : Optional[str]

URI for this voice server host, with the correct scheme prepended.

If this is None, it means that the server has been deallocated and you have to disconnect. You will later receive a new event specifying what endpoint to connect to.

Returns

Optional[str]
If not None, the URI to use to connect to the voice gateway.
property guild_idsnowflakes.Snowflake

ID of the guild this event is for.

Returns

Snowflake
The guild ID of the guild this event relates to.
property raw_endpointOptional[str]

Raw endpoint URI that Discord sent.

If this is None, it means that the server has been deallocated and you have to disconnect. You will later receive a new event specifying what endpoint to connect to.

Warning

This will not contain the scheme to use. Use the endpoint property to get a representation that has this prepended.

Returns

str
A scheme-less endpoint URI for the endpoint to use for a new voice websocket.
property shardgateway_shard.GatewayShard

Shard that received this event.

Returns

GatewayShard
The shard that triggered the event.
property tokenstr

Token that should be used to authenticate with the voice gateway.

Returns

str
The token to use to authenticate with the voice gateway.
Methods
def bitmask() -> int: ...

Inherited from: VoiceEvent.bitmask

Bitmask for this event.

def dispatches() -> Sequence[Type[Event]]: ...

Inherited from: VoiceEvent.dispatches

Sequence of the event classes this event is dispatched as.

dataclass VoiceStateUpdateEvent

class VoiceStateUpdateEvent (
    *,
    shard: gateway_shard.GatewayShard,
    old_state: Optional[voices.VoiceState],
    state: voices.VoiceState,
): ...

Event fired when a user changes their voice state.

Sent when a user joins, leaves or moves voice channel(s).

This is also fired for the application user, and is used when preparing to connect to the voice gateway to stream audio or video content.

This requires one of the following combinations of intents in order to be dispatched:

Method generated by attrs for class VoiceStateUpdateEvent.

Expand source code
Browse git
class VoiceStateUpdateEvent(VoiceEvent):
    """Event fired when a user changes their voice state.

    Sent when a user joins, leaves or moves voice channel(s).

    This is also fired for the application user, and is used when preparing
    to connect to the voice gateway to stream audio or video content.
    """

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring>>.

    old_state: typing.Optional[voices.VoiceState] = attr.field(repr=True)
    """The old voice state.

    This will be `builtins.None` if the voice state missing from the cache.
    """

    state: voices.VoiceState = attr.field(repr=True)
    """Voice state that this update contained.

    Returns
    -------
    hikari.voices.VoiceState
        The voice state that was updated.
    """

    @property
    def app(self) -> traits.RESTAware:
        # <<inherited docstring from Event>>.
        return self.state.app

    @property
    def guild_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from VoiceEvent>>
        return self.state.guild_id
Method resolution order
dataclass VoiceStateUpdateEvent
That's this class!
abstract class VoiceEvent

Base for any voice-related event.

abstract class ShardEvent

Base class for any event that was shard-specific.

abstract class Event

Base event type that all Hikari events should subclass.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

App instance for this application.

Returns

RESTAware
The REST-aware app trait.
property guild_idsnowflakes.Snowflake

ID of the guild this event is for.

Returns

Snowflake
The guild ID of the guild this event relates to.
property old_stateOptional[voices.VoiceState]

The old voice state.

This will be None if the voice state missing from the cache.

property shardgateway_shard.GatewayShard

Shard that received this event.

Returns

GatewayShard
The shard that triggered the event.
property statevoices.VoiceState

Voice state that this update contained.

Returns

VoiceState
The voice state that was updated.
Methods
def bitmask() -> int: ...

Inherited from: VoiceEvent.bitmask

Bitmask for this event.

def dispatches() -> Sequence[Type[Event]]: ...

Inherited from: VoiceEvent.dispatches

Sequence of the event classes this event is dispatched as.