disagreement 0.0.2__py3-none-any.whl → 0.1.0rc2__py3-none-any.whl

disagreement/__init__.py

@@ -14,18 +14,23 @@ __title__ = "disagreement"
 __author__ = "Slipstream"
 __license__ = "BSD 3-Clause License"
 __copyright__ = "Copyright 2025 Slipstream"
-__version__ = "0.0.2"
+__version__ = "0.1.0rc2"
 
-from .client import Client
-from .models import Message, User
+from .client import Client, AutoShardedClient
+from .models import Message, User, Reaction
 from .voice_client import VoiceClient
+from .audio import AudioSource, FFmpegAudioSource
 from .typing import Typing
 from .errors import (
     DisagreementException,
     HTTPException,
     GatewayException,
     AuthenticationError,
+    Forbidden,
+    NotFound,
 )
+from .color import Color
+from .utils import utcnow, message_pager
 from .enums import GatewayIntent, GatewayOpcode  # Export enums
 from .error_handler import setup_global_error_handler
 from .hybrid_context import HybridContext

disagreement/audio.py

@@ -0,0 +1,116 @@
+"""Audio source abstractions for the voice client."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import io
+from typing import Optional, Union
+
+
+class AudioSource:
+    """Abstract base class for audio sources."""
+
+    async def read(self) -> bytes:
+        """Read the next chunk of PCM audio.
+
+        Subclasses must implement this and return raw PCM data
+        at 48kHz stereo (3840 byte chunks).
+        """
+
+        raise NotImplementedError
+
+    async def close(self) -> None:
+        """Cleanup the source when playback ends."""
+
+        return None
+
+
+class FFmpegAudioSource(AudioSource):
+    """Decode audio using FFmpeg.
+
+    Parameters
+    ----------
+    source:
+        A filename, URL, or file-like object to read from.
+    """
+
+    def __init__(self, source: Union[str, io.BufferedIOBase]):
+        self.source = source
+        self.process: Optional[asyncio.subprocess.Process] = None
+        self._feeder: Optional[asyncio.Task] = None
+
+    async def _spawn(self) -> None:
+        if isinstance(self.source, str):
+            args = [
+                "ffmpeg",
+                "-i",
+                self.source,
+                "-f",
+                "s16le",
+                "-ar",
+                "48000",
+                "-ac",
+                "2",
+                "pipe:1",
+            ]
+            self.process = await asyncio.create_subprocess_exec(
+                *args,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+        else:
+            args = [
+                "ffmpeg",
+                "-i",
+                "pipe:0",
+                "-f",
+                "s16le",
+                "-ar",
+                "48000",
+                "-ac",
+                "2",
+                "pipe:1",
+            ]
+            self.process = await asyncio.create_subprocess_exec(
+                *args,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+            assert self.process.stdin is not None
+            self._feeder = asyncio.create_task(self._feed())
+
+    async def _feed(self) -> None:
+        assert isinstance(self.source, io.BufferedIOBase)
+        assert self.process is not None
+        assert self.process.stdin is not None
+        while True:
+            data = await asyncio.to_thread(self.source.read, 4096)
+            if not data:
+                break
+            self.process.stdin.write(data)
+            await self.process.stdin.drain()
+        self.process.stdin.close()
+
+    async def read(self) -> bytes:
+        if self.process is None:
+            await self._spawn()
+        assert self.process is not None
+        assert self.process.stdout is not None
+        data = await self.process.stdout.read(3840)
+        if not data:
+            await self.close()
+        return data
+
+    async def close(self) -> None:
+        if self._feeder:
+            self._feeder.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._feeder
+        if self.process:
+            await self.process.wait()
+            self.process = None
+        if isinstance(self.source, io.IOBase):
+            with contextlib.suppress(Exception):
+                self.source.close()

disagreement/client.py

@@ -16,20 +16,23 @@ from typing import (
     List,
     Dict,
 )
+from types import ModuleType
 
 from .http import HTTPClient
 from .gateway import GatewayClient
 from .shard_manager import ShardManager
 from .event_dispatcher import EventDispatcher
-from .enums import GatewayIntent, InteractionType
+from .enums import GatewayIntent, InteractionType, GatewayOpcode
 from .errors import DisagreementException, AuthenticationError
 from .typing import Typing
 from .ext.commands.core import CommandHandler
 from .ext.commands.cog import Cog
 from .ext.app_commands.handler import AppCommandHandler
 from .ext.app_commands.context import AppCommandContext
+from .ext import loader as ext_loader
 from .interactions import Interaction, Snowflake
 from .error_handler import setup_global_error_handler
+from .voice_client import VoiceClient
 
 if TYPE_CHECKING:
     from .models import (
@@ -46,6 +49,7 @@ if TYPE_CHECKING:
         CategoryChannel,
         Thread,
         DMChannel,
+        Webhook,
     )
     from .ui.view import View
     from .enums import ChannelType as EnumChannelType
@@ -82,6 +86,8 @@ class Client:
         verbose: bool = False,
         mention_replies: bool = False,
         shard_count: Optional[int] = None,
+        gateway_max_retries: int = 5,
+        gateway_max_backoff: float = 60.0,
     ):
         if not token:
             raise ValueError("A bot token must be provided.")
@@ -101,6 +107,8 @@ class Client:
             None  # Initialized in run() or connect()
         )
         self.shard_count: Optional[int] = shard_count
+        self.gateway_max_retries: int = gateway_max_retries
+        self.gateway_max_backoff: float = gateway_max_backoff
         self._shard_manager: Optional[ShardManager] = None
 
         # Initialize CommandHandler
@@ -133,6 +141,8 @@ class Client:
         )  # Placeholder for User model cache if needed
         self._messages: Dict[Snowflake, "Message"] = {}
         self._views: Dict[Snowflake, "View"] = {}
+        self._voice_clients: Dict[Snowflake, VoiceClient] = {}
+        self._webhooks: Dict[Snowflake, "Webhook"] = {}
 
         # Default whether replies mention the user
         self.mention_replies: bool = mention_replies
@@ -165,6 +175,8 @@ class Client:
                 intents=self.intents,
                 client_instance=self,
                 verbose=self.verbose,
+                max_retries=self.gateway_max_retries,
+                max_backoff=self.gateway_max_backoff,
             )
 
     async def _initialize_shard_manager(self) -> None:
@@ -361,6 +373,13 @@ class Client:
         """Indicates if the client has successfully connected to the Gateway and is ready."""
         return self._ready_event.is_set()
 
+    @property
+    def latency(self) -> Optional[float]:
+        """Returns the gateway latency in seconds, or ``None`` if unavailable."""
+        if self._gateway:
+            return self._gateway.latency
+        return None
+
     async def wait_until_ready(self) -> None:
         """|coro|
         Waits until the client is fully connected to Discord and the initial state is processed.
@@ -448,11 +467,16 @@ class Client:
         # Map common function names to Discord event types
         # e.g., on_ready -> READY, on_message -> MESSAGE_CREATE
         if event_name.startswith("on_"):
-            discord_event_name = event_name[3:].upper()  # e.g., on_message -> MESSAGE
-            if discord_event_name == "MESSAGE":  # Common case
-                discord_event_name = "MESSAGE_CREATE"
-            # Add other mappings if needed, e.g. on_member_join -> GUILD_MEMBER_ADD
-
+            discord_event_name = event_name[3:].upper()
+            mapping = {
+                "MESSAGE": "MESSAGE_CREATE",
+                "MESSAGE_EDIT": "MESSAGE_UPDATE",
+                "MESSAGE_UPDATE": "MESSAGE_UPDATE",
+                "MESSAGE_DELETE": "MESSAGE_DELETE",
+                "REACTION_ADD": "MESSAGE_REACTION_ADD",
+                "REACTION_REMOVE": "MESSAGE_REACTION_REMOVE",
+            }
+            discord_event_name = mapping.get(discord_event_name, discord_event_name)
             self._event_dispatcher.register(discord_event_name, coro)
         else:
             # If not starting with "on_", assume it's the direct Discord event name (e.g. "TYPING_START")
@@ -616,6 +640,23 @@ class Client:
             # import traceback
             # traceback.print_exception(type(error.original), error.original, error.original.__traceback__)
 
+    # --- Extension Management Methods ---
+
+    def load_extension(self, name: str) -> ModuleType:
+        """Load an extension by name using :mod:`disagreement.ext.loader`."""
+
+        return ext_loader.load_extension(name)
+
+    def unload_extension(self, name: str) -> None:
+        """Unload a previously loaded extension."""
+
+        ext_loader.unload_extension(name)
+
+    def reload_extension(self, name: str) -> ModuleType:
+        """Reload an extension by name."""
+
+        return ext_loader.reload_extension(name)
+
     # --- Model Parsing and Fetching ---
 
     def parse_user(self, data: Dict[str, Any]) -> "User":
@@ -648,6 +689,19 @@ class Client:
         self._messages[message.id] = message
         return message
 
+    def parse_webhook(self, data: Union[Dict[str, Any], "Webhook"]) -> "Webhook":
+        """Parses webhook data and returns a Webhook object, updating cache."""
+
+        from .models import Webhook
+
+        if isinstance(data, Webhook):
+            webhook = data
+            webhook._client = self  # type: ignore[attr-defined]
+        else:
+            webhook = Webhook(data, client_instance=self)
+        self._webhooks[webhook.id] = webhook
+        return webhook
+
     async def fetch_user(self, user_id: Snowflake) -> Optional["User"]:
         """Fetches a user by ID from Discord."""
         if self._closed:
@@ -830,6 +884,8 @@ class Client:
         components: Optional[List["ActionRow"]] = None,
         allowed_mentions: Optional[Dict[str, Any]] = None,
         message_reference: Optional[Dict[str, Any]] = None,
+        attachments: Optional[List[Any]] = None,
+        files: Optional[List[Any]] = None,
         flags: Optional[int] = None,
         view: Optional["View"] = None,
     ) -> "Message":
@@ -846,6 +902,8 @@ class Client:
             components (Optional[List[ActionRow]]): A list of ActionRow components to include.
             allowed_mentions (Optional[Dict[str, Any]]): Allowed mentions for the message.
             message_reference (Optional[Dict[str, Any]]): Message reference for replying.
+            attachments (Optional[List[Any]]): Attachments to include with the message.
+            files (Optional[List[Any]]): Files to upload with the message.
             flags (Optional[int]): Message flags.
             view (Optional[View]): A view to send with the message.
 
@@ -881,12 +939,12 @@ class Client:
             await view._start(self)
             components_payload = view.to_components_payload()
         elif components:
-            from .models import ActionRow as ActionRowModel
+            from .models import Component as ComponentModel
 
             components_payload = [
                 comp.to_dict()
                 for comp in components
-                if isinstance(comp, ActionRowModel)
+                if isinstance(comp, ComponentModel)
             ]
 
         message_data = await self._http.send_message(
@@ -897,6 +955,8 @@ class Client:
             components=components_payload,
             allowed_mentions=allowed_mentions,
             message_reference=message_reference,
+            attachments=attachments,
+            files=files,
             flags=flags,
         )
 
@@ -912,6 +972,89 @@ class Client:
 
         return Typing(self, channel_id)
 
+    async def join_voice(
+        self,
+        guild_id: Snowflake,
+        channel_id: Snowflake,
+        *,
+        self_mute: bool = False,
+        self_deaf: bool = False,
+    ) -> VoiceClient:
+        """|coro| Join a voice channel and return a :class:`VoiceClient`."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+        if not self.is_ready():
+            await self.wait_until_ready()
+        if self._gateway is None:
+            raise DisagreementException("Gateway is not connected.")
+        if not self.user:
+            raise DisagreementException("Client user unavailable.")
+        assert self.user is not None
+        user_id = self.user.id
+
+        if guild_id in self._voice_clients:
+            return self._voice_clients[guild_id]
+
+        payload = {
+            "op": GatewayOpcode.VOICE_STATE_UPDATE,
+            "d": {
+                "guild_id": str(guild_id),
+                "channel_id": str(channel_id),
+                "self_mute": self_mute,
+                "self_deaf": self_deaf,
+            },
+        }
+        await self._gateway._send_json(payload)  # type: ignore[attr-defined]
+
+        server = await self.wait_for(
+            "VOICE_SERVER_UPDATE",
+            check=lambda d: d.get("guild_id") == str(guild_id),
+            timeout=10,
+        )
+        state = await self.wait_for(
+            "VOICE_STATE_UPDATE",
+            check=lambda d, uid=user_id: d.get("guild_id") == str(guild_id)
+            and d.get("user_id") == str(uid),
+            timeout=10,
+        )
+
+        endpoint = f"wss://{server['endpoint']}?v=10"
+        token = server["token"]
+        session_id = state["session_id"]
+
+        voice = VoiceClient(
+            endpoint,
+            session_id,
+            token,
+            int(guild_id),
+            int(self.user.id),
+            verbose=self.verbose,
+        )
+        await voice.connect()
+        self._voice_clients[guild_id] = voice
+        return voice
+
+    async def add_reaction(self, channel_id: str, message_id: str, emoji: str) -> None:
+        """|coro| Add a reaction to a message."""
+
+        await self.create_reaction(channel_id, message_id, emoji)
+
+    async def remove_reaction(
+        self, channel_id: str, message_id: str, emoji: str
+    ) -> None:
+        """|coro| Remove the bot's reaction from a message."""
+
+        await self.delete_reaction(channel_id, message_id, emoji)
+
+    async def clear_reactions(self, channel_id: str, message_id: str) -> None:
+        """|coro| Remove all reactions from a message."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        await self._http.clear_reactions(channel_id, message_id)
+
     async def create_reaction(
         self, channel_id: str, message_id: str, emoji: str
     ) -> None:
@@ -922,6 +1065,16 @@ class Client:
 
         await self._http.create_reaction(channel_id, message_id, emoji)
 
+        user_id = getattr(getattr(self, "user", None), "id", None)
+        payload = {
+            "user_id": user_id,
+            "channel_id": channel_id,
+            "message_id": message_id,
+            "emoji": {"name": emoji, "id": None},
+        }
+        if hasattr(self, "_event_dispatcher"):
+            await self._event_dispatcher.dispatch("MESSAGE_REACTION_ADD", payload)
+
     async def delete_reaction(
         self, channel_id: str, message_id: str, emoji: str
     ) -> None:
@@ -932,6 +1085,16 @@ class Client:
 
         await self._http.delete_reaction(channel_id, message_id, emoji)
 
+        user_id = getattr(getattr(self, "user", None), "id", None)
+        payload = {
+            "user_id": user_id,
+            "channel_id": channel_id,
+            "message_id": message_id,
+            "emoji": {"name": emoji, "id": None},
+        }
+        if hasattr(self, "_event_dispatcher"):
+            await self._event_dispatcher.dispatch("MESSAGE_REACTION_REMOVE", payload)
+
     async def get_reactions(
         self, channel_id: str, message_id: str, emoji: str
     ) -> List["User"]:
@@ -1060,6 +1223,36 @@ class Client:
             print(f"Failed to fetch channel {channel_id}: {e}")
             return None
 
+    async def create_webhook(
+        self, channel_id: Snowflake, payload: Dict[str, Any]
+    ) -> "Webhook":
+        """|coro| Create a webhook in the given channel."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.create_webhook(channel_id, payload)
+        return self.parse_webhook(data)
+
+    async def edit_webhook(
+        self, webhook_id: Snowflake, payload: Dict[str, Any]
+    ) -> "Webhook":
+        """|coro| Edit an existing webhook."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.edit_webhook(webhook_id, payload)
+        return self.parse_webhook(data)
+
+    async def delete_webhook(self, webhook_id: Snowflake) -> None:
+        """|coro| Delete a webhook by ID."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        await self._http.delete_webhook(webhook_id)
+
     # --- Application Command Methods ---
     async def process_interaction(self, interaction: Interaction) -> None:
         """Internal method to process an interaction from the gateway."""
@@ -1142,3 +1335,19 @@ class Client:
 
         print(f"Unhandled exception in event listener for '{event_method}':")
         print(f"{type(exc).__name__}: {exc}")
+
+
+class AutoShardedClient(Client):
+    """A :class:`Client` that automatically determines the shard count.
+
+    If ``shard_count`` is not provided, the client will query the Discord API
+    via :meth:`HTTPClient.get_gateway_bot` for the recommended shard count and
+    use that when connecting.
+    """
+
+    async def connect(self, reconnect: bool = True) -> None:  # type: ignore[override]
+        if self.shard_count is None:
+            data = await self._http.get_gateway_bot()
+            self.shard_count = data.get("shards", 1)
+
+        await super().connect(reconnect=reconnect)

disagreement/color.py

@@ -0,0 +1,78 @@
+"""Simple color helper similar to discord.py's Color class."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Color:
+    """Represents an RGB color value."""
+
+    value: int
+
+    def __post_init__(self) -> None:
+        if not 0 <= self.value <= 0xFFFFFF:
+            raise ValueError("Color value must be between 0x000000 and 0xFFFFFF")
+
+    @classmethod
+    def from_rgb(cls, r: int, g: int, b: int) -> "Color":
+        """Create a Color from red, green and blue components."""
+        if not all(0 <= c <= 255 for c in (r, g, b)):
+            raise ValueError("RGB components must be between 0 and 255")
+        return cls((r << 16) + (g << 8) + b)
+
+    @classmethod
+    def from_hex(cls, value: str) -> "Color":
+        """Create a Color from a hex string like ``"#ff0000"``."""
+        value = value.lstrip("#")
+        if len(value) != 6:
+            raise ValueError("Hex string must be in RRGGBB format")
+        return cls(int(value, 16))
+
+    @classmethod
+    def default(cls) -> "Color":
+        return cls(0)
+
+    @classmethod
+    def red(cls) -> "Color":
+        return cls(0xFF0000)
+
+    @classmethod
+    def green(cls) -> "Color":
+        return cls(0x00FF00)
+
+    @classmethod
+    def blue(cls) -> "Color":
+        return cls(0x0000FF)
+
+    def to_rgb(self) -> tuple[int, int, int]:
+        return ((self.value >> 16) & 0xFF, (self.value >> 8) & 0xFF, self.value & 0xFF)
+
+    @classmethod
+    def parse(cls, value: "Color | int | str | tuple[int, int, int] | None") -> "Color | None":
+        """Convert ``value`` to a :class:`Color` instance.
+
+        Parameters
+        ----------
+        value:
+            The value to convert. May be ``None``, an existing ``Color``, an
+            integer in the ``0xRRGGBB`` format, or a hex string like ``"#RRGGBB"``.
+
+        Returns
+        -------
+        Optional[Color]
+            A ``Color`` object if ``value`` is not ``None``.
+        """
+
+        if value is None:
+            return None
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, int):
+            return cls(value)
+        if isinstance(value, str):
+            return cls.from_hex(value)
+        if isinstance(value, tuple) and len(value) == 3:
+            return cls.from_rgb(*value)
+        raise TypeError("Color value must be Color, int, str, tuple, or None")

disagreement/components.py

@@ -18,7 +18,7 @@ from .models import (
     Thumbnail,
     MediaGallery,
     MediaGalleryItem,
-    File,
+    FileComponent,
     Separator,
     Container,
     UnfurledMediaItem,
@@ -140,7 +140,7 @@ def component_factory(
         )
 
     if ctype == ComponentType.FILE:
-        return File(
+        return FileComponent(
             file=UnfurledMediaItem(**data["file"]),
             spoiler=data.get("spoiler", False),
             id=data.get("id"),

disagreement/enums.py

@@ -49,6 +49,11 @@ class GatewayIntent(IntEnum):
     AUTO_MODERATION_CONFIGURATION = 1 << 20
     AUTO_MODERATION_EXECUTION = 1 << 21
 
+    @classmethod
+    def none(cls) -> int:
+        """Return a bitmask representing no intents."""
+        return 0
+
     @classmethod
     def default(cls) -> int:
         """Returns default intents (excluding privileged ones like members, presences, message content)."""

disagreement/errors.py

@@ -77,14 +77,19 @@ class RateLimitError(HTTPException):
         )
 
 
-# You can add more specific exceptions as needed, e.g.:
-# class NotFound(HTTPException):
-#     """Raised for 404 Not Found errors."""
-#     pass
-
-# class Forbidden(HTTPException):
-#     """Raised for 403 Forbidden errors."""
-#     pass
+# Specific HTTP error exceptions
+
+
+class NotFound(HTTPException):
+    """Raised for 404 Not Found errors."""
+
+    pass
+
+
+class Forbidden(HTTPException):
+    """Raised for 403 Forbidden errors."""
+
+    pass
 
 
 class AppCommandError(DisagreementException):