disagreement 0.0.1__py3-none-any.whl

disagreement/ui/select.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable, Coroutine, List, Optional, TYPE_CHECKING
+
+from .item import Item
+from ..enums import ComponentType
+from ..models import SelectOption
+
+if TYPE_CHECKING:
+    from ..interactions import Interaction
+
+
+class Select(Item):
+    """Represents a select menu component in a View.
+
+    Args:
+        custom_id (str): The developer-defined identifier for the select menu.
+        options (List[SelectOption]): The choices in the select menu.
+        placeholder (Optional[str]): The placeholder text that is shown if nothing is selected.
+        min_values (int): The minimum number of items that must be chosen.
+        max_values (int): The maximum number of items that can be chosen.
+        disabled (bool): Whether the select menu is disabled.
+        row (Optional[int]): The row the select menu should be placed in, from 0 to 4.
+    """
+
+    def __init__(
+        self,
+        *,
+        custom_id: str,
+        options: List[SelectOption],
+        placeholder: Optional[str] = None,
+        min_values: int = 1,
+        max_values: int = 1,
+        disabled: bool = False,
+        row: Optional[int] = None,
+    ):
+        super().__init__(type=ComponentType.STRING_SELECT)
+        self.custom_id = custom_id
+        self.options = options
+        self.placeholder = placeholder
+        self.min_values = min_values
+        self.max_values = max_values
+        self.disabled = disabled
+        self._row = row
+
+    def to_dict(self) -> dict[str, Any]:
+        """Converts the select menu to a dictionary that can be sent to Discord."""
+        payload = {
+            "type": ComponentType.STRING_SELECT.value,
+            "custom_id": self.custom_id,
+            "options": [option.to_dict() for option in self.options],
+            "disabled": self.disabled,
+        }
+        if self.placeholder:
+            payload["placeholder"] = self.placeholder
+        if self.min_values is not None:
+            payload["min_values"] = self.min_values
+        if self.max_values is not None:
+            payload["max_values"] = self.max_values
+        return payload
+
+
+def select(
+    *,
+    custom_id: str,
+    options: List[SelectOption],
+    placeholder: Optional[str] = None,
+    min_values: int = 1,
+    max_values: int = 1,
+    disabled: bool = False,
+    row: Optional[int] = None,
+) -> Callable[[Callable[..., Coroutine[Any, Any, Any]]], Select]:
+    """A decorator to create a select menu in a View."""
+
+    def decorator(func: Callable[..., Coroutine[Any, Any, Any]]) -> Select:
+        if not asyncio.iscoroutinefunction(func):
+            raise TypeError("Select callback must be a coroutine function.")
+
+        item = Select(
+            custom_id=custom_id,
+            options=options,
+            placeholder=placeholder,
+            min_values=min_values,
+            max_values=max_values,
+            disabled=disabled,
+            row=row,
+        )
+        item.callback = func
+        return item
+
+    return decorator

disagreement/ui/view.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import asyncio
+import uuid
+from typing import Any, Callable, Coroutine, Dict, List, Optional, TYPE_CHECKING
+
+from ..models import ActionRow
+from .item import Item
+
+if TYPE_CHECKING:
+    from ..client import Client
+    from ..interactions import Interaction
+
+
+class View:
+    """Represents a container for UI components that can be sent with a message.
+
+    Args:
+        timeout (Optional[float]): The number of seconds to wait for an interaction before the view times out.
+                                   Defaults to 180.
+    """
+
+    def __init__(self, *, timeout: Optional[float] = 180.0):
+        self.timeout = timeout
+        self.id = str(uuid.uuid4())
+        self.__children: List[Item] = []
+        self.__stopped = asyncio.Event()
+        self._client: Optional[Client] = None
+        self._message_id: Optional[str] = None
+
+        for item in self.__class__.__dict__.values():
+            if isinstance(item, Item):
+                self.add_item(item)
+
+    @property
+    def children(self) -> List[Item]:
+        return self.__children
+
+    def add_item(self, item: Item):
+        """Adds an item to the view."""
+        if not isinstance(item, Item):
+            raise TypeError("Only instances of 'Item' can be added to a View.")
+
+        if len(self.__children) >= 25:
+            raise ValueError("A view can only have a maximum of 25 components.")
+
+        item._view = self
+        self.__children.append(item)
+
+    @property
+    def message_id(self) -> Optional[str]:
+        return self._message_id
+
+    @message_id.setter
+    def message_id(self, value: str):
+        self._message_id = value
+
+    def to_components(self) -> List[ActionRow]:
+        """Converts the view's children into a list of ActionRow components.
+
+        This retains the original, simple layout behaviour where each item is
+        placed in its own :class:`ActionRow` to ensure backward compatibility.
+        """
+
+        rows: List[ActionRow] = []
+
+        for item in self.children:
+            if item.custom_id is None:
+                item.custom_id = (
+                    f"{self.id}:{item.__class__.__name__}:{len(self.__children)}"
+                )
+
+            rows.append(ActionRow(components=[item]))
+
+        return rows
+
+    def layout_components_advanced(self) -> List[ActionRow]:
+        """Group compatible components into rows following Discord rules."""
+
+        rows: List[ActionRow] = []
+
+        for item in self.children:
+            if item.custom_id is None:
+                item.custom_id = (
+                    f"{self.id}:{item.__class__.__name__}:{len(self.__children)}"
+                )
+
+            target_row = item.row
+            if target_row is not None:
+                if not 0 <= target_row <= 4:
+                    raise ValueError("Row index must be between 0 and 4.")
+
+                while len(rows) <= target_row:
+                    if len(rows) >= 5:
+                        raise ValueError("A view can have at most 5 action rows.")
+                    rows.append(ActionRow())
+
+                rows[target_row].add_component(item)
+                continue
+
+            placed = False
+            for row in rows:
+                try:
+                    row.add_component(item)
+                    placed = True
+                    break
+                except ValueError:
+                    continue
+
+            if not placed:
+                if len(rows) >= 5:
+                    raise ValueError("A view can have at most 5 action rows.")
+                new_row = ActionRow([item])
+                rows.append(new_row)
+
+        return rows
+
+    def to_components_payload(self) -> List[Dict[str, Any]]:
+        """Converts the view's children into a list of component dictionaries
+        that can be sent to the Discord API."""
+        return [row.to_dict() for row in self.to_components()]
+
+    async def _dispatch(self, interaction: Interaction):
+        """Called by the client to dispatch an interaction to the correct item."""
+        if self.timeout is not None:
+            self.__stopped.set()  # Reset the timeout on each interaction
+            self.__stopped.clear()
+
+        if interaction.data:
+            custom_id = interaction.data.custom_id
+            for child in self.children:
+                if child.custom_id == custom_id:
+                    if child.callback:
+                        await child.callback(self, interaction)
+                    break
+
+    async def wait(self) -> bool:
+        """Waits until the view has stopped interacting."""
+        return await self.__stopped.wait()
+
+    def stop(self):
+        """Stops the view from listening to interactions."""
+        if not self.__stopped.is_set():
+            self.__stopped.set()
+
+    async def on_timeout(self):
+        """Called when the view times out."""
+        pass  # User can override this
+
+    async def _start(self, client: Client):
+        """Starts the view's internal listener."""
+        self._client = client
+        if self.timeout is not None:
+            asyncio.create_task(self._timeout_task())
+
+    async def _timeout_task(self):
+        """The task that waits for the timeout and then stops the view."""
+        try:
+            await asyncio.wait_for(self.wait(), timeout=self.timeout)
+        except asyncio.TimeoutError:
+            self.stop()
+            await self.on_timeout()
+            if self._client and self._message_id:
+                # Remove the view from the client's listeners
+                self._client._views.pop(self._message_id, None)

disagreement/voice_client.py

@@ -0,0 +1,120 @@
+# disagreement/voice_client.py
+"""Voice gateway and UDP audio client."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import socket
+from typing import Optional, Sequence
+
+import aiohttp
+
+
+class VoiceClient:
+    """Handles the Discord voice WebSocket connection and UDP streaming."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        session_id: str,
+        token: str,
+        guild_id: int,
+        user_id: int,
+        *,
+        ws=None,
+        udp: Optional[socket.socket] = None,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+        verbose: bool = False,
+    ) -> None:
+        self.endpoint = endpoint
+        self.session_id = session_id
+        self.token = token
+        self.guild_id = str(guild_id)
+        self.user_id = str(user_id)
+        self._ws: Optional[aiohttp.ClientWebSocketResponse] = ws
+        self._udp = udp
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._heartbeat_task: Optional[asyncio.Task] = None
+        self._heartbeat_interval: Optional[float] = None
+        self._loop = loop or asyncio.get_event_loop()
+        self.verbose = verbose
+        self.ssrc: Optional[int] = None
+        self.secret_key: Optional[Sequence[int]] = None
+        self._server_ip: Optional[str] = None
+        self._server_port: Optional[int] = None
+
+    async def connect(self) -> None:
+        if self._ws is None:
+            self._session = aiohttp.ClientSession()
+            self._ws = await self._session.ws_connect(self.endpoint)
+
+        hello = await self._ws.receive_json()
+        self._heartbeat_interval = hello["d"]["heartbeat_interval"] / 1000
+        self._heartbeat_task = self._loop.create_task(self._heartbeat())
+
+        await self._ws.send_json(
+            {
+                "op": 0,
+                "d": {
+                    "server_id": self.guild_id,
+                    "user_id": self.user_id,
+                    "session_id": self.session_id,
+                    "token": self.token,
+                },
+            }
+        )
+
+        ready = await self._ws.receive_json()
+        data = ready["d"]
+        self.ssrc = data["ssrc"]
+        self._server_ip = data["ip"]
+        self._server_port = data["port"]
+
+        if self._udp is None:
+            self._udp = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self._udp.connect((self._server_ip, self._server_port))
+
+        await self._ws.send_json(
+            {
+                "op": 1,
+                "d": {
+                    "protocol": "udp",
+                    "data": {
+                        "address": self._udp.getsockname()[0],
+                        "port": self._udp.getsockname()[1],
+                        "mode": "xsalsa20_poly1305",
+                    },
+                },
+            }
+        )
+
+        session_desc = await self._ws.receive_json()
+        self.secret_key = session_desc["d"].get("secret_key")
+
+    async def _heartbeat(self) -> None:
+        assert self._ws is not None
+        assert self._heartbeat_interval is not None
+        try:
+            while True:
+                await self._ws.send_json({"op": 3, "d": int(self._loop.time() * 1000)})
+                await asyncio.sleep(self._heartbeat_interval)
+        except asyncio.CancelledError:
+            pass
+
+    async def send_audio_frame(self, frame: bytes) -> None:
+        if not self._udp:
+            raise RuntimeError("UDP socket not initialised")
+        self._udp.send(frame)
+
+    async def close(self) -> None:
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._heartbeat_task
+        if self._ws:
+            await self._ws.close()
+        if self._session:
+            await self._session.close()
+        if self._udp:
+            self._udp.close()

disagreement-0.0.1.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: disagreement
+Version: 0.0.1
+Summary: A Python library for the Discord API.
+Author-email: Slipstream <me@slipstreamm.dev>
+License: BSD 3-Clause
+Project-URL: Homepage, https://github.com/Slipstreamm/disagreement
+Project-URL: Issues, https://github.com/Slipstreamm/disagreement/issues
+Keywords: discord,api,bot,async,aiohttp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4.0.0,>=3.9.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=1.0.0; extra == "test"
+Requires-Dist: hypothesis>=6.89.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: dotenv>=0.0.5; extra == "dev"
+Dynamic: license-file
+
+# Disagreement
+
+A Python library for interacting with the Discord API, with a focus on bot development.
+
+## Features
+
+- Asynchronous design using `aiohttp`
+- Gateway and HTTP API clients
+- Slash command framework
+- Message component helpers
+- Built-in caching layer
+- Experimental voice support
+- Helpful error handling utilities
+
+## Installation
+
+```bash
+python -m pip install -U pip
+pip install disagreement
+# or install from source for development
+pip install -e .
+```
+
+Requires Python 3.11 or newer.
+
+## Basic Usage
+
+```python
+import asyncio
+import os
+import disagreement
+
+# Ensure DISCORD_BOT_TOKEN is set in your environment
+client = disagreement.Client(token=os.environ.get("DISCORD_BOT_TOKEN"))
+
+@client.on_event('MESSAGE_CREATE')
+async def on_message(message: disagreement.Message):
+    print(f"Received: {message.content} from {message.author.username}")
+    if message.content.lower() == '!ping':
+        await message.reply('Pong!')
+
+async def main():
+    if not client.token:
+        print("Error: DISCORD_BOT_TOKEN environment variable not set.")
+        return
+    try:
+        async with client:
+            await asyncio.Future()  # run until cancelled
+    except KeyboardInterrupt:
+        print("Bot shutting down...")
+    # Add any other specific exception handling from your library, e.g., disagreement.AuthenticationError
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+### Global Error Handling
+
+To ensure unexpected errors don't crash your bot, you can enable the library's
+global error handler:
+
+```python
+import disagreement
+
+disagreement.setup_global_error_handler()
+```
+
+Call this early in your program to log unhandled exceptions instead of letting
+them terminate the process.
+
+### Configuring Logging
+
+Use :func:`disagreement.logging_config.setup_logging` to configure logging for
+your bot. The helper accepts a logging level and an optional file path.
+
+```python
+import logging
+from disagreement.logging_config import setup_logging
+
+setup_logging(logging.INFO)
+# Or log to a file
+setup_logging(logging.DEBUG, file="bot.log")
+```
+
+### Defining Subcommands with `AppCommandGroup`
+
+```python
+from disagreement.ext.app_commands import AppCommandGroup
+
+settings = AppCommandGroup("settings", "Manage settings")
+
+@settings.command(name="show")
+async def show(ctx):
+    """Displays a setting."""
+    ...
+
+@settings.group("admin", description="Admin settings")
+def admin_group():
+    pass
+
+@admin_group.command(name="set")
+async def set_setting(ctx, key: str, value: str):
+    ...
+## Fetching Guilds
+
+Use `Client.fetch_guild` to retrieve a guild from the Discord API if it
+isn't already cached. This is useful when working with guild IDs from
+outside the gateway events.
+
+```python
+guild = await client.fetch_guild("123456789012345678")
+roles = await client.fetch_roles(guild.id)
+```
+
+## Sharding
+
+To run your bot across multiple gateway shards, pass `shard_count` when creating
+the client:
+
+```python
+client = disagreement.Client(token=BOT_TOKEN, shard_count=2)
+```
+
+See `examples/sharded_bot.py` for a full example.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+See the [docs](docs/) directory for detailed guides on components, slash commands, caching, and voice features.
+

disagreement-0.0.1.dist-info/RECORD

@@ -0,0 +1,32 @@
+disagreement/__init__.py,sha256=ylGJLwgNmt7B71khVq2O0fG__4kjnkA35rZFX5tEDrk,907
+disagreement/cache.py,sha256=juabGFl4naQih5OUIVN2aN-vAfw2ZC2cI38s4nGEn8U,1525
+disagreement/client.py,sha256=pFXj7z7R1kJWz3_GWOzDYrF1S-nQ1agjcXnRTSh-PWE,45820
+disagreement/components.py,sha256=W_R9iMETkQj6sr-Lzk2n7hLwLNaLWT4vBPArIPHQUNc,5232
+disagreement/enums.py,sha256=LLeXdYKcx4TUhlojNV5X4NDuvscMbnteWRNW79d0C2c,9668
+disagreement/error_handler.py,sha256=c2lb6aTMnhTtITQuR6axZUtEaasYKUgmdSxAHEkeq50,1028
+disagreement/errors.py,sha256=rCr9jVAzK8wsS6mxieeWpffKhTDX--sHuOBz45kwsAA,3215
+disagreement/event_dispatcher.py,sha256=BevGAi72qXAHN_FqCOSdvVhOhINLeI2ojyVLmvrSKJ0,9851
+disagreement/gateway.py,sha256=V46WyZE1duVEvVcBYsaThWd60Xg9T2Qsqu9Y02rQwXo,21315
+disagreement/http.py,sha256=1lHIEq2RRVOzzSpfj9TNGprJsMW_nhbj_8-fPr0IupI,23986
+disagreement/hybrid_context.py,sha256=VYCmcreTZdPBU9v-Cy48W38vgWO2t8nM2ulC6_z4HjU,1095
+disagreement/i18n.py,sha256=1L4rcFuKP0XjHk9dVwbNh4BkLk2ZlxxZ_-tecGWa9S0,718
+disagreement/interactions.py,sha256=corwLVsbWM2JXHk5u8VR_Qp3GINLcKFo2y7dyI53QFA,21645
+disagreement/logging_config.py,sha256=4q6baQPE6X_0lfaBTFMU1uqc03x5SbJqo2hsApdDFac,686
+disagreement/models.py,sha256=TMvGP17h1LK72SlA4vNUId76LdonKAUCTzqeNJRFzVQ,61475
+disagreement/oauth.py,sha256=TfDdCwg1J7osM9wDi61dtNBA5BrQk5DeQrrHsYycH34,2810
+disagreement/permissions.py,sha256=7g5cIlg-evHXOL0-pmtT5EwqcB-stXot1HZSLz724sE,3008
+disagreement/rate_limiter.py,sha256=ubwR_UTPs2MotipBdtqpgwQKx0IHt2I3cdfFcXTFv7g,2521
+disagreement/shard_manager.py,sha256=R0HXruJ0Wda_3ftTztQx7kpI182jyuAMsjU6fDtz8Us,2039
+disagreement/typing.py,sha256=_1oFWfZ4HyH5Q3bnF7CO24s79z-3_B5Qb69kWiwLhhU,1242
+disagreement/voice_client.py,sha256=KdFEH8PI6v45olTYoW_-DVOuTCk8SGg7BgSzxOQsILs,3869
+disagreement/ui/__init__.py,sha256=PLA6eHiq9cu7JDOKS-7MKtaFhlqswjbI4AEUlpnbgO0,307
+disagreement/ui/button.py,sha256=GHbY3-yMrvv6u674-qYONocuC1e2a0flEWjPKwJXKDo,3163
+disagreement/ui/item.py,sha256=bm-EmQEZpe8Kt8JrRw-o0uQdccgjErORcFsBqaXOcV8,1112
+disagreement/ui/modal.py,sha256=FLWFy_VkZ9UAPumX3Q_bT0q7M06O1Q7XzBLhCZyhYhI,4120
+disagreement/ui/select.py,sha256=XjWRlWkA09QZaDDLn-wDDOWIuj0Mb4VCWJEOAaExZXw,3018
+disagreement/ui/view.py,sha256=QhWoYt39QKXwl1X6Mkm5gNNEqd8bt7O505lSpiG0L04,5567
+disagreement-0.0.1.dist-info/licenses/LICENSE,sha256=zfmtgJhVFHnqT7a8LAQFthXu5bP7EEHmEL99trV66Ew,1474
+disagreement-0.0.1.dist-info/METADATA,sha256=r9liBFa4OLtdW91XF2A7yJ7VcaOiBkmRbKVG74NEsHc,4533
+disagreement-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+disagreement-0.0.1.dist-info/top_level.txt,sha256=t7FY_3iaYhdB6X6y9VybJ2j7UZbVeRUe9wRgH8d5Gtk,13
+disagreement-0.0.1.dist-info/RECORD,,

disagreement-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

disagreement-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2025, Slipstream
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

disagreement-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+disagreement