disagreement 0.4.0__tar.gz → 0.4.2__tar.gz

{disagreement-0.4.0/disagreement.egg-info → disagreement-0.4.2}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: disagreement
-Version: 0.4.0
+Version: 0.4.2
 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
+Project-URL: Documentation, https://disagreement.xyz/
 Keywords: discord,api,bot,async,aiohttp
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -45,6 +46,7 @@ A Python library for interacting with the Discord API, with a focus on bot devel
 - Gateway and HTTP API clients
 - Slash command framework
 - Message component helpers
+- `Message.jump_url` property for quick links to messages
 - Built-in caching layer
 - Experimental voice support
 - Helpful error handling utilities
@@ -152,9 +154,10 @@ session parameter supported by ``aiohttp``.
 Specify default mention behaviour for all outgoing messages when constructing the client:
 
 ```python
+from disagreement.models import AllowedMentions
 client = disagreement.Client(
     token=token,
-    allowed_mentions={"parse": [], "replied_user": False},
+    allowed_mentions=AllowedMentions.none().to_dict(),
 )
 ```
 
@@ -191,6 +194,14 @@ guild = await client.fetch_guild("123456789012345678")
 roles = await client.fetch_roles(guild.id)
 ```
 
+Call `Client.fetch_guilds` to list all guilds the current user has access to.
+
+```python
+guilds = await client.fetch_guilds()
+for g in guilds:
+    print(g.name)
+```
+
 ## Sharding
 
 To run your bot across multiple gateway shards, pass ``shard_count`` when creating

{disagreement-0.4.0 → disagreement-0.4.2}/README.md

@@ -11,6 +11,7 @@ A Python library for interacting with the Discord API, with a focus on bot devel
 - Gateway and HTTP API clients
 - Slash command framework
 - Message component helpers
+- `Message.jump_url` property for quick links to messages
 - Built-in caching layer
 - Experimental voice support
 - Helpful error handling utilities
@@ -118,9 +119,10 @@ session parameter supported by ``aiohttp``.
 Specify default mention behaviour for all outgoing messages when constructing the client:
 
 ```python
+from disagreement.models import AllowedMentions
 client = disagreement.Client(
     token=token,
-    allowed_mentions={"parse": [], "replied_user": False},
+    allowed_mentions=AllowedMentions.none().to_dict(),
 )
 ```
 
@@ -157,6 +159,14 @@ guild = await client.fetch_guild("123456789012345678")
 roles = await client.fetch_roles(guild.id)
 ```
 
+Call `Client.fetch_guilds` to list all guilds the current user has access to.
+
+```python
+guilds = await client.fetch_guilds()
+for g in guilds:
+    print(g.name)
+```
+
 ## Sharding
 
 To run your bot across multiple gateway shards, pass ``shard_count`` when creating

{disagreement-0.4.0 → disagreement-0.4.2}/disagreement/__init__.py

@@ -12,7 +12,7 @@ __title__ = "disagreement"
 __author__ = "Slipstream"
 __license__ = "BSD 3-Clause License"
 __copyright__ = "Copyright 2025 Slipstream"
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 from .client import Client, AutoShardedClient
 from .models import Message, User, Reaction, AuditLogEntry
@@ -38,6 +38,35 @@ from .logging_config import setup_logging
 import logging
 
 
+__all__ = [
+    "Client",
+    "AutoShardedClient",
+    "Message",
+    "User",
+    "Reaction",
+    "AuditLogEntry",
+    "VoiceClient",
+    "AudioSource",
+    "FFmpegAudioSource",
+    "Typing",
+    "DisagreementException",
+    "HTTPException",
+    "GatewayException",
+    "AuthenticationError",
+    "Forbidden",
+    "NotFound",
+    "Color",
+    "utcnow",
+    "message_pager",
+    "GatewayIntent",
+    "GatewayOpcode",
+    "setup_global_error_handler",
+    "HybridContext",
+    "tasks",
+    "setup_logging",
+]
+
+
 # Configure a default logger if none has been configured yet
 if not logging.getLogger().hasHandlers():
     setup_logging(logging.INFO)

{disagreement-0.4.0 → disagreement-0.4.2}/disagreement/cache.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import time
-from typing import TYPE_CHECKING, Dict, Generic, Optional, TypeVar
+from typing import TYPE_CHECKING, Callable, Dict, Generic, Optional, TypeVar
 from collections import OrderedDict
 
 if TYPE_CHECKING:
@@ -40,6 +40,14 @@ class Cache(Generic[T]):
         self._data.move_to_end(key)
         return value
 
+    def get_or_fetch(self, key: str, fetch_fn: Callable[[], T]) -> T:
+        """Return a cached item or fetch and store it if missing."""
+        value = self.get(key)
+        if value is None:
+            value = fetch_fn()
+            self.set(key, value)
+        return value
+
     def invalidate(self, key: str) -> None:
         self._data.pop(key, None)
 

{disagreement-0.4.0 → disagreement-0.4.2}/disagreement/client.py

@@ -529,15 +529,29 @@ class Client:
                 print(f"Message: {message.content}")
         """
 
-        def decorator(
-            coro: Callable[..., Awaitable[None]],
-        ) -> Callable[..., Awaitable[None]]:
-            if not asyncio.iscoroutinefunction(coro):
-                raise TypeError("Event registered must be a coroutine function.")
-            self._event_dispatcher.register(event_name.upper(), coro)
-            return coro
-
-        return decorator
+        def decorator(
+            coro: Callable[..., Awaitable[None]],
+        ) -> Callable[..., Awaitable[None]]:
+            if not asyncio.iscoroutinefunction(coro):
+                raise TypeError("Event registered must be a coroutine function.")
+            self._event_dispatcher.register(event_name.upper(), coro)
+            return coro
+
+        return decorator
+
+    def add_listener(
+        self, event_name: str, coro: Callable[..., Awaitable[None]]
+    ) -> None:
+        """Register ``coro`` to listen for ``event_name``."""
+
+        self._event_dispatcher.register(event_name, coro)
+
+    def remove_listener(
+        self, event_name: str, coro: Callable[..., Awaitable[None]]
+    ) -> None:
+        """Remove ``coro`` from ``event_name`` listeners."""
+
+        self._event_dispatcher.unregister(event_name, coro)
 
     async def _process_message_for_commands(self, message: "Message") -> None:
         """Internal listener to process messages for commands."""
@@ -1311,8 +1325,8 @@ class Client:
 
         return self._messages.get(message_id)
 
-    async def fetch_guild(self, guild_id: Snowflake) -> Optional["Guild"]:
-        """Fetches a guild by ID from Discord and caches it."""
+    async def fetch_guild(self, guild_id: Snowflake) -> Optional["Guild"]:
+        """Fetches a guild by ID from Discord and caches it."""
 
         if self._closed:
             raise DisagreementException("Client is closed.")
@@ -1326,7 +1340,19 @@ class Client:
             return self.parse_guild(guild_data)
         except DisagreementException as e:
             print(f"Failed to fetch guild {guild_id}: {e}")
-            return None
+            return None
+
+    async def fetch_guilds(self) -> List["Guild"]:
+        """Fetch all guilds the current user is in."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.get_current_user_guilds()
+        guilds: List["Guild"] = []
+        for guild_data in data:
+            guilds.append(self.parse_guild(guild_data))
+        return guilds
 
     async def fetch_channel(self, channel_id: Snowflake) -> Optional["Channel"]:
         """Fetches a channel from Discord by its ID and updates the cache."""

{disagreement-0.4.0 → disagreement-0.4.2}/disagreement/event_dispatcher.py

@@ -60,6 +60,7 @@ class EventDispatcher:
             "GUILD_BAN_REMOVE": self._parse_guild_ban_remove,
             "GUILD_ROLE_UPDATE": self._parse_guild_role_update,
             "TYPING_START": self._parse_typing_start,
+            "VOICE_STATE_UPDATE": self._parse_voice_state_update,
         }
 
     def _parse_message_create(self, data: Dict[str, Any]) -> Message:
@@ -111,6 +112,13 @@ class EventDispatcher:
 
         return TypingStart(data, client_instance=self._client)
 
+    def _parse_voice_state_update(self, data: Dict[str, Any]):
+        """Parses raw VOICE_STATE_UPDATE data into a VoiceStateUpdate object."""
+
+        from .models import VoiceStateUpdate
+
+        return VoiceStateUpdate(data, client_instance=self._client)
+
     def _parse_message_reaction(self, data: Dict[str, Any]):
         """Parses raw reaction data into a Reaction object."""
 

{disagreement-0.4.0 → disagreement-0.4.2}/disagreement/http.py

@@ -839,9 +839,13 @@ class HTTPClient:
             use_auth_header=False,
         )
 
-    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}")
+    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}")
+
+    async def get_current_user_guilds(self) -> List[Dict[str, Any]]:
+        """Returns the guilds the current user is in."""
+        return await self.request("GET", "/users/@me/guilds")
 
     async def get_guild_member(
         self, guild_id: "Snowflake", user_id: "Snowflake"

{disagreement-0.4.0 → disagreement-0.4.2}/disagreement/models.py

@@ -106,14 +106,21 @@ class Message:
             ]
         else:
             self.components = None
-        self.attachments: List[Attachment] = [
-            Attachment(a) for a in data.get("attachments", [])
-        ]
-        self.pinned: bool = data.get("pinned", False)
-        # 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", [])
-        # self.mention_everyone: bool = data.get("mention_everyone", False)
+        self.attachments: List[Attachment] = [
+            Attachment(a) for a in data.get("attachments", [])
+        ]
+        self.pinned: bool = data.get("pinned", False)
+        # 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", [])
+        # self.mention_everyone: bool = data.get("mention_everyone", False)
+
+    @property
+    def jump_url(self) -> str:
+        """Return a URL that jumps to this message in the Discord client."""
+
+        guild_or_dm = self.guild_id or "@me"
+        return f"https://discord.com/channels/{guild_or_dm}/{self.channel_id}/{self.id}"
 
     @property
     def clean_content(self) -> str:
@@ -624,14 +631,31 @@ class File:
         self.data = data
 
 
-class AllowedMentions:
+class AllowedMentions:
     """Represents allowed mentions for a message or interaction response."""
 
-    def __init__(self, data: Dict[str, Any]):
-        self.parse: List[str] = data.get("parse", [])
-        self.roles: List[str] = data.get("roles", [])
-        self.users: List[str] = data.get("users", [])
-        self.replied_user: bool = data.get("replied_user", False)
+    def __init__(self, data: Dict[str, Any]):
+        self.parse: List[str] = data.get("parse", [])
+        self.roles: List[str] = data.get("roles", [])
+        self.users: List[str] = data.get("users", [])
+        self.replied_user: bool = data.get("replied_user", False)
+
+    @classmethod
+    def all(cls) -> "AllowedMentions":
+        """Return an instance allowing all mention types."""
+
+        return cls(
+            {
+                "parse": ["users", "roles", "everyone"],
+                "replied_user": True,
+            }
+        )
+
+    @classmethod
+    def none(cls) -> "AllowedMentions":
+        """Return an instance disallowing all mentions."""
+
+        return cls({"parse": [], "replied_user": False})
 
     def to_dict(self) -> Dict[str, Any]:
         payload: Dict[str, Any] = {"parse": self.parse}
@@ -2467,7 +2491,7 @@ class PresenceUpdate:
         return f"<PresenceUpdate user_id='{self.user.id}' guild_id='{self.guild_id}' status='{self.status}'>"
 
 
-class TypingStart:
+class TypingStart:
     """Represents a TYPING_START event."""
 
     def __init__(
@@ -2480,10 +2504,39 @@ class TypingStart:
         self.timestamp: int = data["timestamp"]
         self.member: Optional[Member] = (
             Member(data["member"], client_instance) if data.get("member") else None
-        )
-
-    def __repr__(self) -> str:
-        return f"<TypingStart channel_id='{self.channel_id}' user_id='{self.user_id}'>"
+        )
+
+    def __repr__(self) -> str:
+        return f"<TypingStart channel_id='{self.channel_id}' user_id='{self.user_id}'>"
+
+
+class VoiceStateUpdate:
+    """Represents a VOICE_STATE_UPDATE event."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ):
+        self._client = client_instance
+        self.guild_id: Optional[str] = data.get("guild_id")
+        self.channel_id: Optional[str] = data.get("channel_id")
+        self.user_id: str = data["user_id"]
+        self.member: Optional[Member] = (
+            Member(data["member"], client_instance) if data.get("member") else None
+        )
+        self.session_id: str = data["session_id"]
+        self.deaf: bool = data.get("deaf", False)
+        self.mute: bool = data.get("mute", False)
+        self.self_deaf: bool = data.get("self_deaf", False)
+        self.self_mute: bool = data.get("self_mute", False)
+        self.self_stream: Optional[bool] = data.get("self_stream")
+        self.self_video: bool = data.get("self_video", False)
+        self.suppress: bool = data.get("suppress", False)
+
+    def __repr__(self) -> str:
+        return (
+            f"<VoiceStateUpdate guild_id='{self.guild_id}' user_id='{self.user_id}' "
+            f"channel_id='{self.channel_id}'>"
+        )
 
 
 class Reaction:

{disagreement-0.4.0 → disagreement-0.4.2}/disagreement/voice_client.py

@@ -259,5 +259,20 @@ class VoiceClient:
             self._udp.close()
         if self._udp_receive_thread:
             self._udp_receive_thread.join(timeout=1)
-        if self._sink:
-            self._sink.close()
+        if self._sink:
+            self._sink.close()
+
+    async def __aenter__(self) -> "VoiceClient":
+        """Enter the context manager by connecting to the voice gateway."""
+        await self.connect()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type],
+        exc: Optional[BaseException],
+        tb: Optional[BaseException],
+    ) -> bool:
+        """Exit the context manager and close the connection."""
+        await self.close()
+        return False

{disagreement-0.4.0 → disagreement-0.4.2/disagreement.egg-info}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: disagreement
-Version: 0.4.0
+Version: 0.4.2
 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
+Project-URL: Documentation, https://disagreement.xyz/
 Keywords: discord,api,bot,async,aiohttp
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -45,6 +46,7 @@ A Python library for interacting with the Discord API, with a focus on bot devel
 - Gateway and HTTP API clients
 - Slash command framework
 - Message component helpers
+- `Message.jump_url` property for quick links to messages
 - Built-in caching layer
 - Experimental voice support
 - Helpful error handling utilities
@@ -152,9 +154,10 @@ session parameter supported by ``aiohttp``.
 Specify default mention behaviour for all outgoing messages when constructing the client:
 
 ```python
+from disagreement.models import AllowedMentions
 client = disagreement.Client(
     token=token,
-    allowed_mentions={"parse": [], "replied_user": False},
+    allowed_mentions=AllowedMentions.none().to_dict(),
 )
 ```
 
@@ -191,6 +194,14 @@ guild = await client.fetch_guild("123456789012345678")
 roles = await client.fetch_roles(guild.id)
 ```
 
+Call `Client.fetch_guilds` to list all guilds the current user has access to.
+
+```python
+guilds = await client.fetch_guilds()
+for g in guilds:
+    print(g.name)
+```
+
 ## Sharding
 
 To run your bot across multiple gateway shards, pass ``shard_count`` when creating

{disagreement-0.4.0 → disagreement-0.4.2}/disagreement.egg-info/SOURCES.txt

@@ -99,6 +99,7 @@ examples/hybrid_bot.py
 examples/message_history.py
 examples/modal_command.py
 examples/modal_send.py
+examples/moderation_bot.py
 examples/reactions.py
 examples/sample_extension.py
 examples/sharded_bot.py

{disagreement-0.4.0 → disagreement-0.4.2}/docs/events.md

@@ -1,7 +1,7 @@
 # Events
 
-Disagreement dispatches Gateway events to asynchronous callbacks. Handlers can be registered with `@client.event` or `client.on_event`.
-Listeners may be removed later using `EventDispatcher.unregister(event_name, coro)`.
+Disagreement dispatches Gateway events to asynchronous callbacks. Handlers can be registered with `@client.event`, `client.on_event`, or `client.add_listener(event_name, coro)`.
+Listeners may be removed later using `client.remove_listener(event_name, coro)` or `EventDispatcher.unregister(event_name, coro)`.
 
 ## Raw Events
 
@@ -131,3 +131,13 @@ a dictionary with the shard ID.
 async def on_shard_resume(info: dict):
     ...
 ```
+
+## VOICE_STATE_UPDATE
+
+Triggered when a user's voice connection state changes, such as joining or leaving a voice channel. The callback receives a `VoiceStateUpdate` model.
+
+```python
+@client.event
+async def on_voice_state_update(state: disagreement.VoiceStateUpdate):
+    ...
+```

{disagreement-0.4.0 → disagreement-0.4.2}/docs/http_client.md

@@ -18,3 +18,14 @@ client = Client(
 These options are passed through to `aiohttp.ClientSession` when the session is
 created. You can set a proxy URL, provide a custom connector, or supply any
 other supported session argument.
+
+## Get Current User Guilds
+
+The HTTP client can list the guilds the bot user is in:
+
+```python
+from disagreement.http import HTTPClient
+
+http = HTTPClient(token="TOKEN")
+guilds = await http.get_current_user_guilds()
+```

{disagreement-0.4.0 → disagreement-0.4.2}/docs/introduction.md

@@ -118,15 +118,19 @@ session parameter supported by ``aiohttp``.
 Specify default mention behaviour for all outgoing messages when constructing the client:
 
 ```python
+from disagreement.models import AllowedMentions
 client = disagreement.Client(
     token=token,
-    allowed_mentions={"parse": [], "replied_user": False},
+    allowed_mentions=AllowedMentions.none().to_dict(),
 )
 ```
 
 This dictionary is used whenever ``send_message`` is called without an explicit
 ``allowed_mentions`` argument.
 
+The :class:`AllowedMentions` class offers ``none()`` and ``all()`` helpers for
+quickly generating these configurations.
+
 ### Defining Subcommands with `AppCommandGroup`
 
 ```python
@@ -157,6 +161,12 @@ guild = await client.fetch_guild("123456789012345678")
 roles = await client.fetch_roles(guild.id)
 ```
 
+To retrieve all guilds available to the bot, use `Client.fetch_guilds`.
+
+```python
+guilds = await client.fetch_guilds()
+```
+
 ## Sharding
 
 To run your bot across multiple gateway shards, pass ``shard_count`` when creating

{disagreement-0.4.0 → disagreement-0.4.2}/docs/mentions.md

@@ -8,15 +8,20 @@ Use the ``allowed_mentions`` parameter of :class:`disagreement.Client` to set a
 default for all messages:
 
 ```python
+from disagreement.models import AllowedMentions
 client = disagreement.Client(
     token="YOUR_TOKEN",
-    allowed_mentions={"parse": [], "replied_user": False},
+    allowed_mentions=AllowedMentions.none().to_dict(),
 )
 ```
 
 When ``Client.send_message`` is called without an explicit ``allowed_mentions``
 argument this value will be used.
 
+``AllowedMentions`` also provides the convenience methods
+``AllowedMentions.none()`` and ``AllowedMentions.all()`` to quickly create
+common configurations.
+
 ## Next Steps
 
 - [Commands](commands.md)

{disagreement-0.4.0 → disagreement-0.4.2}/docs/message_history.md

@@ -8,6 +8,9 @@ async for message in channel.history(limit=200):
     print(message.content)
 ```
 
+Each returned `Message` has a ``jump_url`` property that links directly to the
+message in the Discord client.
+
 Pass `before` or `after` to control the range of messages returned. The paginator fetches messages in batches of up to 100 until the limit is reached or Discord returns no more messages.
 
 ## Next Steps

{disagreement-0.4.0 → disagreement-0.4.2}/docs/voice_client.md

@@ -9,15 +9,17 @@ import asyncio
 import os
 import disagreement
 
-vc = disagreement.VoiceClient(
-    os.environ["DISCORD_VOICE_ENDPOINT"],
-    os.environ["DISCORD_SESSION_ID"],
-    os.environ["DISCORD_VOICE_TOKEN"],
-    int(os.environ["DISCORD_GUILD_ID"]),
-    int(os.environ["DISCORD_USER_ID"]),
-)
-
-asyncio.run(vc.connect())
+async def main():
+    async with disagreement.VoiceClient(
+        os.environ["DISCORD_VOICE_ENDPOINT"],
+        os.environ["DISCORD_SESSION_ID"],
+        os.environ["DISCORD_VOICE_TOKEN"],
+        int(os.environ["DISCORD_GUILD_ID"]),
+        int(os.environ["DISCORD_USER_ID"]),
+    ) as vc:
+        await vc.send_audio_frame(b"...")
+
+asyncio.run(main())
 ```
 
 After connecting you can send raw Opus frames:
@@ -41,7 +43,7 @@ You can switch sources while connected:
 await vc.play(FFmpegAudioSource("other.mp3"))
 ```
 
-Call `await vc.close()` when finished.
+The connection will be closed automatically when leaving the `async with` block.
 
 ## Fetching Available Voice Regions