disagreement 0.0.1__py3-none-any.whl → 0.0.2__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,43 @@
+from __future__ import annotations
+
+from importlib import import_module
+import sys
+from types import ModuleType
+from typing import Dict
+
+__all__ = ["load_extension", "unload_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)

disagreement/ext/tasks.py

@@ -0,0 +1,89 @@
+import asyncio
+from typing import Any, Awaitable, Callable, Optional
+
+__all__ = ["loop", "Task"]
+
+
+class Task:
+    """Simple repeating task."""
+
+    def __init__(self, coro: Callable[..., Awaitable[Any]], *, seconds: float) -> None:
+        self._coro = coro
+        self._seconds = float(seconds)
+        self._task: Optional[asyncio.Task[None]] = None
+
+    async def _run(self, *args: Any, **kwargs: Any) -> None:
+        try:
+            while True:
+                await self._coro(*args, **kwargs)
+                await asyncio.sleep(self._seconds)
+        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()
+
+
+class _Loop:
+    def __init__(self, func: Callable[..., Awaitable[Any]], seconds: float) -> None:
+        self.func = func
+        self.seconds = seconds
+        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)
+        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) -> Callable[[Callable[..., Awaitable[Any]]], _Loop]:
+    """Decorator to create a looping task."""
+
+    def decorator(func: Callable[..., Awaitable[Any]]) -> _Loop:
+        return _Loop(func, seconds)
+
+    return decorator

disagreement/gateway.py

@@ -166,6 +166,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 +180,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,
             },

{disagreement-0.0.1.dist-info → disagreement-0.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: disagreement
-Version: 0.0.1
+Version: 0.0.2
 Summary: A Python library for the Discord API.
 Author-email: Slipstream <me@slipstreamm.dev>
 License: BSD 3-Clause
@@ -60,29 +60,33 @@ Requires Python 3.11 or newer.
 ```python
 import asyncio
 import os
+
 import disagreement
+from disagreement.ext import commands
+
+
+class Basics(commands.Cog):
+    def __init__(self, client: disagreement.Client) -> None:
+        super().__init__(client)
+
+    @commands.command()
+    async def ping(self, ctx: commands.CommandContext) -> None:
+        await ctx.reply("Pong!")
+
+
+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))
 
-# Ensure DISCORD_BOT_TOKEN is set in your environment
-client = disagreement.Client(token=os.environ.get("DISCORD_BOT_TOKEN"))
-
-@client.on_event('MESSAGE_CREATE')
-async def on_message(message: disagreement.Message):
-    print(f"Received: {message.content} from {message.author.username}")
-    if message.content.lower() == '!ping':
-        await message.reply('Pong!')
-
-async def main():
-    if not client.token:
-        print("Error: DISCORD_BOT_TOKEN environment variable not set.")
-        return
-    try:
-        async with client:
-            await asyncio.Future()  # run until cancelled
-    except KeyboardInterrupt:
-        print("Bot shutting down...")
-    # Add any other specific exception handling from your library, e.g., disagreement.AuthenticationError
-
-if __name__ == '__main__':
+
+async def main() -> None:
+    await client.run()
+
+
+if __name__ == "__main__":
     asyncio.run(main())
 ```
 
@@ -117,21 +121,20 @@ setup_logging(logging.DEBUG, file="bot.log")
 ### Defining Subcommands with `AppCommandGroup`
 
 ```python
-from disagreement.ext.app_commands import AppCommandGroup
+from disagreement.ext.app_commands import AppCommandGroup, slash_command
+from disagreement.ext.app_commands.context import AppCommandContext
 
-settings = AppCommandGroup("settings", "Manage settings")
+settings_group = AppCommandGroup("settings", "Manage settings")
+admin_group = AppCommandGroup("admin", "Admin settings", parent=settings_group)
 
-@settings.command(name="show")
-async def show(ctx):
-    """Displays a setting."""
+
+@slash_command(name="show", description="Display a setting.", parent=settings_group)
+async def show(ctx: AppCommandContext, key: str):
     ...
 
-@settings.group("admin", description="Admin settings")
-def admin_group():
-    pass
 
-@admin_group.command(name="set")
-async def set_setting(ctx, key: str, value: str):
+@slash_command(name="set", description="Update a setting.", parent=admin_group)
+async def set_setting(ctx: AppCommandContext, key: str, value: str):
     ...
 ## Fetching Guilds
 
@@ -161,3 +164,7 @@ Contributions are welcome! Please open an issue or submit a pull request.
 
 See the [docs](docs/) directory for detailed guides on components, slash commands, caching, and voice features.
 
+## License
+
+This project is licensed under the BSD 3-Clause license. See the [LICENSE](LICENSE) file for details.
+

{disagreement-0.0.1.dist-info → disagreement-0.0.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-disagreement/__init__.py,sha256=ylGJLwgNmt7B71khVq2O0fG__4kjnkA35rZFX5tEDrk,907
+disagreement/__init__.py,sha256=EHUd2pLLOoobJJ9HD_Vw0us5BbOshMKNvjl7toEVBp8,907
 disagreement/cache.py,sha256=juabGFl4naQih5OUIVN2aN-vAfw2ZC2cI38s4nGEn8U,1525
 disagreement/client.py,sha256=pFXj7z7R1kJWz3_GWOzDYrF1S-nQ1agjcXnRTSh-PWE,45820
 disagreement/components.py,sha256=W_R9iMETkQj6sr-Lzk2n7hLwLNaLWT4vBPArIPHQUNc,5232
@@ -6,7 +6,7 @@ disagreement/enums.py,sha256=LLeXdYKcx4TUhlojNV5X4NDuvscMbnteWRNW79d0C2c,9668
 disagreement/error_handler.py,sha256=c2lb6aTMnhTtITQuR6axZUtEaasYKUgmdSxAHEkeq50,1028
 disagreement/errors.py,sha256=rCr9jVAzK8wsS6mxieeWpffKhTDX--sHuOBz45kwsAA,3215
 disagreement/event_dispatcher.py,sha256=BevGAi72qXAHN_FqCOSdvVhOhINLeI2ojyVLmvrSKJ0,9851
-disagreement/gateway.py,sha256=V46WyZE1duVEvVcBYsaThWd60Xg9T2Qsqu9Y02rQwXo,21315
+disagreement/gateway.py,sha256=85WSEZregWUvuc0M-DjErOCJM697mqHwdRw9Iz-w7aU,21384
 disagreement/http.py,sha256=1lHIEq2RRVOzzSpfj9TNGprJsMW_nhbj_8-fPr0IupI,23986
 disagreement/hybrid_context.py,sha256=VYCmcreTZdPBU9v-Cy48W38vgWO2t8nM2ulC6_z4HjU,1095
 disagreement/i18n.py,sha256=1L4rcFuKP0XjHk9dVwbNh4BkLk2ZlxxZ_-tecGWa9S0,718
@@ -19,14 +19,31 @@ disagreement/rate_limiter.py,sha256=ubwR_UTPs2MotipBdtqpgwQKx0IHt2I3cdfFcXTFv7g,
 disagreement/shard_manager.py,sha256=R0HXruJ0Wda_3ftTztQx7kpI182jyuAMsjU6fDtz8Us,2039
 disagreement/typing.py,sha256=_1oFWfZ4HyH5Q3bnF7CO24s79z-3_B5Qb69kWiwLhhU,1242
 disagreement/voice_client.py,sha256=KdFEH8PI6v45olTYoW_-DVOuTCk8SGg7BgSzxOQsILs,3869
+disagreement/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+disagreement/ext/loader.py,sha256=Gl2Btaimw_Tm159zLhni9f_Q7pXhOAA4uEpolB4mGAI,1128
+disagreement/ext/tasks.py,sha256=nlsmpHAhbITKe2Rp-jM8KWdruykNf1MTRrSrXdFMWUE,2671
+disagreement/ext/app_commands/__init__.py,sha256=DQ3vHz2EaJ_hTlvFRpRSofPlCuFueRoLgLriECI5xFg,991
+disagreement/ext/app_commands/commands.py,sha256=cY9gyXovnyBIEWmhUPe8YZfw_WXCA1qXWDWTMmX_Vm8,24095
+disagreement/ext/app_commands/context.py,sha256=Xcm4Ka5K5uTQGviixF5LeCDdOdF9YQS5F7lZi2m--8s,20831
+disagreement/ext/app_commands/converters.py,sha256=J1VEmo-7H9K7kGPJodu5FX4RmFFI1BuzhlQAEs2MsD4,21036
+disagreement/ext/app_commands/decorators.py,sha256=smgx5RHedmgn7wxhBza78rQo5Guz8PEDDOvK5niJlMc,23236
+disagreement/ext/app_commands/handler.py,sha256=XO9yLgcV7aIxzhTMgFcQ1Tbr4GRZRfDBzkIAkiu6mw8,26045
+disagreement/ext/commands/__init__.py,sha256=Yw--e6mhE_qjgNg1qYM4yvRAOZfZD6avQ_IOGH0IQxA,1051
+disagreement/ext/commands/cog.py,sha256=U57yMrUpqj3_-W1-koyfGgH43MZG_JzJOl46kTur7iA,6636
+disagreement/ext/commands/converters.py,sha256=mh8xJr1FIiah6bdYy0KsdccfYcPii2Yc_IdhzCTw5uE,5864
+disagreement/ext/commands/core.py,sha256=CoX38qL-5WIola_KnShb3Za-uZSLhpfBW1pPkHw2f84,18905
+disagreement/ext/commands/decorators.py,sha256=ca06AuRznoe4ZTma9EmO-lw9kQRliOHWlQcpURb840o,5525
+disagreement/ext/commands/errors.py,sha256=cG5sPA-osUq2gts5scrl5yT-BHEYVHLTb4TULjAmbaY,2065
+disagreement/ext/commands/help.py,sha256=yw0ydupOsPwmnhsIIoxa93xjj9MAcBcGfD8BXa7V8G8,1456
+disagreement/ext/commands/view.py,sha256=3Wo4gGJX9fb65qw8yHFwMjnAeJvMJAx19rZNHz-ZDUs,3315
 disagreement/ui/__init__.py,sha256=PLA6eHiq9cu7JDOKS-7MKtaFhlqswjbI4AEUlpnbgO0,307
 disagreement/ui/button.py,sha256=GHbY3-yMrvv6u674-qYONocuC1e2a0flEWjPKwJXKDo,3163
 disagreement/ui/item.py,sha256=bm-EmQEZpe8Kt8JrRw-o0uQdccgjErORcFsBqaXOcV8,1112
 disagreement/ui/modal.py,sha256=FLWFy_VkZ9UAPumX3Q_bT0q7M06O1Q7XzBLhCZyhYhI,4120
 disagreement/ui/select.py,sha256=XjWRlWkA09QZaDDLn-wDDOWIuj0Mb4VCWJEOAaExZXw,3018
 disagreement/ui/view.py,sha256=QhWoYt39QKXwl1X6Mkm5gNNEqd8bt7O505lSpiG0L04,5567
-disagreement-0.0.1.dist-info/licenses/LICENSE,sha256=zfmtgJhVFHnqT7a8LAQFthXu5bP7EEHmEL99trV66Ew,1474
-disagreement-0.0.1.dist-info/METADATA,sha256=r9liBFa4OLtdW91XF2A7yJ7VcaOiBkmRbKVG74NEsHc,4533
-disagreement-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-disagreement-0.0.1.dist-info/top_level.txt,sha256=t7FY_3iaYhdB6X6y9VybJ2j7UZbVeRUe9wRgH8d5Gtk,13
-disagreement-0.0.1.dist-info/RECORD,,
+disagreement-0.0.2.dist-info/licenses/LICENSE,sha256=zfmtgJhVFHnqT7a8LAQFthXu5bP7EEHmEL99trV66Ew,1474
+disagreement-0.0.2.dist-info/METADATA,sha256=8Sc8qa3lQKVkXWV-9TbXV-fDi0gbWjrOm0a0pPlFTTg,4645
+disagreement-0.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+disagreement-0.0.2.dist-info/top_level.txt,sha256=t7FY_3iaYhdB6X6y9VybJ2j7UZbVeRUe9wRgH8d5Gtk,13
+disagreement-0.0.2.dist-info/RECORD,,