disagreement 0.0.1__py3-none-any.whl → 0.1.0rc1__py3-none-any.whl

disagreement/ext/commands/errors.py

@@ -0,0 +1,76 @@
+# disagreement/ext/commands/errors.py
+
+"""
+Custom exceptions for the command extension.
+"""
+
+from disagreement.errors import DisagreementException
+
+
+class CommandError(DisagreementException):
+    """Base exception for errors raised by the commands extension."""
+
+    pass
+
+
+class CommandNotFound(CommandError):
+    """Exception raised when a command is not found."""
+
+    def __init__(self, command_name: str):
+        self.command_name = command_name
+        super().__init__(f"Command '{command_name}' not found.")
+
+
+class BadArgument(CommandError):
+    """Exception raised when a command argument fails to parse or validate."""
+
+    pass
+
+
+class MissingRequiredArgument(BadArgument):
+    """Exception raised when a required command argument is missing."""
+
+    def __init__(self, param_name: str):
+        self.param_name = param_name
+        super().__init__(f"Missing required argument: {param_name}")
+
+
+class ArgumentParsingError(BadArgument):
+    """Exception raised during the argument parsing process."""
+
+    pass
+
+
+class CheckFailure(CommandError):
+    """Exception raised when a command check fails."""
+
+    pass
+
+
+class CheckAnyFailure(CheckFailure):
+    """Raised when :func:`check_any` fails all checks."""
+
+    def __init__(self, errors: list[CheckFailure]):
+        self.errors = errors
+        msg = "; ".join(str(e) for e in errors)
+        super().__init__(f"All checks failed: {msg}")
+
+
+class CommandOnCooldown(CheckFailure):
+    """Raised when a command is invoked while on cooldown."""
+
+    def __init__(self, retry_after: float):
+        self.retry_after = retry_after
+        super().__init__(f"Command is on cooldown. Retry in {retry_after:.2f}s")
+
+
+class CommandInvokeError(CommandError):
+    """Exception raised when an error occurs during command invocation."""
+
+    def __init__(self, original: Exception):
+        self.original = original
+        super().__init__(f"Error during command invocation: {original}")
+
+
+# Add more specific errors as needed, e.g., UserNotFound, ChannelNotFound, etc.
+# These might inherit from BadArgument.

disagreement/ext/commands/help.py

@@ -0,0 +1,37 @@
+# disagreement/ext/commands/help.py
+
+from typing import List, Optional
+
+from .core import Command, CommandContext, CommandHandler
+
+
+class HelpCommand(Command):
+    """Built-in command that displays help information for other commands."""
+
+    def __init__(self, handler: CommandHandler) -> None:
+        self.handler = handler
+
+        async def callback(ctx: CommandContext, command: Optional[str] = None) -> None:
+            if command:
+                cmd = handler.get_command(command)
+                if not cmd or cmd.name.lower() != command.lower():
+                    await ctx.send(f"Command '{command}' not found.")
+                    return
+                description = cmd.description or cmd.brief or "No description provided."
+                await ctx.send(f"**{ctx.prefix}{cmd.name}**\n{description}")
+            else:
+                lines: List[str] = []
+                for registered in dict.fromkeys(handler.commands.values()):
+                    brief = registered.brief or registered.description or ""
+                    lines.append(f"{ctx.prefix}{registered.name} - {brief}".strip())
+                if lines:
+                    await ctx.send("\n".join(lines))
+                else:
+                    await ctx.send("No commands available.")
+
+        super().__init__(
+            callback,
+            name="help",
+            brief="Show command help.",
+            description="Displays help for commands.",
+        )

disagreement/ext/commands/view.py

@@ -0,0 +1,103 @@
+# disagreement/ext/commands/view.py
+
+import re
+
+
+class StringView:
+    """
+    A utility class to help with parsing strings, particularly for command arguments.
+    It keeps track of the current position in the string and provides methods
+    to read parts of it.
+    """
+
+    def __init__(self, buffer: str):
+        self.buffer: str = buffer
+        self.original: str = buffer  # Keep original for error reporting if needed
+        self.index: int = 0
+        self.end: int = len(buffer)
+        self.previous: int = 0  # Index before the last successful read
+
+    @property
+    def remaining(self) -> str:
+        """Returns the rest of the string that hasn't been consumed."""
+        return self.buffer[self.index :]
+
+    @property
+    def eof(self) -> bool:
+        """Checks if the end of the string has been reached."""
+        return self.index >= self.end
+
+    def skip_whitespace(self) -> None:
+        """Skips any leading whitespace from the current position."""
+        while not self.eof and self.buffer[self.index].isspace():
+            self.index += 1
+
+    def get_word(self) -> str:
+        """
+        Reads a "word" from the current position.
+        A word is a sequence of non-whitespace characters.
+        """
+        self.skip_whitespace()
+        if self.eof:
+            return ""
+
+        self.previous = self.index
+        match = re.match(r"\S+", self.buffer[self.index :])
+        if match:
+            word = match.group(0)
+            self.index += len(word)
+            return word
+        return ""  # Should not happen if not eof and skip_whitespace was called
+
+    def get_quoted_string(self) -> str:
+        """
+        Reads a string enclosed in double quotes.
+        Handles escaped quotes inside the string.
+        """
+        self.skip_whitespace()
+        if self.eof or self.buffer[self.index] != '"':
+            return ""  # Or raise an error, or return None
+
+        self.previous = self.index
+        self.index += 1  # Skip the opening quote
+        result = []
+        escaped = False
+
+        while not self.eof:
+            char = self.buffer[self.index]
+            self.index += 1
+
+            if escaped:
+                result.append(char)
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                return "".join(result)  # Closing quote found
+            else:
+                result.append(char)
+
+        # If loop finishes, means EOF was reached before closing quote
+        # This is an error condition. Restore index and indicate failure.
+        self.index = self.previous
+        # Consider raising an error like UnterminatedQuotedStringError
+        return ""  # Or raise
+
+    def read_rest(self) -> str:
+        """Reads all remaining characters from the current position."""
+        self.skip_whitespace()
+        if self.eof:
+            return ""
+
+        self.previous = self.index
+        result = self.buffer[self.index :]
+        self.index = self.end
+        return result
+
+    def undo(self) -> None:
+        """Resets the current position to before the last successful read."""
+        self.index = self.previous
+
+    # Could add more methods like:
+    # peek() - look at next char without consuming
+    # match_regex(pattern) - consume if regex matches

disagreement/ext/loader.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from importlib import import_module
+import sys
+from types import ModuleType
+from typing import Dict
+
+__all__ = ["load_extension", "unload_extension", "reload_extension"]
+
+_loaded_extensions: Dict[str, ModuleType] = {}
+
+
+def load_extension(name: str) -> ModuleType:
+    """Load an extension by name.
+
+    The extension module must define a ``setup`` coroutine or function that
+    will be called after loading. Any value returned by ``setup`` is ignored.
+    """
+
+    if name in _loaded_extensions:
+        raise ValueError(f"Extension '{name}' already loaded")
+
+    module = import_module(name)
+
+    if not hasattr(module, "setup"):
+        raise ImportError(f"Extension '{name}' does not define a setup function")
+
+    module.setup()
+    _loaded_extensions[name] = module
+    return module
+
+
+def unload_extension(name: str) -> None:
+    """Unload a previously loaded extension."""
+
+    module = _loaded_extensions.pop(name, None)
+    if module is None:
+        raise ValueError(f"Extension '{name}' is not loaded")
+
+    if hasattr(module, "teardown"):
+        module.teardown()
+
+    sys.modules.pop(name, None)
+
+
+def reload_extension(name: str) -> ModuleType:
+    """Reload an extension by name.
+
+    This is a convenience wrapper around :func:`unload_extension` followed by
+    :func:`load_extension`.
+    """
+
+    unload_extension(name)
+    return load_extension(name)

disagreement/ext/tasks.py

@@ -0,0 +1,182 @@
+import asyncio
+import datetime
+from typing import Any, Awaitable, Callable, Optional
+
+__all__ = ["loop", "Task"]
+
+
+class Task:
+    """Simple repeating task."""
+
+    def __init__(
+        self,
+        coro: Callable[..., Awaitable[Any]],
+        *,
+        seconds: float = 0.0,
+        minutes: float = 0.0,
+        hours: float = 0.0,
+        delta: Optional[datetime.timedelta] = None,
+        time_of_day: Optional[datetime.time] = None,
+        on_error: Optional[Callable[[Exception], Awaitable[None]]] = None,
+    ) -> None:
+        self._coro = coro
+        self._task: Optional[asyncio.Task[None]] = None
+        if time_of_day is not None and (
+            seconds or minutes or hours or delta is not None
+        ):
+            raise ValueError("time_of_day cannot be used with an interval")
+
+        if delta is not None:
+            if not isinstance(delta, datetime.timedelta):
+                raise TypeError("delta must be a datetime.timedelta")
+            interval_seconds = delta.total_seconds()
+        else:
+            interval_seconds = seconds + minutes * 60.0 + hours * 3600.0
+
+        self._seconds = float(interval_seconds)
+        self._time_of_day = time_of_day
+        self._on_error = on_error
+
+    def _seconds_until_time(self) -> float:
+        assert self._time_of_day is not None
+        now = datetime.datetime.now()
+        target = datetime.datetime.combine(now.date(), self._time_of_day)
+        if target <= now:
+            target += datetime.timedelta(days=1)
+        return (target - now).total_seconds()
+
+    async def _run(self, *args: Any, **kwargs: Any) -> None:
+        try:
+            first = True
+            while True:
+                if self._time_of_day is not None:
+                    await asyncio.sleep(self._seconds_until_time())
+                elif not first:
+                    await asyncio.sleep(self._seconds)
+
+                try:
+                    await self._coro(*args, **kwargs)
+                except Exception as exc:  # noqa: BLE001
+                    if self._on_error is not None:
+                        await _maybe_call(self._on_error, exc)
+                    else:
+                        raise
+
+                first = False
+        except asyncio.CancelledError:
+            pass
+
+    def start(self, *args: Any, **kwargs: Any) -> asyncio.Task[None]:
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(self._run(*args, **kwargs))
+        return self._task
+
+    def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            self._task = None
+
+    @property
+    def running(self) -> bool:
+        return self._task is not None and not self._task.done()
+
+
+async def _maybe_call(
+    func: Callable[[Exception], Awaitable[None] | None], exc: Exception
+) -> None:
+    result = func(exc)
+    if asyncio.iscoroutine(result):
+        await result
+
+
+class _Loop:
+    def __init__(
+        self,
+        func: Callable[..., Awaitable[Any]],
+        *,
+        seconds: float = 0.0,
+        minutes: float = 0.0,
+        hours: float = 0.0,
+        delta: Optional[datetime.timedelta] = None,
+        time_of_day: Optional[datetime.time] = None,
+        on_error: Optional[Callable[[Exception], Awaitable[None]]] = None,
+    ) -> None:
+        self.func = func
+        self.seconds = seconds
+        self.minutes = minutes
+        self.hours = hours
+        self.delta = delta
+        self.time_of_day = time_of_day
+        self.on_error = on_error
+        self._task: Optional[Task] = None
+        self._owner: Any = None
+
+    def __get__(self, obj: Any, objtype: Any) -> "_BoundLoop":
+        return _BoundLoop(self, obj)
+
+    def _coro(self, *args: Any, **kwargs: Any) -> Awaitable[Any]:
+        if self._owner is None:
+            return self.func(*args, **kwargs)
+        return self.func(self._owner, *args, **kwargs)
+
+    def start(self, *args: Any, **kwargs: Any) -> asyncio.Task[None]:
+        self._task = Task(
+            self._coro,
+            seconds=self.seconds,
+            minutes=self.minutes,
+            hours=self.hours,
+            delta=self.delta,
+            time_of_day=self.time_of_day,
+            on_error=self.on_error,
+        )
+        return self._task.start(*args, **kwargs)
+
+    def stop(self) -> None:
+        if self._task is not None:
+            self._task.stop()
+
+    @property
+    def running(self) -> bool:
+        return self._task.running if self._task else False
+
+
+class _BoundLoop:
+    def __init__(self, parent: _Loop, owner: Any) -> None:
+        self._parent = parent
+        self._owner = owner
+
+    def start(self, *args: Any, **kwargs: Any) -> asyncio.Task[None]:
+        self._parent._owner = self._owner
+        return self._parent.start(*args, **kwargs)
+
+    def stop(self) -> None:
+        self._parent.stop()
+
+    @property
+    def running(self) -> bool:
+        return self._parent.running
+
+
+def loop(
+    *,
+    seconds: float = 0.0,
+    minutes: float = 0.0,
+    hours: float = 0.0,
+    delta: Optional[datetime.timedelta] = None,
+    time_of_day: Optional[datetime.time] = None,
+    on_error: Optional[Callable[[Exception], Awaitable[None]]] = None,
+) -> Callable[[Callable[..., Awaitable[Any]]], _Loop]:
+    """Decorator to create a looping task."""
+
+    def decorator(func: Callable[..., Awaitable[Any]]) -> _Loop:
+        return _Loop(
+            func,
+            seconds=seconds,
+            minutes=minutes,
+            hours=hours,
+            delta=delta,
+            time_of_day=time_of_day,
+            on_error=on_error,
+        )
+
+    return decorator

disagreement/gateway.py

@@ -10,6 +10,7 @@ import aiohttp
 import json
 import zlib
 import time
+import random
 from typing import Optional, TYPE_CHECKING, Any, Dict
 
 from .enums import GatewayOpcode, GatewayIntent
@@ -43,6 +44,8 @@ class GatewayClient:
         *,
         shard_id: Optional[int] = None,
         shard_count: Optional[int] = None,
+        max_retries: int = 5,
+        max_backoff: float = 60.0,
     ):
         self._http: "HTTPClient" = http_client
         self._dispatcher: "EventDispatcher" = event_dispatcher
@@ -52,6 +55,8 @@ class GatewayClient:
         self.verbose: bool = verbose
         self._shard_id: Optional[int] = shard_id
         self._shard_count: Optional[int] = shard_count
+        self._max_retries: int = max_retries
+        self._max_backoff: float = max_backoff
 
         self._ws: Optional[aiohttp.ClientWebSocketResponse] = None
         self._loop: asyncio.AbstractEventLoop = asyncio.get_event_loop()
@@ -63,10 +68,33 @@ class GatewayClient:
         self._keep_alive_task: Optional[asyncio.Task] = None
         self._receive_task: Optional[asyncio.Task] = None
 
+        self._last_heartbeat_sent: Optional[float] = None
+        self._last_heartbeat_ack: Optional[float] = None
+
         # For zlib decompression
         self._buffer = bytearray()
         self._inflator = zlib.decompressobj()
 
+    async def _reconnect(self) -> None:
+        """Attempts to reconnect using exponential backoff with jitter."""
+        delay = 1.0
+        for attempt in range(self._max_retries):
+            try:
+                await self.connect()
+                return
+            except Exception as e:  # noqa: BLE001
+                if attempt >= self._max_retries - 1:
+                    print(f"Reconnect failed after {attempt + 1} attempts: {e}")
+                    raise
+                jitter = random.uniform(0, delay)
+                wait_time = min(delay + jitter, self._max_backoff)
+                print(
+                    f"Reconnect attempt {attempt + 1} failed: {e}. "
+                    f"Retrying in {wait_time:.2f} seconds..."
+                )
+                await asyncio.sleep(wait_time)
+                delay = min(delay * 2, self._max_backoff)
+
     async def _decompress_message(
         self, message_bytes: bytes
     ) -> Optional[Dict[str, Any]]:
@@ -103,6 +131,7 @@ class GatewayClient:
 
     async def _heartbeat(self):
         """Sends a heartbeat to the Gateway."""
+        self._last_heartbeat_sent = time.monotonic()
         payload = {"op": GatewayOpcode.HEARTBEAT, "d": self._last_sequence}
         await self._send_json(payload)
         # print("Sent heartbeat.")
@@ -166,6 +195,7 @@ class GatewayClient:
         print(
             f"Sent RESUME for session {self._session_id} at sequence {self._last_sequence}."
         )
+
     async def update_presence(
         self,
         status: str,
@@ -179,14 +209,16 @@ class GatewayClient:
             "op": GatewayOpcode.PRESENCE_UPDATE,
             "d": {
                 "since": since,
-                "activities": [
-                    {
-                        "name": activity_name,
-                        "type": activity_type,
-                    }
-                ]
-                if activity_name
-                else [],
+                "activities": (
+                    [
+                        {
+                            "name": activity_name,
+                            "type": activity_type,
+                        }
+                    ]
+                    if activity_name
+                    else []
+                ),
                 "status": status,
                 "afk": afk,
             },
@@ -347,7 +379,7 @@ class GatewayClient:
             await self._heartbeat()
         elif op == GatewayOpcode.RECONNECT:  # Server requests a reconnect
             print("Gateway requested RECONNECT. Closing and will attempt to reconnect.")
-            await self.close(code=4000)  # Use a non-1000 code to indicate reconnect
+            await self.close(code=4000, reconnect=True)
         elif op == GatewayOpcode.INVALID_SESSION:
             # The 'd' payload for INVALID_SESSION is a boolean indicating resumability
             can_resume = data.get("d") is True
@@ -356,9 +388,7 @@ class GatewayClient:
                 self._session_id = None  # Clear session_id to force re-identify
                 self._last_sequence = None
             # Close and reconnect. The connect logic will decide to resume or identify.
-            await self.close(
-                code=4000 if can_resume else 4009
-            )  # 4009 for non-resumable
+            await self.close(code=4000 if can_resume else 4009, reconnect=True)
         elif op == GatewayOpcode.HELLO:
             hello_d_payload = data.get("d")
             if (
@@ -385,6 +415,7 @@ class GatewayClient:
                 print("Performing initial IDENTIFY.")
                 await self._identify()
         elif op == GatewayOpcode.HEARTBEAT_ACK:
+            self._last_heartbeat_ack = time.monotonic()
             # print("Received heartbeat ACK.")
             pass  # Good, connection is alive
         else:
@@ -403,13 +434,11 @@ class GatewayClient:
             print("Receive_loop task cancelled.")
         except aiohttp.ClientConnectionError as e:
             print(f"ClientConnectionError in receive_loop: {e}. Attempting reconnect.")
-            # This might be handled by an outer reconnect loop in the Client class
-            await self.close(code=1006)  # Abnormal closure
+            await self.close(code=1006, reconnect=True)  # Abnormal closure
         except Exception as e:
             print(f"Unexpected error in receive_loop: {e}")
             traceback.print_exc()
-            # Consider specific error types for more granular handling
-            await self.close(code=1011)  # Internal error
+            await self.close(code=1011, reconnect=True)
         finally:
             print("Receive_loop ended.")
             # If the loop ends unexpectedly (not due to explicit close),
@@ -457,7 +486,7 @@ class GatewayClient:
                 f"An unexpected error occurred during Gateway connection: {e}"
             ) from e
 
-    async def close(self, code: int = 1000):
+    async def close(self, code: int = 1000, *, reconnect: bool = False):
         """Closes the Gateway connection."""
         print(f"Closing Gateway connection with code {code}...")
         if self._keep_alive_task and not self._keep_alive_task.done():
@@ -468,11 +497,13 @@ class GatewayClient:
                 pass  # Expected
 
         if self._receive_task and not self._receive_task.done():
+            current = asyncio.current_task(loop=self._loop)
             self._receive_task.cancel()
-            try:
-                await self._receive_task
-            except asyncio.CancelledError:
-                pass  # Expected
+            if self._receive_task is not current:
+                try:
+                    await self._receive_task
+                except asyncio.CancelledError:
+                    pass  # Expected
 
         if self._ws and not self._ws.closed:
             await self._ws.close(code=code)
@@ -488,3 +519,18 @@ class GatewayClient:
             self._session_id = None
             self._last_sequence = None
             self._resume_gateway_url = None  # This might be re-fetched anyway
+
+    @property
+    def latency(self) -> Optional[float]:
+        """Returns the latency between heartbeat and ACK in seconds."""
+        if self._last_heartbeat_sent is None or self._last_heartbeat_ack is None:
+            return None
+        return self._last_heartbeat_ack - self._last_heartbeat_sent
+
+    @property
+    def last_heartbeat_sent(self) -> Optional[float]:
+        return self._last_heartbeat_sent
+
+    @property
+    def last_heartbeat_ack(self) -> Optional[float]:
+        return self._last_heartbeat_ack