disagreement 0.2.0rc1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: disagreement
-Version: 0.2.0rc1
+Version: 0.4.0
 Summary: A Python library for the Discord API.
 Author-email: Slipstream <me@slipstreamm.dev>
 License: BSD 3-Clause
@@ -23,6 +23,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp<4.0.0,>=3.9.0
+Requires-Dist: PyNaCl<2.0.0,>=1.5.0
 Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == "test"
 Requires-Dist: pytest-asyncio>=1.0.0; extra == "test"
@@ -37,6 +38,9 @@ A Python library for interacting with the Discord API, with a focus on bot devel
 
 ## Features
 
+- Internationalization helpers
+- Hybrid context for commands
+- Built-in rate limiting
 - Asynchronous design using `aiohttp`
 - Gateway and HTTP API clients
 - Slash command framework
@@ -56,6 +60,13 @@ pip install -e .
 
 Requires Python 3.10 or newer.
 
+To run the example scripts, you'll need the `python-dotenv` package to load
+environment variables. Install the development extras with:
+
+```bash
+pip install "disagreement[dev]"
+```
+
 ## Basic Usage
 
 ```python
@@ -64,6 +75,8 @@ import os
 
 import disagreement
 from disagreement.ext import commands
+from dotenv import load_dotenv
+load_dotenv()
 
 
 class Basics(commands.Cog):
@@ -72,18 +85,17 @@ class Basics(commands.Cog):
 
     @commands.command()
     async def ping(self, ctx: commands.CommandContext) -> None:
-        await ctx.reply("Pong!")
+        await ctx.reply(f"Pong! Gateway Latency: {self.client.latency_ms} ms.")
 
 
 token = os.getenv("DISCORD_BOT_TOKEN")
 if not token:
     raise RuntimeError("DISCORD_BOT_TOKEN environment variable not set")
 
-client = disagreement.Client(token=token, command_prefix="!")
-client.add_cog(Basics(client))
-
-
+intents = disagreement.GatewayIntent.default() | disagreement.GatewayIntent.MESSAGE_CONTENT
+client = disagreement.Client(token=token, command_prefix="!", intents=intents, mention_replies=True)
 async def main() -> None:
+    client.add_cog(Basics(client))
     await client.run()
 
 
@@ -135,6 +147,20 @@ These options are forwarded to ``HTTPClient`` when it creates the underlying
 ``aiohttp.ClientSession``. You can specify a custom ``connector`` or any other
 session parameter supported by ``aiohttp``.
 
+### Default Allowed Mentions
+
+Specify default mention behaviour for all outgoing messages when constructing the client:
+
+```python
+client = disagreement.Client(
+    token=token,
+    allowed_mentions={"parse": [], "replied_user": False},
+)
+```
+
+This dictionary is used whenever ``send_message`` is called without an explicit
+``allowed_mentions`` argument.
+
 ### Defining Subcommands with `AppCommandGroup`
 
 ```python
@@ -153,6 +179,7 @@ async def show(ctx: AppCommandContext, key: str):
 @slash_command(name="set", description="Update a setting.", parent=admin_group)
 async def set_setting(ctx: AppCommandContext, key: str, value: str):
     ...
+```
 ## Fetching Guilds
 
 Use `Client.fetch_guild` to retrieve a guild from the Discord API if it

{disagreement-0.2.0rc1 → disagreement-0.4.0}/README.md

@@ -4,6 +4,9 @@ A Python library for interacting with the Discord API, with a focus on bot devel
 
 ## Features
 
+- Internationalization helpers
+- Hybrid context for commands
+- Built-in rate limiting
 - Asynchronous design using `aiohttp`
 - Gateway and HTTP API clients
 - Slash command framework
@@ -23,6 +26,13 @@ pip install -e .
 
 Requires Python 3.10 or newer.
 
+To run the example scripts, you'll need the `python-dotenv` package to load
+environment variables. Install the development extras with:
+
+```bash
+pip install "disagreement[dev]"
+```
+
 ## Basic Usage
 
 ```python
@@ -31,6 +41,8 @@ import os
 
 import disagreement
 from disagreement.ext import commands
+from dotenv import load_dotenv
+load_dotenv()
 
 
 class Basics(commands.Cog):
@@ -39,18 +51,17 @@ class Basics(commands.Cog):
 
     @commands.command()
     async def ping(self, ctx: commands.CommandContext) -> None:
-        await ctx.reply("Pong!")
+        await ctx.reply(f"Pong! Gateway Latency: {self.client.latency_ms} ms.")
 
 
 token = os.getenv("DISCORD_BOT_TOKEN")
 if not token:
     raise RuntimeError("DISCORD_BOT_TOKEN environment variable not set")
 
-client = disagreement.Client(token=token, command_prefix="!")
-client.add_cog(Basics(client))
-
-
+intents = disagreement.GatewayIntent.default() | disagreement.GatewayIntent.MESSAGE_CONTENT
+client = disagreement.Client(token=token, command_prefix="!", intents=intents, mention_replies=True)
 async def main() -> None:
+    client.add_cog(Basics(client))
     await client.run()
 
 
@@ -102,6 +113,20 @@ These options are forwarded to ``HTTPClient`` when it creates the underlying
 ``aiohttp.ClientSession``. You can specify a custom ``connector`` or any other
 session parameter supported by ``aiohttp``.
 
+### Default Allowed Mentions
+
+Specify default mention behaviour for all outgoing messages when constructing the client:
+
+```python
+client = disagreement.Client(
+    token=token,
+    allowed_mentions={"parse": [], "replied_user": False},
+)
+```
+
+This dictionary is used whenever ``send_message`` is called without an explicit
+``allowed_mentions`` argument.
+
 ### Defining Subcommands with `AppCommandGroup`
 
 ```python
@@ -120,6 +145,7 @@ async def show(ctx: AppCommandContext, key: str):
 @slash_command(name="set", description="Update a setting.", parent=admin_group)
 async def set_setting(ctx: AppCommandContext, key: str, value: str):
     ...
+```
 ## Fetching Guilds
 
 Use `Client.fetch_guild` to retrieve a guild from the Discord API if it

{disagreement-0.2.0rc1 → disagreement-0.4.0}/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.2.0rc1"
+__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-0.2.0rc1 → disagreement-0.4.0}/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,
@@ -114,3 +133,21 @@ class FFmpegAudioSource(AudioSource):
         if isinstance(self.source, io.IOBase):
             with contextlib.suppress(Exception):
                 self.source.close()
+
+
+class AudioSink:
+    """Abstract base class for audio sinks."""
+
+    def write(self, user, data):
+        """Write a chunk of PCM audio.
+
+        Subclasses must implement this. The data is raw PCM at 48kHz
+        stereo.
+        """
+
+        raise NotImplementedError
+
+    def close(self) -> None:
+        """Cleanup the sink when the voice client disconnects."""
+
+        return None

disagreement-0.4.0/disagreement/cache.py

@@ -0,0 +1,94 @@
+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
+    from .caching import MemberCacheFlags
+
+T = TypeVar("T")
+
+
+class Cache(Generic[T]):
+    """Simple in-memory cache with optional TTL and max size support."""
+
+    def __init__(
+        self, ttl: Optional[float] = None, maxlen: Optional[int] = None
+    ) -> None:
+        self.ttl = ttl
+        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)
+        if not item:
+            return None
+        value, expiry = item
+        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:
+        self._data.pop(key, None)
+
+    def clear(self) -> None:
+        self._data.clear()
+
+    def values(self) -> list[T]:
+        now = time.monotonic()
+        items = []
+        for key, (value, expiry) in list(self._data.items()):
+            if expiry is not None and expiry < now:
+                self.invalidate(key)
+            else:
+                items.append(value)
+        return items
+
+
+class GuildCache(Cache["Guild"]):
+    """Cache specifically for :class:`Guild` objects."""
+
+
+class ChannelCache(Cache["Channel"]):
+    """Cache specifically for :class:`Channel` objects."""
+
+
+class MemberCache(Cache["Member"]):
+    """
+    A cache for :class:`Member` objects that respects :class:`MemberCacheFlags`.
+    """
+
+    def __init__(self, flags: MemberCacheFlags, ttl: Optional[float] = None) -> None:
+        super().__init__(ttl)
+        self.flags = flags
+
+    def _should_cache(self, member: Member) -> bool:
+        """Determines if a member should be cached based on the flags."""
+        if self.flags.all:
+            return True
+        if self.flags.none:
+            return False
+
+        if self.flags.online and member.status != "offline":
+            return True
+        if self.flags.voice and member.voice_state is not None:
+            return True
+        if self.flags.joined and getattr(member, "_just_joined", False):
+            return True
+        return False
+
+    def set(self, key: str, value: Member) -> None:
+        if self._should_cache(value):
+            super().set(key, value)

disagreement-0.4.0/disagreement/caching.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import operator
+from typing import Any, Callable, ClassVar, Dict, Iterator, Tuple
+
+
+class _MemberCacheFlagValue:
+    flag: int
+
+    def __init__(self, func: Callable[[Any], bool]):
+        self.flag = getattr(func, "flag", 0)
+        self.__doc__ = func.__doc__
+
+    def __get__(self, instance: "MemberCacheFlags", owner: type) -> Any:
+        if instance is None:
+            return self
+        return instance.value & self.flag != 0
+
+    def __set__(self, instance: Any, value: bool) -> None:
+        if value:
+            instance.value |= self.flag
+        else:
+            instance.value &= ~self.flag
+
+    def __repr__(self) -> str:
+        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)
+        return _MemberCacheFlagValue(func)
+
+    return decorator
+
+
+class MemberCacheFlags:
+    __slots__ = ("value",)
+
+    VALID_FLAGS: ClassVar[Dict[str, int]] = {
+        "joined": 1 << 0,
+        "voice": 1 << 1,
+        "online": 1 << 2,
+    }
+    DEFAULT_FLAGS: ClassVar[int] = 1 | 2 | 4
+    ALL_FLAGS: ClassVar[int] = sum(VALID_FLAGS.values())
+
+    def __init__(self, **kwargs: bool):
+        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.")
+            setattr(self, key, value)
+
+    @classmethod
+    def _from_value(cls, value: int) -> MemberCacheFlags:
+        self = cls.__new__(cls)
+        self.value = value
+        return self
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, MemberCacheFlags) and self.value == other.value
+
+    def __ne__(self, other: object) -> bool:
+        return not self.__eq__(other)
+
+    def __hash__(self) -> int:
+        return hash(self.value)
+
+    def __repr__(self) -> str:
+        return f"<MemberCacheFlags value={self.value}>"
+
+    def __iter__(self) -> Iterator[Tuple[str, bool]]:
+        for name in self.VALID_FLAGS:
+            yield name, getattr(self, name)
+
+    def __int__(self) -> int:
+        return self.value
+
+    def __index__(self) -> int:
+        return self.value
+
+    @classmethod
+    def all(cls) -> MemberCacheFlags:
+        """A factory method that creates a :class:`MemberCacheFlags` with all flags enabled."""
+        return cls._from_value(cls.ALL_FLAGS)
+
+    @classmethod
+    def none(cls) -> MemberCacheFlags:
+        """A factory method that creates a :class:`MemberCacheFlags` with all flags disabled."""
+        return cls._from_value(0)
+
+    @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"])
+
+    @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"])
+
+    @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"])
+
+    @flag_value(1 << 0)
+    def joined(self) -> bool:
+        """Whether to cache members that have just joined the guild."""
+        return False
+
+    @flag_value(1 << 1)
+    def voice(self) -> bool:
+        """Whether to cache members that are in a voice channel."""
+        return False
+
+    @flag_value(1 << 2)
+    def online(self) -> bool:
+        """Whether to cache members that are online."""
+        return False