feat: Add a method to Client to retrieve all voice regions from the API

Signed-off-by: Mathieu C <McCuber04@outlook.de>
Signed-off-by: Mathieu Corsham <McCuber04@outlook.de>

Author: mccoderpy

discord/__init__.py

@@ -57,7 +57,7 @@
 from .player import *
 from .webhook import *
 from .welcome_screen import *
-from .voice_client import VoiceClient, VoiceProtocol
+from .voice_client import *
 from .sink import *
 from .audit_logs import AuditLogChanges, AuditLogEntry, AuditLogDiff
 from .raw_models import *
@@ -67,6 +67,7 @@
 from .automod import *
 
 MISSING = utils.MISSING
+Mentionable = abc.Mentionable
 
 VersionInfo = namedtuple('VersionInfo', 'major minor micro releaselevel serial')
 

discord/application_commands.py

@@ -59,6 +59,7 @@
     try_enum
 )
 from .permissions import Permissions
+from .abc import GuildChannel
 
 if TYPE_CHECKING:
     from datetime import datetime

discord/asset.py

@@ -25,6 +25,8 @@
 """
 from __future__ import annotations
 
+import io
+
 from typing import (
     BinaryIO,
     Optional,
@@ -53,8 +55,6 @@
     HAS_HTTP_CONNECTION = Union[ConnectionState, OAuth2Client]
 
 
-import io
-
 from .errors import DiscordException, InvalidArgument
 from . import utils
 

discord/client.py

@@ -66,7 +66,7 @@
 from .enums import Status, VoiceRegion
 from .gateway import *
 from .activity import BaseActivity, create_activity
-from .voice_client import VoiceClient
+from .voice_client import VoiceRegionInfo, VoiceClient
 from .http import HTTPClient
 from .state import ConnectionState
 from . import utils
@@ -2805,3 +2805,22 @@ async def fetch_all_nitro_stickers(self) -> List[StickerPack]:
         data = await self.http.get_all_nitro_stickers()
         packs = [StickerPack(state=self._connection, data=d) for d in data['sticker_packs']]
         return packs
+
+    async def fetch_voice_regions(self) -> List[VoiceRegionInfo]:
+        """|coro|
+
+        Returns a list of :class:`.VoiceRegionInfo` that can be used when creating or editing a
+        :attr:`VoiceChannel` or :attr:`StageChannel`\'s region.
+
+        .. note::
+
+            This method is an API call.
+            For general usage, consider using the :class:`VoiceRegion` enum instead.
+
+        Returns
+        --------
+        List[:class:`.VoiceRegionInfo`]
+            The voice regions that can be used.
+        """
+        data = await self.http.get_voice_regions()
+        return [VoiceRegionInfo(data=d) for d in data]

discord/types/voice.py

@@ -0,0 +1,36 @@
+"""
+The MIT License (MIT)
+
+Copyright (c) 2021-present mccoderpy
+
+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.
+"""
+
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+
+class VoiceRegion(TypedDict):
+    id: str
+    name: str
+    vip: bool
+    optimal: bool
+    deprecated: bool
+    custom: bool

discord/voice_client.py

@@ -25,6 +25,7 @@
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
+from __future__ import annotations
 
 """Some documentation to refer to:
 
@@ -58,6 +59,11 @@
     Tuple
 )
 
+if TYPE_CHECKING:
+    from .types.voice import (
+        VoiceRegion as VoiceRegionData,
+    )
+
 from . import opus, utils
 from .backoff import ExponentialBackoff
 from .gateway import *
@@ -73,6 +79,84 @@
 
 log = logging.getLogger(__name__)
 
+__all__ = (
+    'VoiceRegionInfo',
+    'VoiceClient',
+    'VoiceProtocol',
+)
+
+
+class VoiceRegionInfo:
+    """A class containing info about a specific voice region.
+
+    These can be retrieved via :meth:`~discord.Client.fetch_voice_regions`.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ------------
+    id: :class:`str`
+        The unique ID of the region.
+    name: :class:`str`
+        The name of the region.
+    vip: :class:`bool`
+        Indicates if this is a VIP-only server.
+    optimal: :class:`bool`
+    	``True`` for a single server that is closest to the current user's client
+    deprecated: :class:`bool`
+        Indicates if this is a deprecated voice region (avoid switching to these).
+    custom: :class:`bool`
+        Indicates if this is a custom voice region (used for events/etc).
+
+    .. container:: operations
+
+        .. describe:: x == y
+            Whether two voice regions are equal.
+        .. describe:: x != y
+            Whether two voice regions are not equal.
+        .. describe:: x > y
+            Whether a voice region is optimal over another.
+        .. describe:: x < y
+            Whether a voice region is not optimal over another.
+        .. describe:: str(x)
+            Returns the id of the region.
+        .. describe:: repr(x)
+            Returns a representation of the region.
+        ..
+    """
+    def __init__(self, *, data: VoiceRegionData) -> None:
+        self.id: str = data['id']
+        self.name: str = data['name']
+        self.vip: bool = data['vip']
+        self.optimal: bool = data['optimal']
+        self.deprecated: bool = data['deprecated']
+        self.custom: bool = data['custom']
+
+    def __repr__(self) -> str:
+        return f'<VoiceRegion id={self.id} name={self.name!r} vip={self.vip} optimal={self.optimal}' \
+               f' deprecated={self.deprecated} custom={self.custom}>'
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, VoiceRegionInfo) and other.id == self.id
+
+    def __ne__(self, other: Any) -> bool:
+        return not self.__eq__(other)
+
+    def __gt__(self, other: Any) -> bool:
+        return isinstance(other, VoiceRegionInfo) and self.optimal and not other.optimal
+
+    def __ge__(self, other: Any) -> bool:
+        return isinstance(other, VoiceRegionInfo) and self.optimal and not other.optimal
+
+    def __lt__(self, other: Any) -> bool:
+        return isinstance(other, VoiceRegionInfo) and not self.optimal and other.optimal
+
+    def __le__(self, other: Any) -> bool:
+        return isinstance(other, VoiceRegionInfo) and not self.optimal and other.optimal
+
+    def __str__(self) -> str:
+        return self.id
+
 
 class VoiceProtocol:
     """A class that represents the Discord voice protocol.

docs/api.rst

@@ -1462,6 +1462,9 @@ of :class:`enum.Enum`.
 
     Specifies the region a voice server belongs to.
 
+    .. note::
+        If you wan\'t to fetch all currently available voice regions, consider using :meth:`Client.fetch_voice_regions`.
+
     .. attribute:: amsterdam
 
         The Amsterdam region.
@@ -3683,6 +3686,14 @@ Sticker
     :members:
     :exclude-members: pack, pack_id, sort_value
 
+VoiceRegionInfo
+~~~~~~~~~~~~~~~~
+
+.. attributetable:: VoiceRegionInfo
+
+.. autoclass:: VoiceRegionInfo()
+    :members:
+
 RawMessageDeleteEvent
 ~~~~~~~~~~~~~~~~~~~~~~~