disagreement 0.0.1__py3-none-any.whl

disagreement/oauth.py

@@ -0,0 +1,109 @@
+"""OAuth2 utilities."""
+
+from __future__ import annotations
+
+import aiohttp
+from typing import List, Optional, Dict, Any, Union
+from urllib.parse import urlencode
+
+from .errors import HTTPException
+
+
+def build_authorization_url(
+    client_id: str,
+    redirect_uri: str,
+    scope: Union[str, List[str]],
+    *,
+    state: Optional[str] = None,
+    response_type: str = "code",
+    prompt: Optional[str] = None,
+) -> str:
+    """Return the Discord OAuth2 authorization URL."""
+    if isinstance(scope, list):
+        scope = " ".join(scope)
+
+    params = {
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "response_type": response_type,
+        "scope": scope,
+    }
+    if state is not None:
+        params["state"] = state
+    if prompt is not None:
+        params["prompt"] = prompt
+
+    return "https://discord.com/oauth2/authorize?" + urlencode(params)
+
+
+async def exchange_code_for_token(
+    client_id: str,
+    client_secret: str,
+    code: str,
+    redirect_uri: str,
+    *,
+    session: Optional[aiohttp.ClientSession] = None,
+) -> Dict[str, Any]:
+    """Exchange an authorization code for an access token."""
+    close = False
+    if session is None:
+        session = aiohttp.ClientSession()
+        close = True
+
+    data = {
+        "client_id": client_id,
+        "client_secret": client_secret,
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": redirect_uri,
+    }
+
+    resp = await session.post(
+        "https://discord.com/api/v10/oauth2/token",
+        data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+    try:
+        json_data = await resp.json()
+        if resp.status != 200:
+            raise HTTPException(resp, message="OAuth token exchange failed")
+    finally:
+        if close:
+            await session.close()
+    return json_data
+
+
+async def refresh_access_token(
+    refresh_token: str,
+    client_id: str,
+    client_secret: str,
+    *,
+    session: Optional[aiohttp.ClientSession] = None,
+) -> Dict[str, Any]:
+    """Refresh an access token using a refresh token."""
+
+    close = False
+    if session is None:
+        session = aiohttp.ClientSession()
+        close = True
+
+    data = {
+        "client_id": client_id,
+        "client_secret": client_secret,
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+    }
+
+    resp = await session.post(
+        "https://discord.com/api/v10/oauth2/token",
+        data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+    try:
+        json_data = await resp.json()
+        if resp.status != 200:
+            raise HTTPException(resp, message="OAuth token refresh failed")
+    finally:
+        if close:
+            await session.close()
+    return json_data

disagreement/permissions.py

@@ -0,0 +1,99 @@
+"""Utility helpers for working with Discord permission bitmasks."""
+
+from __future__ import annotations
+
+from enum import IntFlag
+from typing import Iterable, List
+
+
+class Permissions(IntFlag):
+    """Discord guild and channel permissions."""
+
+    CREATE_INSTANT_INVITE = 1 << 0
+    KICK_MEMBERS = 1 << 1
+    BAN_MEMBERS = 1 << 2
+    ADMINISTRATOR = 1 << 3
+    MANAGE_CHANNELS = 1 << 4
+    MANAGE_GUILD = 1 << 5
+    ADD_REACTIONS = 1 << 6
+    VIEW_AUDIT_LOG = 1 << 7
+    PRIORITY_SPEAKER = 1 << 8
+    STREAM = 1 << 9
+    VIEW_CHANNEL = 1 << 10
+    SEND_MESSAGES = 1 << 11
+    SEND_TTS_MESSAGES = 1 << 12
+    MANAGE_MESSAGES = 1 << 13
+    EMBED_LINKS = 1 << 14
+    ATTACH_FILES = 1 << 15
+    READ_MESSAGE_HISTORY = 1 << 16
+    MENTION_EVERYONE = 1 << 17
+    USE_EXTERNAL_EMOJIS = 1 << 18
+    VIEW_GUILD_INSIGHTS = 1 << 19
+    CONNECT = 1 << 20
+    SPEAK = 1 << 21
+    MUTE_MEMBERS = 1 << 22
+    DEAFEN_MEMBERS = 1 << 23
+    MOVE_MEMBERS = 1 << 24
+    USE_VAD = 1 << 25
+    CHANGE_NICKNAME = 1 << 26
+    MANAGE_NICKNAMES = 1 << 27
+    MANAGE_ROLES = 1 << 28
+    MANAGE_WEBHOOKS = 1 << 29
+    MANAGE_GUILD_EXPRESSIONS = 1 << 30
+    USE_APPLICATION_COMMANDS = 1 << 31
+    REQUEST_TO_SPEAK = 1 << 32
+    MANAGE_EVENTS = 1 << 33
+    MANAGE_THREADS = 1 << 34
+    CREATE_PUBLIC_THREADS = 1 << 35
+    CREATE_PRIVATE_THREADS = 1 << 36
+    USE_EXTERNAL_STICKERS = 1 << 37
+    SEND_MESSAGES_IN_THREADS = 1 << 38
+    USE_EMBEDDED_ACTIVITIES = 1 << 39
+    MODERATE_MEMBERS = 1 << 40
+    VIEW_CREATOR_MONETIZATION_ANALYTICS = 1 << 41
+    USE_SOUNDBOARD = 1 << 42
+    CREATE_GUILD_EXPRESSIONS = 1 << 43
+    CREATE_EVENTS = 1 << 44
+    USE_EXTERNAL_SOUNDS = 1 << 45
+    SEND_VOICE_MESSAGES = 1 << 46
+
+
+def permissions_value(*perms: Permissions | int | Iterable[Permissions | int]) -> int:
+    """Return a combined integer value for multiple permissions."""
+
+    value = 0
+    for perm in perms:
+        if isinstance(perm, Iterable) and not isinstance(perm, (Permissions, int)):
+            value |= permissions_value(*perm)
+        else:
+            value |= int(perm)
+    return value
+
+
+def has_permissions(
+    current: int | str | Permissions,
+    *perms: Permissions | int | Iterable[Permissions | int],
+) -> bool:
+    """Return ``True`` if ``current`` includes all ``perms``."""
+
+    current_val = int(current)
+    needed = permissions_value(*perms)
+    return (current_val & needed) == needed
+
+
+def missing_permissions(
+    current: int | str | Permissions,
+    *perms: Permissions | int | Iterable[Permissions | int],
+) -> List[Permissions]:
+    """Return the subset of ``perms`` not present in ``current``."""
+
+    current_val = int(current)
+    missing: List[Permissions] = []
+    for perm in perms:
+        if isinstance(perm, Iterable) and not isinstance(perm, (Permissions, int)):
+            missing.extend(missing_permissions(current_val, *perm))
+        else:
+            perm_val = int(perm)
+            if not current_val & perm_val:
+                missing.append(Permissions(perm_val))
+    return missing

disagreement/rate_limiter.py

@@ -0,0 +1,75 @@
+"""Asynchronous rate limiter for Discord HTTP requests."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Dict, Mapping
+
+
+class _Bucket:
+    def __init__(self) -> None:
+        self.remaining: int = 1
+        self.reset_at: float = 0.0
+        self.lock = asyncio.Lock()
+
+
+class RateLimiter:
+    """Rate limiter implementing per-route buckets and a global queue."""
+
+    def __init__(self) -> None:
+        self._buckets: Dict[str, _Bucket] = {}
+        self._global_event = asyncio.Event()
+        self._global_event.set()
+
+    def _get_bucket(self, route: str) -> _Bucket:
+        bucket = self._buckets.get(route)
+        if bucket is None:
+            bucket = _Bucket()
+            self._buckets[route] = bucket
+        return bucket
+
+    async def acquire(self, route: str) -> _Bucket:
+        bucket = self._get_bucket(route)
+        while True:
+            await self._global_event.wait()
+            async with bucket.lock:
+                now = time.monotonic()
+                if bucket.remaining <= 0 and now < bucket.reset_at:
+                    await asyncio.sleep(bucket.reset_at - now)
+                    continue
+                if bucket.remaining > 0:
+                    bucket.remaining -= 1
+                return bucket
+
+    def release(self, route: str, headers: Mapping[str, str]) -> None:
+        bucket = self._get_bucket(route)
+        try:
+            remaining = int(headers.get("X-RateLimit-Remaining", bucket.remaining))
+            reset_after = float(headers.get("X-RateLimit-Reset-After", "0"))
+            bucket.remaining = remaining
+            bucket.reset_at = time.monotonic() + reset_after
+        except ValueError:
+            pass
+
+        if headers.get("X-RateLimit-Global", "false").lower() == "true":
+            retry_after = float(headers.get("Retry-After", "0"))
+            self._global_event.clear()
+            asyncio.create_task(self._lift_global(retry_after))
+
+    async def handle_rate_limit(
+        self, route: str, retry_after: float, is_global: bool
+    ) -> None:
+        bucket = self._get_bucket(route)
+        bucket.remaining = 0
+        bucket.reset_at = time.monotonic() + retry_after
+        if is_global:
+            self._global_event.clear()
+            await asyncio.sleep(retry_after)
+            self._global_event.set()
+        else:
+            await asyncio.sleep(retry_after)
+
+    async def _lift_global(self, delay: float) -> None:
+        await asyncio.sleep(delay)
+        self._global_event.set()

disagreement/shard_manager.py

@@ -0,0 +1,65 @@
+# disagreement/shard_manager.py
+
+"""Sharding utilities for managing multiple gateway connections."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import List, TYPE_CHECKING
+
+from .gateway import GatewayClient
+
+if TYPE_CHECKING:  # pragma: no cover - for type checking only
+    from .client import Client
+
+
+class Shard:
+    """Represents a single gateway shard."""
+
+    def __init__(self, shard_id: int, shard_count: int, gateway: GatewayClient) -> None:
+        self.id: int = shard_id
+        self.count: int = shard_count
+        self.gateway: GatewayClient = gateway
+
+    async def connect(self) -> None:
+        """Connects this shard's gateway."""
+        await self.gateway.connect()
+
+    async def close(self) -> None:
+        """Closes this shard's gateway."""
+        await self.gateway.close()
+
+
+class ShardManager:
+    """Manages multiple :class:`Shard` instances."""
+
+    def __init__(self, client: "Client", shard_count: int) -> None:
+        self.client: "Client" = client
+        self.shard_count: int = shard_count
+        self.shards: List[Shard] = []
+
+    def _create_shards(self) -> None:
+        if self.shards:
+            return
+        for shard_id in range(self.shard_count):
+            gateway = GatewayClient(
+                http_client=self.client._http,
+                event_dispatcher=self.client._event_dispatcher,
+                token=self.client.token,
+                intents=self.client.intents,
+                client_instance=self.client,
+                verbose=self.client.verbose,
+                shard_id=shard_id,
+                shard_count=self.shard_count,
+            )
+            self.shards.append(Shard(shard_id, self.shard_count, gateway))
+
+    async def start(self) -> None:
+        """Starts all shards."""
+        self._create_shards()
+        await asyncio.gather(*(s.connect() for s in self.shards))
+
+    async def close(self) -> None:
+        """Closes all shards."""
+        await asyncio.gather(*(s.close() for s in self.shards))
+        self.shards.clear()

disagreement/typing.py

@@ -0,0 +1,42 @@
+import asyncio
+from contextlib import suppress
+from typing import Optional, TYPE_CHECKING
+
+from .errors import DisagreementException
+
+if TYPE_CHECKING:
+    from .client import Client
+
+if __name__ == "typing":
+    # For direct module execution testing
+    pass
+
+
+class Typing:
+    """Async context manager for Discord typing indicator."""
+
+    def __init__(self, client: "Client", channel_id: str) -> None:
+        self._client = client
+        self._channel_id = channel_id
+        self._task: Optional[asyncio.Task] = None
+
+    async def _run(self) -> None:
+        try:
+            while True:
+                await self._client._http.trigger_typing(self._channel_id)
+                await asyncio.sleep(5)
+        except asyncio.CancelledError:
+            pass
+
+    async def __aenter__(self) -> "Typing":
+        if self._client._closed:
+            raise DisagreementException("Client is closed.")
+        await self._client._http.trigger_typing(self._channel_id)
+        self._task = asyncio.create_task(self._run())
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        if self._task:
+            self._task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._task

disagreement/ui/__init__.py

@@ -0,0 +1,17 @@
+from .view import View
+from .item import Item
+from .button import Button, button
+from .select import Select, select
+from .modal import Modal, TextInput, text_input
+
+__all__ = [
+    "View",
+    "Item",
+    "Button",
+    "button",
+    "Select",
+    "select",
+    "Modal",
+    "TextInput",
+    "text_input",
+]

disagreement/ui/button.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable, Coroutine, Optional, TYPE_CHECKING
+
+from .item import Item
+from ..enums import ComponentType, ButtonStyle
+from ..models import PartialEmoji, to_partial_emoji
+
+if TYPE_CHECKING:
+    from ..interactions import Interaction
+
+
+class Button(Item):
+    """Represents a button component in a View.
+
+    Args:
+        style (ButtonStyle): The style of the button.
+        label (Optional[str]): The text that appears on the button.
+        emoji (Optional[str | PartialEmoji]): The emoji that appears on the button.
+        custom_id (Optional[str]): The developer-defined identifier for the button.
+        url (Optional[str]): The URL for the button.
+        disabled (bool): Whether the button is disabled.
+        row (Optional[int]): The row the button should be placed in, from 0 to 4.
+    """
+
+    def __init__(
+        self,
+        *,
+        style: ButtonStyle = ButtonStyle.SECONDARY,
+        label: Optional[str] = None,
+        emoji: Optional[str | PartialEmoji] = None,
+        custom_id: Optional[str] = None,
+        url: Optional[str] = None,
+        disabled: bool = False,
+        row: Optional[int] = None,
+    ):
+        super().__init__(type=ComponentType.BUTTON)
+        if not label and not emoji:
+            raise ValueError("A button must have a label and/or an emoji.")
+
+        if url and custom_id:
+            raise ValueError("A button cannot have both a URL and a custom_id.")
+
+        self.style = style
+        self.label = label
+        self.emoji = to_partial_emoji(emoji)
+        self.custom_id = custom_id
+        self.url = url
+        self.disabled = disabled
+        self._row = row
+
+    def to_dict(self) -> dict[str, Any]:
+        """Converts the button to a dictionary that can be sent to Discord."""
+        payload = {
+            "type": ComponentType.BUTTON.value,
+            "style": self.style.value,
+            "disabled": self.disabled,
+        }
+        if self.label:
+            payload["label"] = self.label
+        if self.emoji:
+            payload["emoji"] = self.emoji.to_dict()
+        if self.url:
+            payload["url"] = self.url
+        if self.custom_id:
+            payload["custom_id"] = self.custom_id
+        return payload
+
+
+def button(
+    *,
+    label: Optional[str] = None,
+    custom_id: Optional[str] = None,
+    style: ButtonStyle = ButtonStyle.SECONDARY,
+    emoji: Optional[str | PartialEmoji] = None,
+    url: Optional[str] = None,
+    disabled: bool = False,
+    row: Optional[int] = None,
+) -> Callable[[Callable[..., Coroutine[Any, Any, Any]]], Button]:
+    """A decorator to create a button in a View."""
+
+    def decorator(func: Callable[..., Coroutine[Any, Any, Any]]) -> Button:
+        if not asyncio.iscoroutinefunction(func):
+            raise TypeError("Button callback must be a coroutine function.")
+
+        item = Button(
+            label=label,
+            custom_id=custom_id,
+            style=style,
+            emoji=emoji,
+            url=url,
+            disabled=disabled,
+            row=row,
+        )
+        item.callback = func
+        return item
+
+    return decorator

disagreement/ui/item.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Coroutine, Optional, TYPE_CHECKING
+
+from ..models import Component
+
+if TYPE_CHECKING:
+    from .view import View
+    from ..interactions import Interaction
+
+
+class Item(Component):
+    """Represents a UI item that can be placed in a View.
+
+    This is a base class and is not meant to be used directly.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._view: Optional[View] = None
+        self._row: Optional[int] = None
+        # This is the callback associated with this item.
+        self.callback: Optional[
+            Callable[["View", Interaction], Coroutine[Any, Any, Any]]
+        ] = None
+
+    @property
+    def view(self) -> Optional[View]:
+        return self._view
+
+    @property
+    def row(self) -> Optional[int]:
+        return self._row
+
+    def _refresh_from_data(self, data: dict[str, Any]) -> None:
+        # This is used to update the item's state from incoming interaction data.
+        # For example, a button's disabled state could be updated here.
+        pass

disagreement/ui/modal.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Coroutine, Optional, List, TYPE_CHECKING
+import asyncio
+
+from .item import Item
+from .view import View
+from ..enums import ComponentType, TextInputStyle
+from ..models import ActionRow
+
+if TYPE_CHECKING:  # pragma: no cover - for type hints only
+    from ..interactions import Interaction
+
+
+class TextInput(Item):
+    """Represents a text input component inside a modal."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        custom_id: Optional[str] = None,
+        style: TextInputStyle = TextInputStyle.SHORT,
+        placeholder: Optional[str] = None,
+        required: bool = True,
+        min_length: Optional[int] = None,
+        max_length: Optional[int] = None,
+        row: Optional[int] = None,
+    ) -> None:
+        super().__init__(type=ComponentType.TEXT_INPUT)
+        self.label = label
+        self.custom_id = custom_id
+        self.style = style
+        self.placeholder = placeholder
+        self.required = required
+        self.min_length = min_length
+        self.max_length = max_length
+        self._row = row
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "type": ComponentType.TEXT_INPUT.value,
+            "style": self.style.value,
+            "label": self.label,
+            "required": self.required,
+        }
+        if self.custom_id:
+            payload["custom_id"] = self.custom_id
+        if self.placeholder:
+            payload["placeholder"] = self.placeholder
+        if self.min_length is not None:
+            payload["min_length"] = self.min_length
+        if self.max_length is not None:
+            payload["max_length"] = self.max_length
+        return payload
+
+
+def text_input(
+    *,
+    label: str,
+    custom_id: Optional[str] = None,
+    style: TextInputStyle = TextInputStyle.SHORT,
+    placeholder: Optional[str] = None,
+    required: bool = True,
+    min_length: Optional[int] = None,
+    max_length: Optional[int] = None,
+    row: Optional[int] = None,
+) -> Callable[[Callable[..., Coroutine[Any, Any, Any]]], TextInput]:
+    """Decorator to define a text input callback inside a :class:`Modal`."""
+
+    def decorator(func: Callable[..., Coroutine[Any, Any, Any]]) -> TextInput:
+        if not asyncio.iscoroutinefunction(func):
+            raise TypeError("TextInput callback must be a coroutine function.")
+
+        item = TextInput(
+            label=label,
+            custom_id=custom_id,
+            style=style,
+            placeholder=placeholder,
+            required=required,
+            min_length=min_length,
+            max_length=max_length,
+            row=row,
+        )
+        item.callback = func
+        return item
+
+    return decorator
+
+
+class Modal:
+    """Represents a modal dialog."""
+
+    def __init__(self, *, title: str, custom_id: str) -> None:
+        self.title = title
+        self.custom_id = custom_id
+        self._children: List[TextInput] = []
+
+        for item in self.__class__.__dict__.values():
+            if isinstance(item, TextInput):
+                self.add_item(item)
+
+    @property
+    def children(self) -> List[TextInput]:
+        return self._children
+
+    def add_item(self, item: TextInput) -> None:
+        if not isinstance(item, TextInput):
+            raise TypeError("Only TextInput items can be added to a Modal.")
+        if len(self._children) >= 5:
+            raise ValueError("A modal can only have up to 5 text inputs.")
+        item._view = None  # Not part of a view but reuse item base
+        self._children.append(item)
+
+    def to_components(self) -> List[ActionRow]:
+        rows: List[ActionRow] = []
+        for child in self.children:
+            row = ActionRow(components=[child])
+            rows.append(row)
+        return rows
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "custom_id": self.custom_id,
+            "components": [r.to_dict() for r in self.to_components()],
+        }
+
+    async def callback(
+        self, interaction: Interaction
+    ) -> None:  # pragma: no cover - default
+        pass