disagreement 0.0.1__py3-none-any.whl → 0.1.0rc1__py3-none-any.whl

disagreement/http.py

@@ -20,7 +20,7 @@ from . import __version__  # For User-Agent
 
 if TYPE_CHECKING:
     from .client import Client
-    from .models import Message
+    from .models import Message, Webhook, File
     from .interactions import ApplicationCommand, InteractionResponsePayload, Snowflake
 
 # Discord API constants
@@ -60,7 +60,9 @@ class HTTPClient:
         self,
         method: str,
         endpoint: str,
-        payload: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None,
+        payload: Optional[
+            Union[Dict[str, Any], List[Dict[str, Any]], aiohttp.FormData]
+        ] = None,
         params: Optional[Dict[str, Any]] = None,
         is_json: bool = True,
         use_auth_header: bool = True,
@@ -204,11 +206,23 @@ class HTTPClient:
         components: Optional[List[Dict[str, Any]]] = None,
         allowed_mentions: Optional[dict] = None,
         message_reference: Optional[Dict[str, Any]] = None,
+        attachments: Optional[List[Any]] = None,
+        files: Optional[List[Any]] = None,
         flags: Optional[int] = None,
     ) -> Dict[str, Any]:
         """Sends a message to a channel.
 
-        Returns the created message data as a dict.
+        Parameters
+        ----------
+        attachments:
+            A list of attachment payloads to include with the message.
+        files:
+            A list of :class:`File` objects containing binary data to upload.
+
+        Returns
+        -------
+        Dict[str, Any]
+            The created message data.
         """
         payload: Dict[str, Any] = {}
         if content is not None:  # Content is optional if embeds/components are present
@@ -221,6 +235,28 @@ class HTTPClient:
             payload["components"] = components
         if allowed_mentions:
             payload["allowed_mentions"] = allowed_mentions
+        all_files: List["File"] = []
+        if attachments is not None:
+            payload["attachments"] = []
+            for a in attachments:
+                if hasattr(a, "data") and hasattr(a, "filename"):
+                    idx = len(all_files)
+                    all_files.append(a)
+                    payload["attachments"].append({"id": idx, "filename": a.filename})
+                else:
+                    payload["attachments"].append(
+                        a.to_dict() if hasattr(a, "to_dict") else a
+                    )
+        if files is not None:
+            for f in files:
+                if hasattr(f, "data") and hasattr(f, "filename"):
+                    idx = len(all_files)
+                    all_files.append(f)
+                    if "attachments" not in payload:
+                        payload["attachments"] = []
+                    payload["attachments"].append({"id": idx, "filename": f.filename})
+                else:
+                    raise TypeError("files must be File objects")
         if flags:
             payload["flags"] = flags
         if message_reference:
@@ -229,6 +265,25 @@ class HTTPClient:
         if not payload:
             raise ValueError("Message must have content, embeds, or components.")
 
+        if all_files:
+            form = aiohttp.FormData()
+            form.add_field(
+                "payload_json", json.dumps(payload), content_type="application/json"
+            )
+            for idx, f in enumerate(all_files):
+                form.add_field(
+                    f"files[{idx}]",
+                    f.data,
+                    filename=f.filename,
+                    content_type="application/octet-stream",
+                )
+            return await self.request(
+                "POST",
+                f"/channels/{channel_id}/messages",
+                payload=form,
+                is_json=False,
+            )
+
         return await self.request(
             "POST", f"/channels/{channel_id}/messages", payload=payload
         )
@@ -256,6 +311,13 @@ class HTTPClient:
             "GET", f"/channels/{channel_id}/messages/{message_id}"
         )
 
+    async def delete_message(
+        self, channel_id: "Snowflake", message_id: "Snowflake"
+    ) -> None:
+        """Deletes a message in a channel."""
+
+        await self.request("DELETE", f"/channels/{channel_id}/messages/{message_id}")
+
     async def create_reaction(
         self, channel_id: "Snowflake", message_id: "Snowflake", emoji: str
     ) -> None:
@@ -286,6 +348,18 @@ class HTTPClient:
             f"/channels/{channel_id}/messages/{message_id}/reactions/{encoded}",
         )
 
+    async def bulk_delete_messages(
+        self, channel_id: "Snowflake", messages: List["Snowflake"]
+    ) -> List["Snowflake"]:
+        """Bulk deletes messages in a channel and returns their IDs."""
+
+        await self.request(
+            "POST",
+            f"/channels/{channel_id}/messages/bulk-delete",
+            payload={"messages": messages},
+        )
+        return messages
+
     async def delete_channel(
         self, channel_id: str, reason: Optional[str] = None
     ) -> None:
@@ -310,6 +384,33 @@ class HTTPClient:
         """Fetches a channel by ID."""
         return await self.request("GET", f"/channels/{channel_id}")
 
+    async def create_webhook(
+        self, channel_id: "Snowflake", payload: Dict[str, Any]
+    ) -> "Webhook":
+        """Creates a webhook in the specified channel."""
+
+        data = await self.request(
+            "POST", f"/channels/{channel_id}/webhooks", payload=payload
+        )
+        from .models import Webhook
+
+        return Webhook(data)
+
+    async def edit_webhook(
+        self, webhook_id: "Snowflake", payload: Dict[str, Any]
+    ) -> "Webhook":
+        """Edits an existing webhook."""
+
+        data = await self.request("PATCH", f"/webhooks/{webhook_id}", payload=payload)
+        from .models import Webhook
+
+        return Webhook(data)
+
+    async def delete_webhook(self, webhook_id: "Snowflake") -> None:
+        """Deletes a webhook."""
+
+        await self.request("DELETE", f"/webhooks/{webhook_id}")
+
     async def get_user(self, user_id: "Snowflake") -> Dict[str, Any]:
         """Fetches a user object for a given user ID."""
         return await self.request("GET", f"/users/{user_id}")

disagreement/models.py

@@ -5,6 +5,9 @@ Data models for Discord objects.
 """
 
 import json
+import asyncio
+import aiohttp  # pylint: disable=import-error
+import asyncio
 from typing import Optional, TYPE_CHECKING, List, Dict, Any, Union
 
 from .errors import DisagreementException, HTTPException
@@ -21,12 +24,14 @@ from .enums import (  # These enums will need to be defined in disagreement/enum
     ButtonStyle,  # Added for Button
     # SelectMenuType will be part of ComponentType or a new enum if needed
 )
+from .permissions import Permissions
 
 
 if TYPE_CHECKING:
     from .client import Client  # For type hinting to avoid circular imports
     from .enums import OverwriteType  # For PermissionOverwrite model
     from .ui.view import View
+    from .interactions import Snowflake
 
     # Forward reference Message if it were used in type hints before its definition
     # from .models import Message # Not needed as Message is defined before its use in TextChannel.send etc.
@@ -72,6 +77,7 @@ class Message:
         timestamp (str): When this message was sent (ISO8601 timestamp).
         components (Optional[List[ActionRow]]): Structured components attached
             to the message if present.
+        attachments (List[Attachment]): Attachments included with the message.
     """
 
     def __init__(self, data: dict, client_instance: "Client"):
@@ -92,6 +98,9 @@ class Message:
             ]
         else:
             self.components = None
+        self.attachments: List[Attachment] = [
+            Attachment(a) for a in data.get("attachments", [])
+        ]
         # Add other fields as needed, e.g., attachments, embeds, reactions, etc.
         # self.mentions: List[User] = [User(u) for u in data.get("mentions", [])]
         # self.mention_roles: List[str] = data.get("mention_roles", [])
@@ -192,6 +201,22 @@ class Message:
             view=view,
         )
 
+    async def delete(self, delay: Optional[float] = None) -> None:
+        """|coro|
+
+        Deletes this message.
+
+        Parameters
+        ----------
+        delay:
+            If provided, wait this many seconds before deleting.
+        """
+
+        if delay is not None:
+            await asyncio.sleep(delay)
+
+        await self._client._http.delete_message(self.channel_id, self.id)
+
     def __repr__(self) -> str:
         return f"<Message id='{self.id}' channel_id='{self.channel_id}' author='{self.author!r}'>"
 
@@ -373,6 +398,14 @@ class Attachment:
         return payload
 
 
+class File:
+    """Represents a file to be uploaded."""
+
+    def __init__(self, filename: str, data: bytes):
+        self.filename = filename
+        self.data = data
+
+
 class AllowedMentions:
     """Represents allowed mentions for a message or interaction response."""
 
@@ -527,6 +560,34 @@ class Member(User):  # Member inherits from User
             reason=reason,
         )
 
+    @property
+    def top_role(self) -> Optional["Role"]:
+        """Return the member's highest role from the guild cache."""
+
+        if not self.guild_id or not self._client:
+            return None
+
+        guild = self._client.get_guild(self.guild_id)
+        if not guild:
+            return None
+
+        if not guild.roles and hasattr(self._client, "fetch_roles"):
+            try:
+                self._client.loop.run_until_complete(
+                    self._client.fetch_roles(self.guild_id)
+                )
+            except RuntimeError:
+                future = asyncio.run_coroutine_threadsafe(
+                    self._client.fetch_roles(self.guild_id), self._client.loop
+                )
+                future.result()
+
+        role_objects = [r for r in guild.roles if r.id in self.roles]
+        if not role_objects:
+            return None
+
+        return max(role_objects, key=lambda r: r.position)
+
 
 class PartialEmoji:
     """Represents a partial emoji, often used in components or reactions.
@@ -853,6 +914,31 @@ class Guild:
     def get_member(self, user_id: str) -> Optional[Member]:
         return self._members.get(user_id)
 
+    def get_member_named(self, name: str) -> Optional[Member]:
+        """Retrieve a cached member by username or nickname.
+
+        The lookup is case-insensitive and searches both the username and
+        guild nickname for a match.
+
+        Parameters
+        ----------
+        name: str
+            The username or nickname to search for.
+
+        Returns
+        -------
+        Optional[Member]
+            The matching member if found, otherwise ``None``.
+        """
+
+        lowered = name.lower()
+        for member in self._members.values():
+            if member.username.lower() == lowered:
+                return member
+            if member.nick and member.nick.lower() == lowered:
+                return member
+        return None
+
     def get_role(self, role_id: str) -> Optional[Role]:
         return next((role for role in self.roles if role.id == role_id), None)
 
@@ -893,6 +979,78 @@ class Channel:
     def __repr__(self) -> str:
         return f"<Channel id='{self.id}' name='{self.name}' type='{self.type.name if hasattr(self.type, 'name') else self._type_val}'>"
 
+    def permission_overwrite_for(
+        self, target: Union["Role", "Member", str]
+    ) -> Optional["PermissionOverwrite"]:
+        """Return the :class:`PermissionOverwrite` for ``target`` if present."""
+
+        if isinstance(target, str):
+            target_id = target
+        else:
+            target_id = target.id
+        for overwrite in self.permission_overwrites:
+            if overwrite.id == target_id:
+                return overwrite
+        return None
+
+    @staticmethod
+    def _apply_overwrite(
+        perms: Permissions, overwrite: Optional["PermissionOverwrite"]
+    ) -> Permissions:
+        if overwrite is None:
+            return perms
+
+        perms &= ~Permissions(int(overwrite.deny))
+        perms |= Permissions(int(overwrite.allow))
+        return perms
+
+    def permissions_for(self, member: "Member") -> Permissions:
+        """Resolve channel permissions for ``member``."""
+
+        if self.guild_id is None:
+            return Permissions(~0)
+
+        if not hasattr(self._client, "get_guild"):
+            return Permissions(0)
+
+        guild = self._client.get_guild(self.guild_id)
+        if guild is None:
+            return Permissions(0)
+
+        base = Permissions(0)
+
+        everyone = guild.get_role(guild.id)
+        if everyone is not None:
+            base |= Permissions(int(everyone.permissions))
+
+        for rid in member.roles:
+            role = guild.get_role(rid)
+            if role is not None:
+                base |= Permissions(int(role.permissions))
+
+        if base & Permissions.ADMINISTRATOR:
+            return Permissions(~0)
+
+        # Apply @everyone overwrite
+        base = self._apply_overwrite(base, self.permission_overwrite_for(guild.id))
+
+        # Role overwrites
+        role_allow = Permissions(0)
+        role_deny = Permissions(0)
+        for rid in member.roles:
+            ow = self.permission_overwrite_for(rid)
+            if ow is not None:
+                role_allow |= Permissions(int(ow.allow))
+                role_deny |= Permissions(int(ow.deny))
+
+        base &= ~role_deny
+        base |= role_allow
+
+        # Member overwrite
+        base = self._apply_overwrite(base, self.permission_overwrite_for(member.id))
+
+        return base
+
 
 class TextChannel(Channel):
     """Represents a guild text channel or announcement channel."""
@@ -928,6 +1086,27 @@ class TextChannel(Channel):
             components=components,
         )
 
+    async def purge(
+        self, limit: int, *, before: "Snowflake | None" = None
+    ) -> List["Snowflake"]:
+        """Bulk delete messages from this channel."""
+
+        params: Dict[str, Union[int, str]] = {"limit": limit}
+        if before is not None:
+            params["before"] = before
+
+        messages = await self._client._http.request(
+            "GET", f"/channels/{self.id}/messages", params=params
+        )
+        ids = [m["id"] for m in messages]
+        if not ids:
+            return []
+
+        await self._client._http.bulk_delete_messages(self.id, ids)
+        for mid in ids:
+            self._client._messages.pop(mid, None)
+        return ids
+
     def __repr__(self) -> str:
         return f"<TextChannel id='{self.id}' name='{self.name}' guild_id='{self.guild_id}'>"
 
@@ -1090,6 +1269,55 @@ class PartialChannel:
         return f"<PartialChannel id='{self.id}' name='{self.name}' type='{type_name}'>"
 
 
+class Webhook:
+    """Represents a Discord Webhook."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ):
+        self._client: Optional["Client"] = client_instance
+        self.id: str = data["id"]
+        self.type: int = int(data.get("type", 1))
+        self.guild_id: Optional[str] = data.get("guild_id")
+        self.channel_id: Optional[str] = data.get("channel_id")
+        self.name: Optional[str] = data.get("name")
+        self.avatar: Optional[str] = data.get("avatar")
+        self.token: Optional[str] = data.get("token")
+        self.application_id: Optional[str] = data.get("application_id")
+        self.url: Optional[str] = data.get("url")
+        self.user: Optional[User] = User(data["user"]) if data.get("user") else None
+
+    def __repr__(self) -> str:
+        return f"<Webhook id='{self.id}' name='{self.name}'>"
+
+    @classmethod
+    def from_url(
+        cls, url: str, session: Optional[aiohttp.ClientSession] = None
+    ) -> "Webhook":
+        """Create a minimal :class:`Webhook` from a webhook URL.
+
+        Parameters
+        ----------
+        url:
+            The full Discord webhook URL.
+        session:
+            Unused for now. Present for API compatibility.
+
+        Returns
+        -------
+        Webhook
+            A webhook instance containing only the ``id``, ``token`` and ``url``.
+        """
+
+        parts = url.rstrip("/").split("/")
+        if len(parts) < 2:
+            raise ValueError("Invalid webhook URL")
+        token = parts[-1]
+        webhook_id = parts[-2]
+
+        return cls({"id": webhook_id, "token": token, "url": url})
+
+
 # --- Message Components ---
 
 
@@ -1433,7 +1661,7 @@ class MediaGallery(Component):
         return payload
 
 
-class File(Component):
+class FileComponent(Component):
     """Represents a file component."""
 
     def __init__(
@@ -1614,6 +1842,85 @@ class TypingStart:
         return f"<TypingStart channel_id='{self.channel_id}' user_id='{self.user_id}'>"
 
 
+class Reaction:
+    """Represents a message reaction event."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ):
+        self._client = client_instance
+        self.user_id: str = data["user_id"]
+        self.channel_id: str = data["channel_id"]
+        self.message_id: str = data["message_id"]
+        self.guild_id: Optional[str] = data.get("guild_id")
+        self.member: Optional[Member] = (
+            Member(data["member"], client_instance) if data.get("member") else None
+        )
+        self.emoji: Dict[str, Any] = data.get("emoji", {})
+
+    def __repr__(self) -> str:
+        emoji_value = self.emoji.get("name") or self.emoji.get("id")
+        return f"<Reaction message_id='{self.message_id}' user_id='{self.user_id}' emoji='{emoji_value}'>"
+
+
+class GuildMemberRemove:
+    """Represents a GUILD_MEMBER_REMOVE event."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ):
+        self._client = client_instance
+        self.guild_id: str = data["guild_id"]
+        self.user: User = User(data["user"])
+
+    def __repr__(self) -> str:
+        return (
+            f"<GuildMemberRemove guild_id='{self.guild_id}' user_id='{self.user.id}'>"
+        )
+
+
+class GuildBanAdd:
+    """Represents a GUILD_BAN_ADD event."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ):
+        self._client = client_instance
+        self.guild_id: str = data["guild_id"]
+        self.user: User = User(data["user"])
+
+    def __repr__(self) -> str:
+        return f"<GuildBanAdd guild_id='{self.guild_id}' user_id='{self.user.id}'>"
+
+
+class GuildBanRemove:
+    """Represents a GUILD_BAN_REMOVE event."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ):
+        self._client = client_instance
+        self.guild_id: str = data["guild_id"]
+        self.user: User = User(data["user"])
+
+    def __repr__(self) -> str:
+        return f"<GuildBanRemove guild_id='{self.guild_id}' user_id='{self.user.id}'>"
+
+
+class GuildRoleUpdate:
+    """Represents a GUILD_ROLE_UPDATE event."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ):
+        self._client = client_instance
+        self.guild_id: str = data["guild_id"]
+        self.role: Role = Role(data["role"])
+
+    def __repr__(self) -> str:
+        return f"<GuildRoleUpdate guild_id='{self.guild_id}' role_id='{self.role.id}'>"
+
+
 def channel_factory(data: Dict[str, Any], client: "Client") -> Channel:
     """Create a channel object from raw API data."""
     channel_type = data.get("type")

disagreement/shard_manager.py

@@ -51,6 +51,8 @@ class ShardManager:
                 verbose=self.client.verbose,
                 shard_id=shard_id,
                 shard_count=self.shard_count,
+                max_retries=self.client.gateway_max_retries,
+                max_backoff=self.client.gateway_max_backoff,
             )
             self.shards.append(Shard(shard_id, self.shard_count, gateway))
 

disagreement/utils.py

@@ -0,0 +1,10 @@
+"""Utility helpers."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def utcnow() -> datetime:
+    """Return the current timezone-aware UTC time."""
+    return datetime.now(timezone.utc)

disagreement/voice_client.py

@@ -10,6 +10,8 @@ from typing import Optional, Sequence
 
 import aiohttp
 
+from .audio import AudioSource, FFmpegAudioSource
+
 
 class VoiceClient:
     """Handles the Discord voice WebSocket connection and UDP streaming."""
@@ -43,6 +45,8 @@ class VoiceClient:
         self.secret_key: Optional[Sequence[int]] = None
         self._server_ip: Optional[str] = None
         self._server_port: Optional[int] = None
+        self._current_source: Optional[AudioSource] = None
+        self._play_task: Optional[asyncio.Task] = None
 
     async def connect(self) -> None:
         if self._ws is None:
@@ -107,7 +111,45 @@ class VoiceClient:
             raise RuntimeError("UDP socket not initialised")
         self._udp.send(frame)
 
+    async def _play_loop(self) -> None:
+        assert self._current_source is not None
+        try:
+            while True:
+                data = await self._current_source.read()
+                if not data:
+                    break
+                await self.send_audio_frame(data)
+        finally:
+            await self._current_source.close()
+            self._current_source = None
+            self._play_task = None
+
+    async def stop(self) -> None:
+        if self._play_task:
+            self._play_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._play_task
+            self._play_task = None
+        if self._current_source:
+            await self._current_source.close()
+            self._current_source = None
+
+    async def play(self, source: AudioSource, *, wait: bool = True) -> None:
+        """|coro| Play an :class:`AudioSource` on the voice connection."""
+
+        await self.stop()
+        self._current_source = source
+        self._play_task = self._loop.create_task(self._play_loop())
+        if wait:
+            await self._play_task
+
+    async def play_file(self, filename: str, *, wait: bool = True) -> None:
+        """|coro| Stream an audio file or URL using FFmpeg."""
+
+        await self.play(FFmpegAudioSource(filename), wait=wait)
+
     async def close(self) -> None:
+        await self.stop()
         if self._heartbeat_task:
             self._heartbeat_task.cancel()
             with contextlib.suppress(asyncio.CancelledError):