disagreement 0.2.0rc1__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.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/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/cache.py

@@ -2,23 +2,32 @@ 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
+    from .models import Channel, Guild, Member
+    from .caching import MemberCacheFlags
 
 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)
@@ -28,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:
@@ -53,3 +63,32 @@ class GuildCache(Cache["Guild"]):
 
 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/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