disagreement 0.3.0b1__py3-none-any.whl → 0.4.0__py3-none-any.whl

disagreement/__init__.py

@@ -1,5 +1,3 @@
-# disagreement/__init__.py
-
 """
 Disagreement
 ~~~~~~~~~~~~
@@ -14,7 +12,7 @@ __title__ = "disagreement"
 __author__ = "Slipstream"
 __license__ = "BSD 3-Clause License"
 __copyright__ = "Copyright 2025 Slipstream"
-__version__ = "0.3.0b1"
+__version__ = "0.4.0"
 
 from .client import Client, AutoShardedClient
 from .models import Message, User, Reaction, AuditLogEntry
@@ -31,7 +29,7 @@ from .errors import (
 )
 from .color import Color
 from .utils import utcnow, message_pager
-from .enums import GatewayIntent, GatewayOpcode  # Export enums
+from .enums import GatewayIntent, GatewayOpcode
 from .error_handler import setup_global_error_handler
 from .hybrid_context import HybridContext
 from .ext import tasks

disagreement/audio.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import io
+import shlex
 from typing import Optional, Union
 
 
@@ -35,15 +36,27 @@ class FFmpegAudioSource(AudioSource):
         A filename, URL, or file-like object to read from.
     """
 
-    def __init__(self, source: Union[str, io.BufferedIOBase]):
+    def __init__(
+        self,
+        source: Union[str, io.BufferedIOBase],
+        *,
+        before_options: Optional[str] = None,
+        options: Optional[str] = None,
+        volume: float = 1.0,
+    ):
         self.source = source
+        self.before_options = before_options
+        self.options = options
+        self.volume = volume
         self.process: Optional[asyncio.subprocess.Process] = None
         self._feeder: Optional[asyncio.Task] = None
 
     async def _spawn(self) -> None:
         if isinstance(self.source, str):
-            args = [
-                "ffmpeg",
+            args = ["ffmpeg"]
+            if self.before_options:
+                args += shlex.split(self.before_options)
+            args += [
                 "-i",
                 self.source,
                 "-f",
@@ -54,14 +67,18 @@ class FFmpegAudioSource(AudioSource):
                 "2",
                 "pipe:1",
             ]
+            if self.options:
+                args += shlex.split(self.options)
             self.process = await asyncio.create_subprocess_exec(
                 *args,
                 stdout=asyncio.subprocess.PIPE,
                 stderr=asyncio.subprocess.DEVNULL,
             )
         else:
-            args = [
-                "ffmpeg",
+            args = ["ffmpeg"]
+            if self.before_options:
+                args += shlex.split(self.before_options)
+            args += [
                 "-i",
                 "pipe:0",
                 "-f",
@@ -72,6 +89,8 @@ class FFmpegAudioSource(AudioSource):
                 "2",
                 "pipe:1",
             ]
+            if self.options:
+                args += shlex.split(self.options)
             self.process = await asyncio.create_subprocess_exec(
                 *args,
                 stdin=asyncio.subprocess.PIPE,
@@ -115,6 +134,7 @@ class FFmpegAudioSource(AudioSource):
             with contextlib.suppress(Exception):
                 self.source.close()
 
+
 class AudioSink:
     """Abstract base class for audio sinks."""
 

disagreement/cache.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import time
 from typing import TYPE_CHECKING, Dict, Generic, Optional, TypeVar
+from collections import OrderedDict
 
 if TYPE_CHECKING:
     from .models import Channel, Guild, Member
@@ -11,15 +12,22 @@ T = TypeVar("T")
 
 
 class Cache(Generic[T]):
-    """Simple in-memory cache with optional TTL support."""
+    """Simple in-memory cache with optional TTL and max size support."""
 
-    def __init__(self, ttl: Optional[float] = None) -> None:
+    def __init__(
+        self, ttl: Optional[float] = None, maxlen: Optional[int] = None
+    ) -> None:
         self.ttl = ttl
-        self._data: Dict[str, tuple[T, Optional[float]]] = {}
+        self.maxlen = maxlen
+        self._data: "OrderedDict[str, tuple[T, Optional[float]]]" = OrderedDict()
 
     def set(self, key: str, value: T) -> None:
         expiry = time.monotonic() + self.ttl if self.ttl is not None else None
+        if key in self._data:
+            self._data.move_to_end(key)
         self._data[key] = (value, expiry)
+        if self.maxlen is not None and len(self._data) > self.maxlen:
+            self._data.popitem(last=False)
 
     def get(self, key: str) -> Optional[T]:
         item = self._data.get(key)
@@ -29,6 +37,7 @@ class Cache(Generic[T]):
         if expiry is not None and expiry < time.monotonic():
             self.invalidate(key)
             return None
+        self._data.move_to_end(key)
         return value
 
     def invalidate(self, key: str) -> None:

disagreement/caching.py

@@ -8,10 +8,10 @@ class _MemberCacheFlagValue:
     flag: int
 
     def __init__(self, func: Callable[[Any], bool]):
-        self.flag = getattr(func, 'flag', 0)
+        self.flag = getattr(func, "flag", 0)
         self.__doc__ = func.__doc__
 
-    def __get__(self, instance: 'MemberCacheFlags', owner: type) -> Any:
+    def __get__(self, instance: "MemberCacheFlags", owner: type) -> Any:
         if instance is None:
             return self
         return instance.value & self.flag != 0
@@ -23,23 +23,24 @@ class _MemberCacheFlagValue:
             instance.value &= ~self.flag
 
     def __repr__(self) -> str:
-        return f'<{self.__class__.__name__} flag={self.flag}>'
+        return f"<{self.__class__.__name__} flag={self.flag}>"
 
 
 def flag_value(flag: int) -> Callable[[Callable[[Any], bool]], _MemberCacheFlagValue]:
     def decorator(func: Callable[[Any], bool]) -> _MemberCacheFlagValue:
-        setattr(func, 'flag', flag)
+        setattr(func, "flag", flag)
         return _MemberCacheFlagValue(func)
+
     return decorator
 
 
 class MemberCacheFlags:
-    __slots__ = ('value',)
+    __slots__ = ("value",)
 
     VALID_FLAGS: ClassVar[Dict[str, int]] = {
-        'joined': 1 << 0,
-        'voice': 1 << 1,
-        'online': 1 << 2,
+        "joined": 1 << 0,
+        "voice": 1 << 1,
+        "online": 1 << 2,
     }
     DEFAULT_FLAGS: ClassVar[int] = 1 | 2 | 4
     ALL_FLAGS: ClassVar[int] = sum(VALID_FLAGS.values())
@@ -48,7 +49,7 @@ class MemberCacheFlags:
         self.value = self.DEFAULT_FLAGS
         for key, value in kwargs.items():
             if key not in self.VALID_FLAGS:
-                raise TypeError(f'{key!r} is not a valid member cache flag.')
+                raise TypeError(f"{key!r} is not a valid member cache flag.")
             setattr(self, key, value)
 
     @classmethod
@@ -67,7 +68,7 @@ class MemberCacheFlags:
         return hash(self.value)
 
     def __repr__(self) -> str:
-        return f'<MemberCacheFlags value={self.value}>'
+        return f"<MemberCacheFlags value={self.value}>"
 
     def __iter__(self) -> Iterator[Tuple[str, bool]]:
         for name in self.VALID_FLAGS:
@@ -92,17 +93,17 @@ class MemberCacheFlags:
     @classmethod
     def only_joined(cls) -> MemberCacheFlags:
         """A factory method that creates a :class:`MemberCacheFlags` with only the `joined` flag enabled."""
-        return cls._from_value(cls.VALID_FLAGS['joined'])
+        return cls._from_value(cls.VALID_FLAGS["joined"])
 
     @classmethod
     def only_voice(cls) -> MemberCacheFlags:
         """A factory method that creates a :class:`MemberCacheFlags` with only the `voice` flag enabled."""
-        return cls._from_value(cls.VALID_FLAGS['voice'])
+        return cls._from_value(cls.VALID_FLAGS["voice"])
 
     @classmethod
     def only_online(cls) -> MemberCacheFlags:
         """A factory method that creates a :class:`MemberCacheFlags` with only the `online` flag enabled."""
-        return cls._from_value(cls.VALID_FLAGS['online'])
+        return cls._from_value(cls.VALID_FLAGS["online"])
 
     @flag_value(1 << 0)
     def joined(self) -> bool:
@@ -117,4 +118,4 @@ class MemberCacheFlags:
     @flag_value(1 << 2)
     def online(self) -> bool:
         """Whether to cache members that are online."""
-        return False
+        return False

disagreement/client.py

@@ -1,5 +1,3 @@
-# disagreement/client.py
-
 """
 The main Client class for interacting with the Discord API.
 """
@@ -36,6 +34,7 @@ from .ext import loader as ext_loader
 from .interactions import Interaction, Snowflake
 from .error_handler import setup_global_error_handler
 from .voice_client import VoiceClient
+from .models import Activity
 
 if TYPE_CHECKING:
     from .models import (
@@ -75,13 +74,21 @@ class Client:
         intents (Optional[int]): The Gateway Intents to use. Defaults to `GatewayIntent.default()`.
                                  You might need to enable privileged intents in your bot's application page.
         loop (Optional[asyncio.AbstractEventLoop]): The event loop to use for asynchronous operations.
-                                                    Defaults to `asyncio.get_event_loop()`.
+                                                    Defaults to the running loop
+                                                    via `asyncio.get_running_loop()`,
+                                                    or a new loop from
+                                                    `asyncio.new_event_loop()` if
+                                                    none is running.
         command_prefix (Union[str, List[str], Callable[['Client', Message], Union[str, List[str]]]]):
             The prefix(es) for commands. Defaults to '!'.
         verbose (bool): If True, print raw HTTP and Gateway traffic for debugging.
+        mention_replies (bool): Whether replies mention the author by default.
+        allowed_mentions (Optional[Dict[str, Any]]): Default allowed mentions for messages.
         http_options (Optional[Dict[str, Any]]): Extra options passed to
             :class:`HTTPClient` for creating the internal
             :class:`aiohttp.ClientSession`.
+        message_cache_maxlen (Optional[int]): Maximum number of messages to keep
+            in the cache. When ``None``, the cache size is unlimited.
     """
 
     def __init__(
@@ -95,10 +102,12 @@ class Client:
         application_id: Optional[Union[str, int]] = None,
         verbose: bool = False,
         mention_replies: bool = False,
+        allowed_mentions: Optional[Dict[str, Any]] = None,
         shard_count: Optional[int] = None,
         gateway_max_retries: int = 5,
         gateway_max_backoff: float = 60.0,
         member_cache_flags: Optional[MemberCacheFlags] = None,
+        message_cache_maxlen: Optional[int] = None,
         http_options: Optional[Dict[str, Any]] = None,
     ):
         if not token:
@@ -108,6 +117,7 @@ class Client:
         self.member_cache_flags: MemberCacheFlags = (
             member_cache_flags if member_cache_flags is not None else MemberCacheFlags()
         )
+        self.message_cache_maxlen: Optional[int] = message_cache_maxlen
         self.intents: int = intents if intents is not None else GatewayIntent.default()
         if loop:
             self.loop: asyncio.AbstractEventLoop = loop
@@ -157,7 +167,7 @@ class Client:
         self._guilds: GuildCache = GuildCache()
         self._channels: ChannelCache = ChannelCache()
         self._users: Cache["User"] = Cache()
-        self._messages: Cache["Message"] = Cache(ttl=3600)  # Cache messages for an hour
+        self._messages: Cache["Message"] = Cache(ttl=3600, maxlen=message_cache_maxlen)
         self._views: Dict[Snowflake, "View"] = {}
         self._persistent_views: Dict[str, "View"] = {}
         self._voice_clients: Dict[Snowflake, VoiceClient] = {}
@@ -165,6 +175,7 @@ class Client:
 
         # Default whether replies mention the user
         self.mention_replies: bool = mention_replies
+        self.allowed_mentions: Optional[Dict[str, Any]] = allowed_mentions
 
         # Basic signal handling for graceful shutdown
         # This might be better handled by the user's application code, but can be a nice default.
@@ -251,17 +262,16 @@ class Client:
                 raise
             except DisagreementException as e:  # Includes GatewayException
                 print(f"Failed to connect (Attempt {attempt + 1}/{max_retries}): {e}")
-                if attempt < max_retries - 1:
-                    print(f"Retrying in {retry_delay} seconds...")
-                    await asyncio.sleep(retry_delay)
-                    retry_delay = min(
-                        retry_delay * 2, 60
-                    )  # Exponential backoff up to 60s
-                else:
-                    print("Max connection retries reached. Giving up.")
-                    await self.close()  # Ensure cleanup
-                    raise
-        # Should not be reached if max_retries is > 0
+                if attempt < max_retries - 1:
+                    print(f"Retrying in {retry_delay} seconds...")
+                    await asyncio.sleep(retry_delay)
+                    retry_delay = min(
+                        retry_delay * 2, 60
+                    )  # Exponential backoff up to 60s
+                else:
+                    print("Max connection retries reached. Giving up.")
+                    await self.close()  # Ensure cleanup
+                    raise
         if max_retries == 0:  # If max_retries was 0, means no retries attempted
             raise DisagreementException("Connection failed with 0 retries allowed.")
 
@@ -399,6 +409,12 @@ class Client:
             return self._gateway.latency
         return None
 
+    @property
+    def latency_ms(self) -> Optional[float]:
+        """Returns the gateway latency in milliseconds, or ``None`` if unavailable."""
+        latency = getattr(self._gateway, "latency_ms", None)
+        return round(latency, 2) if latency is not None else None
+
     async def wait_until_ready(self) -> None:
         """|coro|
         Waits until the client is fully connected to Discord and the initial state is processed.
@@ -435,8 +451,7 @@ class Client:
     async def change_presence(
         self,
         status: str,
-        activity_name: Optional[str] = None,
-        activity_type: int = 0,
+        activity: Optional[Activity] = None,
         since: int = 0,
         afk: bool = False,
     ):
@@ -445,8 +460,7 @@ class Client:
 
         Args:
             status (str): The new status for the client (e.g., "online", "idle", "dnd", "invisible").
-            activity_name (Optional[str]): The name of the activity.
-            activity_type (int): The type of the activity.
+            activity (Optional[Activity]): Activity instance describing what the bot is doing.
             since (int): The timestamp (in milliseconds) of when the client went idle.
             afk (bool): Whether the client is AFK.
         """
@@ -456,8 +470,7 @@ class Client:
         if self._gateway:
             await self._gateway.update_presence(
                 status=status,
-                activity_name=activity_name,
-                activity_type=activity_type,
+                activity=activity,
                 since=since,
                 afk=afk,
             )
@@ -693,7 +706,7 @@ class Client:
             )
             # import traceback
             # traceback.print_exception(type(error.original), error.original, error.original.__traceback__)
- 
+
     async def on_command_completion(self, ctx: "CommandContext") -> None:
         """
         Default command completion handler. Called when a command has successfully completed.
@@ -1010,7 +1023,7 @@ class Client:
             embeds (Optional[List[Embed]]): A list of embeds to send. Cannot be used with `embed`.
                                             Discord supports up to 10 embeds per message.
             components (Optional[List[ActionRow]]): A list of ActionRow components to include.
-            allowed_mentions (Optional[Dict[str, Any]]): Allowed mentions for the message.
+            allowed_mentions (Optional[Dict[str, Any]]): Allowed mentions for the message. Defaults to :attr:`Client.allowed_mentions`.
             message_reference (Optional[Dict[str, Any]]): Message reference for replying.
             attachments (Optional[List[Any]]): Attachments to include with the message.
             files (Optional[List[Any]]): Files to upload with the message.
@@ -1057,6 +1070,9 @@ class Client:
                 if isinstance(comp, ComponentModel)
             ]
 
+        if allowed_mentions is None:
+            allowed_mentions = self.allowed_mentions
+
         message_data = await self._http.send_message(
             channel_id=channel_id,
             content=content,
@@ -1428,6 +1444,24 @@ class Client:
 
         await self._http.delete_guild_template(guild_id, template_code)
 
+    async def fetch_widget(self, guild_id: Snowflake) -> Dict[str, Any]:
+        """|coro| Fetch a guild's widget settings."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        return await self._http.get_guild_widget(guild_id)
+
+    async def edit_widget(
+        self, guild_id: Snowflake, payload: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """|coro| Edit a guild's widget settings."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        return await self._http.edit_guild_widget(guild_id, payload)
+
     async def fetch_scheduled_events(
         self, guild_id: Snowflake
     ) -> List["ScheduledEvent"]:
@@ -1514,35 +1548,35 @@ class Client:
         return [self.parse_invite(inv) for inv in data]
 
     def add_persistent_view(self, view: "View") -> None:
-       """
-       Registers a persistent view with the client.
-
-       Persistent views have a timeout of `None` and their components must have a `custom_id`.
-       This allows the view to be re-instantiated across bot restarts.
-
-       Args:
-           view (View): The view instance to register.
-
-       Raises:
-           ValueError: If the view is not persistent (timeout is not None) or if a component's
-                       custom_id is already registered.
-       """
-       if self.is_ready():
-           print(
-               "Warning: Adding a persistent view after the client is ready. "
-               "This view will only be available for interactions on this session."
-           )
-
-       if view.timeout is not None:
-           raise ValueError("Persistent views must have a timeout of None.")
-
-       for item in view.children:
-           if item.custom_id:  # Ensure custom_id is not None
-               if item.custom_id in self._persistent_views:
-                   raise ValueError(
-                       f"A component with custom_id '{item.custom_id}' is already registered."
-                   )
-               self._persistent_views[item.custom_id] = view
+        """
+        Registers a persistent view with the client.
+
+        Persistent views have a timeout of `None` and their components must have a `custom_id`.
+        This allows the view to be re-instantiated across bot restarts.
+
+        Args:
+            view (View): The view instance to register.
+
+        Raises:
+            ValueError: If the view is not persistent (timeout is not None) or if a component's
+                        custom_id is already registered.
+        """
+        if self.is_ready():
+            print(
+                "Warning: Adding a persistent view after the client is ready. "
+                "This view will only be available for interactions on this session."
+            )
+
+        if view.timeout is not None:
+            raise ValueError("Persistent views must have a timeout of None.")
+
+        for item in view.children:
+            if item.custom_id:  # Ensure custom_id is not None
+                if item.custom_id in self._persistent_views:
+                    raise ValueError(
+                        f"A component with custom_id '{item.custom_id}' is already registered."
+                    )
+                self._persistent_views[item.custom_id] = view
 
     # --- Application Command Methods ---
     async def process_interaction(self, interaction: Interaction) -> None:

disagreement/enums.py

@@ -1,10 +1,8 @@
-# disagreement/enums.py
-
 """
 Enums for Discord constants.
 """
 
-from enum import IntEnum, Enum  # Import Enum
+from enum import IntEnum, Enum
 
 
 class GatewayOpcode(IntEnum):
@@ -375,6 +373,15 @@ class OverwriteType(IntEnum):
     MEMBER = 1
 
 
+class AutoArchiveDuration(IntEnum):
+    """Thread auto-archive duration in minutes."""
+
+    HOUR = 60
+    DAY = 1440
+    THREE_DAYS = 4320
+    WEEK = 10080
+
+
 # --- Component Enums ---
 
 

disagreement/error_handler.py

@@ -14,7 +14,11 @@ def setup_global_error_handler(
     The handler logs unhandled exceptions so they don't crash the bot.
     """
     if loop is None:
-        loop = asyncio.get_event_loop()
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
 
     if not logging.getLogger().hasHandlers():
         setup_logging(logging.ERROR)