disagreement 0.4.1__py3-none-any.whl → 0.4.2__py3-none-any.whl

disagreement/__init__.py

@@ -12,7 +12,7 @@ __title__ = "disagreement"
 __author__ = "Slipstream"
 __license__ = "BSD 3-Clause License"
 __copyright__ = "Copyright 2025 Slipstream"
-__version__ = "0.4.1"
+__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/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/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/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/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/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/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.1.dist-info → disagreement-0.4.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: disagreement
-Version: 0.4.1
+Version: 0.4.2
 Summary: A Python library for the Discord API.
 Author-email: Slipstream <me@slipstreamm.dev>
 License: BSD 3-Clause
@@ -46,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
@@ -153,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(),
 )
 ```
 
@@ -192,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.1.dist-info → disagreement-0.4.2.dist-info}/RECORD

@@ -1,21 +1,21 @@
-disagreement/__init__.py,sha256=4rWCD-jlCX7cGKi7JpXzFGr4aHgM6N2lBuwrsQ7VA44,1137
+disagreement/__init__.py,sha256=SEe8hwL_hzJj8c2gjFJG35OV-f-10owc4NbpdC3gnu0,1646
 disagreement/audio.py,sha256=erBaupz-Hw8LR-5mGLDvhphCDAQeWk0ZBA0AMVwDUIM,4360
-disagreement/cache.py,sha256=srmaw-x8iiqU53eh33JgLLkM-K-TgFnvOS2lYO7Z2FI,2866
+disagreement/cache.py,sha256=9yit7gIro0nEngBQUsBLHN2gGWTZ2EYiBMrfgcu5LVM,3157
 disagreement/caching.py,sha256=KEicB8fIBRwc5Ifl1CCHHnPu-NfAvqdfArjxFuV557g,3841
-disagreement/client.py,sha256=RBiprWFfW02Wkt8FwHaYvJfcK4vOR559Fn5p26ab9ME,67441
+disagreement/client.py,sha256=W-8DwXxcZEAjaIZfZVKy49CZMhXDf4-WIrBnSvd4cFc,68285
 disagreement/color.py,sha256=0RumZU9geS51rmmywwotmkXFc8RyQghOviRGGrHmvW4,4495
 disagreement/components.py,sha256=tEYJ2RHVpIFtZuPPxZ0v8ssUw_x7ybhYBzHNsRiXXvU,5250
 disagreement/enums.py,sha256=F_DHgeAnnw17ILswOuxPR6G1OimL6aeuxIEAni1XPyY,11187
 disagreement/error_handler.py,sha256=rj9AiJhRLPNAaAY6Gj0KQXgKNfPsgnZUtyTljclybD8,1161
 disagreement/errors.py,sha256=Zi7x_hgGXCDw5ht2HpcQDba4NQbXkBbjQIVhU9RVyhE,32236
-disagreement/event_dispatcher.py,sha256=o-PgfOYEwlCbmrWeLuycp-QT6tlXF2JEU3Dyv0VFZ0c,11419
+disagreement/event_dispatcher.py,sha256=0vCLYRPSihuf1qmLBY9KFjj85bVWUxB8s7uhJvMbyy4,11745
 disagreement/gateway.py,sha256=7ccRygL1gnd_w8DldsLFxreZy1iCdw6Nw65_UW8Ulz8,26831
-disagreement/http.py,sha256=iYmX6QjBEkcZlHJTefJ-tHHYp8BV4TTQYE-vaHGjfUk,51729
+disagreement/http.py,sha256=IRaEhhQvfnSX5HM_2r3OTvrMdPK-suhoi7l2Wsl3X-c,51915
 disagreement/hybrid_context.py,sha256=VYCmcreTZdPBU9v-Cy48W38vgWO2t8nM2ulC6_z4HjU,1095
 disagreement/i18n.py,sha256=1L4rcFuKP0XjHk9dVwbNh4BkLk2ZlxxZ_-tecGWa9S0,718
 disagreement/interactions.py,sha256=moN2iQEE9ntC-Y2Q7uxUqoBBRYHegNwB00w-2UD30q4,21703
 disagreement/logging_config.py,sha256=4q6baQPE6X_0lfaBTFMU1uqc03x5SbJqo2hsApdDFac,686
-disagreement/models.py,sha256=ohpMS03K9Hs9lJ2uWLG_0P3VTJr8sSy9dNsc3uRerpM,97981
+disagreement/models.py,sha256=q6txqdQ0EpUqeZbn24BYRqDl3mJ1lO2qPnnB4mnhyFU,99839
 disagreement/oauth.py,sha256=TfDdCwg1J7osM9wDi61dtNBA5BrQk5DeQrrHsYycH34,2810
 disagreement/permissions.py,sha256=7g5cIlg-evHXOL0-pmtT5EwqcB-stXot1HZSLz724sE,3008
 disagreement/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -23,7 +23,7 @@ disagreement/rate_limiter.py,sha256=ubwR_UTPs2MotipBdtqpgwQKx0IHt2I3cdfFcXTFv7g,
 disagreement/shard_manager.py,sha256=gE7562izYcN-5jTDWUP9kIFX5gffRjIryqNxk1mtnSM,2128
 disagreement/typing.py,sha256=_1oFWfZ4HyH5Q3bnF7CO24s79z-3_B5Qb69kWiwLhhU,1242
 disagreement/utils.py,sha256=mz7foTCOAmUv9n8EcdZeiFarwqB14xHOG8o0p8tFuKA,2014
-disagreement/voice_client.py,sha256=AgBhId6syetP4wwHq47IgGlfNIqtLUt_5nbEE-c6KtQ,9250
+disagreement/voice_client.py,sha256=mn7wiE_HzUibaTPY-xCP7b8AkOx4ioeR7zF2YUqC7ok,9700
 disagreement/ext/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 disagreement/ext/loader.py,sha256=9_uULvNAa-a6UiaeQhWglwgIrHEPKbf9bnWtSL1KV5Q,1408
 disagreement/ext/tasks.py,sha256=b14KI-btikbrjPlD76md3Ggt6znrxPqr7TDarU4PYBg,7269
@@ -48,8 +48,8 @@ disagreement/ui/item.py,sha256=bm-EmQEZpe8Kt8JrRw-o0uQdccgjErORcFsBqaXOcV8,1112
 disagreement/ui/modal.py,sha256=w0ZEVslXzx2-RWUP4jdVB54zDuT81jpueVWZ70byFnI,4137
 disagreement/ui/select.py,sha256=XjWRlWkA09QZaDDLn-wDDOWIuj0Mb4VCWJEOAaExZXw,3018
 disagreement/ui/view.py,sha256=UdOaoSe0NZXZMjOtM8CLCPcDHVf6Dn2yr2PHLSvoJsg,5834
-disagreement-0.4.1.dist-info/licenses/LICENSE,sha256=zfmtgJhVFHnqT7a8LAQFthXu5bP7EEHmEL99trV66Ew,1474
-disagreement-0.4.1.dist-info/METADATA,sha256=yKEkXoTqMFuBVFKGIKQ6d39ExMuS24MiniEJ3ggyRkY,6322
-disagreement-0.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-disagreement-0.4.1.dist-info/top_level.txt,sha256=t7FY_3iaYhdB6X6y9VybJ2j7UZbVeRUe9wRgH8d5Gtk,13
-disagreement-0.4.1.dist-info/RECORD,,
+disagreement-0.4.2.dist-info/licenses/LICENSE,sha256=zfmtgJhVFHnqT7a8LAQFthXu5bP7EEHmEL99trV66Ew,1474
+disagreement-0.4.2.dist-info/METADATA,sha256=Y4OVIt8mHGWsb9fuyL51QiVXVrObftm4g7TQVEATmL0,6590
+disagreement-0.4.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+disagreement-0.4.2.dist-info/top_level.txt,sha256=t7FY_3iaYhdB6X6y9VybJ2j7UZbVeRUe9wRgH8d5Gtk,13
+disagreement-0.4.2.dist-info/RECORD,,