fix: Add MissingVoiceDependencies error (#3158)

If this breaks: paillat said "trust"

Author: Paillat-dev

discord/client.py

@@ -70,8 +70,7 @@
 from .threads import Thread
 from .ui.view import BaseView
 from .user import ClientUser, User
-from .utils import _D, _FETCHABLE, MISSING
-from .voice.utils.dependencies import warn_if_voice_dependencies_missing
+from .utils import _D, _FETCHABLE, MISSING, warn_if_voice_dependencies_missing
 from .webhook import Webhook
 from .widget import Widget
 
@@ -93,7 +92,6 @@
 
 Coro = TypeVar("Coro", bound=Callable[..., Coroutine[Any, Any, Any]])
 
-
 _log = logging.getLogger(__name__)
 
 

discord/errors.py

@@ -64,6 +64,7 @@
     "ApplicationCommandError",
     "CheckFailure",
     "ApplicationCommandInvokeError",
+    "MissingVoiceDependenciesError",
 )
 
 
@@ -411,3 +412,23 @@ def __init__(self, e: Exception) -> None:
         super().__init__(
             f"Application Command raised an exception: {e.__class__.__name__}: {e}"
         )
+
+
+class MissingVoiceDependenciesError(RuntimeError, DiscordException):
+    """Raised when required voice dependencies are not installed.
+
+    .. note::
+        This exception inherits from both :exc:`RuntimeError` and :exc:`DiscordException`.
+
+    Attributes:
+        missing: tuple[str, ...]
+            The missing dependencies that are required for voice support.
+    """
+
+    def __init__(self, missing: tuple[str, ...]) -> None:
+        self.missing: tuple[str, ...] = missing
+        deps = ", ".join(missing)
+        super().__init__(
+            f"{deps} {'is' if len(missing) == 1 else 'are'} required for voice support. "
+            'Install them with "pip install py-cord[voice]".'
+        )

discord/utils.py

@@ -93,7 +93,6 @@
 else:
     HAS_MSGSPEC = True
 
-
 __all__ = (
     "parse_time",
     "warn_deprecated",
@@ -140,7 +139,6 @@
     )
     EMOJIS_MAP = {}
 
-
 UNICODE_EMOJIS = set(EMOJIS_MAP.values())
 
 
@@ -176,7 +174,6 @@ class _RequestLike(Protocol):
     AutocompleteContext = Any
     OptionChoice = Any
 
-
 T = TypeVar("T")
 T_co = TypeVar("T_co", covariant=True)
 _Iter = Union[Iterator[T], AsyncIterator[T]]
@@ -1632,3 +1629,39 @@ def users_to_csv(users: Iterable[Snowflake]) -> io.BytesIO:
         A file-like object containing the CSV data.
     """
     return io.BytesIO("\n".join(map(lambda u: str(u.id), users)).encode("utf-8"))
+
+
+voice_dependency_warning_emitted = False
+
+
+def get_missing_voice_dependencies() -> tuple[str, ...]:
+    missing: list[str] = []
+    try:
+        import nacl.secret
+        import nacl.utils
+    except ImportError:
+        missing.append("PyNaCl")
+
+    try:
+        import davey
+    except ImportError:
+        missing.append("davey")
+    return tuple(missing)
+
+
+def warn_if_voice_dependencies_missing() -> None:
+    global voice_dependency_warning_emitted
+    if voice_dependency_warning_emitted:
+        return
+
+    missing = get_missing_voice_dependencies()
+    if not missing:
+        return
+
+    voice_dependency_warning_emitted = True
+    deps = ", ".join(missing)
+    _log.warning(
+        "%s %s not installed, voice will NOT be supported",
+        deps,
+        "is" if len(missing) == 1 else "are",
+    )

discord/voice/__init__.py

@@ -8,6 +8,12 @@
 :license: MIT, see LICENSE for more details.
 """
 
+from ..errors import MissingVoiceDependenciesError
+from ..utils import get_missing_voice_dependencies
+
+if missing := get_missing_voice_dependencies():
+    raise MissingVoiceDependenciesError(missing=missing)
+
 from ._types import *
 from .client import *
 from .packets import *

discord/voice/client.py

@@ -40,11 +40,12 @@
 from discord.sinks.errors import RecordingException
 from discord.utils import MISSING
 
+from ..utils import get_missing_voice_dependencies
 from ._types import VoiceProtocol
 from .enums import OpCodes
 from .receive import AudioReader
 from .state import VoiceConnectionState
-from .utils.dependencies import HAS_DAVEY, HAS_NACL, get_missing_voice_dependencies
+from .utils.dependencies import HAS_DAVEY, HAS_NACL
 
 if HAS_NACL:
     import nacl.secret

discord/voice/utils/dependencies.py

@@ -22,8 +22,6 @@
 DEALINGS IN THE SOFTWARE.
 """
 
-import logging
-
 try:
     import davey
 except ImportError:
@@ -40,34 +38,3 @@
     HAS_NACL = False
 else:
     HAS_NACL = True
-
-VOICE_DEPENDENCY_WARNING_EMITTED = False
-
-_log = logging.getLogger("discord.client")
-
-
-def get_missing_voice_dependencies() -> tuple[str, ...]:
-    missing: list[str] = []
-    if not HAS_NACL:
-        missing.append("PyNaCl")
-    if not HAS_DAVEY:
-        missing.append("davey")
-    return tuple(missing)
-
-
-def warn_if_voice_dependencies_missing() -> None:
-    global VOICE_DEPENDENCY_WARNING_EMITTED
-    if VOICE_DEPENDENCY_WARNING_EMITTED:
-        return
-
-    missing = get_missing_voice_dependencies()
-    if not missing:
-        return
-
-    VOICE_DEPENDENCY_WARNING_EMITTED = True
-    deps = ", ".join(missing)
-    _log.warning(
-        "%s %s not installed, voice will NOT be supported",
-        deps,
-        "is" if len(missing) == 1 else "are",
-    )

docs/api/exceptions.rst

@@ -41,6 +41,7 @@ Exception Hierarchy
                 - :exc:`sinks.MKVSinkError`
                 - :exc:`sinks.MKASinkError`
                 - :exc:`sinks.OGGSinkError`
+            - :exc:`MissingVoiceDependenciesError`
 
 Objects
 -------
@@ -124,3 +125,5 @@ The following exceptions are thrown by the library.
 .. autoexception:: discord.sinks.MKASinkError
 
 .. autoexception:: discord.sinks.OGGSinkError
+
+.. autoexception:: discord.MissingVoiceDependenciesError

tests/voice/test_dependency_behavior.py

@@ -27,14 +27,13 @@
 import pytest
 
 import discord
-from discord.voice.utils import dependencies as voice_dependencies
 
 
 def test_client_warns_once_when_voice_dependencies_are_missing(caplog):
-    if not voice_dependencies.get_missing_voice_dependencies():
+    if not discord.utils.get_missing_voice_dependencies():
         pytest.skip("requires an environment without the voice extra")
 
-    voice_dependencies.VOICE_DEPENDENCY_WARNING_EMITTED = False
+    discord.utils.voice_dependency_warning_emitted = False
 
     with caplog.at_level(logging.WARNING, logger="discord.client"):
         discord.Client()
@@ -43,19 +42,25 @@ def test_client_warns_once_when_voice_dependencies_are_missing(caplog):
     warnings = [
         record.getMessage()
         for record in caplog.records
-        if record.name == "discord.client"
+        if record.name == "discord.utils"
     ]
     assert len(warnings) == 1
     assert warnings[0].endswith("voice will NOT be supported")
-    for dependency in voice_dependencies.get_missing_voice_dependencies():
+    for dependency in discord.utils.get_missing_voice_dependencies():
         assert dependency in warnings[0]
 
 
-def test_voice_modules_remain_importable_without_voice_dependencies():
-    if not voice_dependencies.get_missing_voice_dependencies():
+def test_voice_modules_imports_without_voice_dependencies():
+    if not discord.utils.get_missing_voice_dependencies():
         pytest.skip("requires an environment without the voice extra")
 
     __import__("discord")
-    __import__("discord.voice")
-    __import__("discord.voice.gateway")
-    __import__("discord.voice.receive.reader")
+
+    with pytest.raises(discord.MissingVoiceDependenciesError):
+        __import__("discord.voice")
+
+    with pytest.raises(discord.MissingVoiceDependenciesError):
+        __import__("discord.voice.gateway")
+
+    with pytest.raises(discord.MissingVoiceDependenciesError):
+        __import__("discord.voice.receive.reader")

tests/voice/test_imports.py

@@ -27,14 +27,13 @@
 import pytest
 
 import discord
-from discord.voice.utils import dependencies as voice_dependencies
 
 
 def test_client_does_not_warn_when_voice_dependencies_are_available(caplog):
-    if voice_dependencies.get_missing_voice_dependencies():
+    if discord.utils.get_missing_voice_dependencies():
         pytest.skip("requires an environment with the voice extra")
 
-    voice_dependencies.VOICE_DEPENDENCY_WARNING_EMITTED = False
+    discord.utils.voice_dependency_warning_emitted = False
 
     with caplog.at_level(logging.WARNING, logger="discord.client"):
         discord.Client()
@@ -48,7 +47,7 @@ def test_client_does_not_warn_when_voice_dependencies_are_available(caplog):
 
 
 def test_voice_modules_import_with_voice_extra():
-    if voice_dependencies.get_missing_voice_dependencies():
+    if discord.utils.get_missing_voice_dependencies():
         pytest.skip("requires an environment with the voice extra")
 
     __import__("discord.voice")