feat: deprecate VoiceRegion enum in favour of dynamic voice regions

CHANGELOG.md

@@ -14,6 +14,9 @@ These changes are available on the `master` branch, but have not yet been releas
 
 - Added `Member.vr_status` property.
   ([#3328](https://github.com/Pycord-Development/pycord/pull/3328))
+- Added `Guild.fetch_voice_regions()` method to retrieve the currently available voice
+  regions for the guild.
+  ([#3347](https://github.com/Pycord-Development/pycord/pull/3347))
 
 ### Changed
 
@@ -27,6 +30,10 @@ These changes are available on the `master` branch, but have not yet been releas
 
 ### Deprecated
 
+- Deprecated the `VoiceRegion` enum in favor of the region ID `str` or
+  `Guild.fetch_voice_regions()`.
+  ([#3347](https://github.com/Pycord-Development/pycord/pull/3347))
+
 ### Removed
 
 ## [2.8.1] - 2026-07-25

discord/enums.py

@@ -30,6 +30,8 @@
 from enum import IntEnum
 from typing import TYPE_CHECKING, Any, ClassVar, TypeVar, Union
 
+from .utils import warn_deprecated
+
 __all__ = (
     "Enum",
     "ChannelType",
@@ -286,32 +288,50 @@ class MessageType(Enum):
     poll_result = 46
 
 
-class VoiceRegion(Enum):
-    """Voice region"""
+class _VoiceRegionMeta(Enum.__class__):
+    def _warn(self, label: str) -> None:
+        warn_deprecated(
+            label,
+            instead="the region ID string or Guild.fetch_voice_regions()",
+            since="2.9",
+            removed="3.0",
+            stacklevel=4,
+        )
+
+    def __getattribute__(cls, name: str) -> Any:
+        members = super().__getattribute__("_enum_member_map_")
+        if name in members:
+            cls._warn(f"VoiceRegion.{name}")
+        return super().__getattribute__(name)
+
+    def __getitem__(cls, name: str) -> Any:
+        member = super().__getitem__(name)
+        cls._warn(f"VoiceRegion[{name!r}]")
+        return member
+
+
+class VoiceRegion(Enum, metaclass=_VoiceRegionMeta):
+    """Specifies the region a voice server belongs to.
+
+    .. deprecated:: 2.9
+        The list of voice regions is dynamic, so this enum is deprecated in favor
+        of the region ID :class:`str` or :meth:`Guild.fetch_voice_regions` and
+        will be removed in version 3.0.
+    """
 
-    us_west = "us-west"
-    us_east = "us-east"
-    us_south = "us-south"
-    us_central = "us-central"
-    eu_west = "eu-west"
-    eu_central = "eu-central"
-    singapore = "singapore"
-    london = "london"
-    sydney = "sydney"
-    amsterdam = "amsterdam"
-    frankfurt = "frankfurt"
     brazil = "brazil"
     hongkong = "hongkong"
-    russia = "russia"
+    india = "india"
     japan = "japan"
-    southafrica = "southafrica"
+    rotterdam = "rotterdam"
+    singapore = "singapore"
     south_korea = "south-korea"
-    india = "india"
-    europe = "europe"
-    dubai = "dubai"
-    vip_us_east = "vip-us-east"
-    vip_us_west = "vip-us-west"
-    vip_amsterdam = "vip-amsterdam"
+    southafrica = "southafrica"
+    sydney = "sydney"
+    us_central = "us-central"
+    us_east = "us-east"
+    us_south = "us-south"
+    us_west = "us-west"
 
     def __str__(self):
         return self.value

discord/guild.py

@@ -121,6 +121,7 @@
     from .types.guild import ModifyIncidents as ModifyIncidentsPayload
     from .types.member import Member as MemberPayload
     from .types.threads import Thread as ThreadPayload
+    from .types.voice import VoiceRegion as VoiceRegionPayload
     from .types.voice import VoiceState as GuildVoiceState
     from .voice import VoiceClient
     from .webhook import Webhook
@@ -3786,6 +3787,44 @@ async def vanity_invite(self) -> Invite | None:
         payload["uses"] = payload.get("uses", 0)
         return Invite(state=self._state, data=payload, guild=self, channel=channel)
 
+    async def fetch_voice_regions(self) -> list[VoiceRegionPayload]:
+        """|coro|
+
+        Retrieves the voice regions that the guild has access to.
+
+        The list of voice regions is dynamic, so this method is the
+        recommended way to get the currently available regions instead of
+        relying on the deprecated :class:`VoiceRegion` enum.
+
+        .. versionadded:: 2.9
+
+        Each payload is a :class:`~discord.types.voice.VoiceRegion` TypedDict
+        with the following keys:
+
+        ``id``
+            The region ID, e.g. ``"us-west"``. Use this as the
+            :attr:`~discord.VoiceChannel.rtc_region` of a voice channel.
+        ``name``
+            The region's display name, e.g. ``"US West"``.
+        ``optimal``
+            Whether the region is optimal for the guild's members.
+        ``deprecated``
+            Whether the region is deprecated.
+        ``custom``
+            Whether the region is a custom region.
+
+        Returns
+        -------
+        List[:class:`~discord.types.voice.VoiceRegion`]
+            The list of voice regions the guild has access to.
+
+        Raises
+        ------
+        HTTPException
+            Retrieving the voice regions failed.
+        """
+        return await self._state.http.get_guild_voice_regions(self.id)
+
     # TODO: use MISSING when async iterators get refactored
     def audit_logs(
         self,

discord/http.py

@@ -85,6 +85,7 @@
         template,
         threads,
         user,
+        voice,
         webhook,
         welcome_screen,
         widget,
@@ -1043,6 +1044,16 @@ def guild_voice_state(
 
         return self.request(r, json=payload, reason=reason)
 
+    def get_guild_voice_regions(
+        self, guild_id: Snowflake
+    ) -> Response[list[voice.VoiceRegion]]:
+        return self.request(
+            Route("GET", "/guilds/{guild_id}/regions", guild_id=guild_id)
+        )
+
+    def get_voice_regions(self) -> Response[list[voice.VoiceRegion]]:
+        return self.request(Route("GET", "/voice/regions"))
+
     def edit_profile(self, payload: dict[str, Any]) -> Response[user.User]:
         return self.request(Route("PATCH", "/users/@me"), json=payload)
 

docs/api/enums.rst

@@ -615,60 +615,37 @@ of :class:`enum.Enum`.
 
     Specifies the region a voice server belongs to.
 
-    .. attribute:: amsterdam
+    .. deprecated:: 2.9
+
+        The list of voice regions is dynamic, so this enum is deprecated in favor
+        of the region ID :class:`str` or :meth:`Guild.fetch_voice_regions` and
+        will be removed in version 3.0.
 
-        The Amsterdam region.
     .. attribute:: brazil
 
         The Brazil region.
-    .. attribute:: dubai
-
-        The Dubai region.
-
-        .. versionadded:: 1.3
-
-    .. attribute:: eu_central
-
-        The EU Central region.
-    .. attribute:: eu_west
-
-        The EU West region.
-    .. attribute:: europe
-
-        The Europe region.
-
-        .. versionadded:: 1.3
-
-    .. attribute:: frankfurt
-
-        The Frankfurt region.
     .. attribute:: hongkong
 
         The Hong Kong region.
     .. attribute:: india
 
         The India region.
-
-        .. versionadded:: 1.2
-
     .. attribute:: japan
 
         The Japan region.
-    .. attribute:: london
+    .. attribute:: rotterdam
 
-        The London region.
-    .. attribute:: russia
+        The Rotterdam region.
 
-        The Russia region.
     .. attribute:: singapore
 
         The Singapore region.
-    .. attribute:: southafrica
-
-        The South Africa region.
     .. attribute:: south_korea
 
         The South Korea region.
+    .. attribute:: southafrica
+
+        The South Africa region.
     .. attribute:: sydney
 
         The Sydney region.
@@ -684,15 +661,6 @@ of :class:`enum.Enum`.
     .. attribute:: us_west
 
         The US West region.
-    .. attribute:: vip_amsterdam
-
-        The Amsterdam region for VIP guilds.
-    .. attribute:: vip_us_east
-
-        The US East region for VIP guilds.
-    .. attribute:: vip_us_west
-
-        The US West region for VIP guilds.
 
 .. class:: VerificationLevel