scurrypy 0.1.0__tar.gz

scurrypy-0.1.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2025 Furmissile. All rights reserved.
+
+Derivative works are not permitted -- the source code is made available for educational and reference purposes only, and is not exempt from licensing.
+This software is provided on an "as-is" basis and the author is not responsible for any liability that may come from misuse.
+No commercial profit may be drawn off of derivatives of this software project for any reason.

scurrypy-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: scurrypy
+Version: 0.1.0
+Summary: Discord API Wrapper in Python
+Author: Furmissile
+Requires-Python: >=3.10
+License-File: LICENSE
+Dynamic: license-file

scurrypy-0.1.0/README.md

@@ -0,0 +1,12 @@
+# __Welcome to ScurryPy__
+Yet another Discord API wrapper in Python!
+
+While this wrapper is mainly used for various squirrel-related shenanigans, it can also be used for more generic bot purposes.
+
+## Features
+* Command and event handling
+* Declarative style using decorators
+* Supports both legacy and new features
+* Respects Discord's rate limits
+
+See the docs for more!

scurrypy-0.1.0/discord/__init__.py

@@ -0,0 +1,9 @@
+# discord
+
+from .logger import Logger
+from .client import Client
+from .intents import Intents, set_intents
+
+from .events import *
+from .resources import *
+from .parts import *

scurrypy-0.1.0/discord/client.py

@@ -0,0 +1,312 @@
+import asyncio
+
+from .logger import Logger
+from .gateway import GatewayClient
+from .http import HTTPClient
+from .intents import Intents
+from .error import DiscordError
+
+from .resources.guild import Guild
+from .resources.channel import Channel
+from .resources.message import Message
+from .resources.bot_emojis import BotEmojis
+from .resources.user import User
+from .resources.application import Application
+
+from .parts.command import SlashCommand, MessageCommand, UserCommand
+
+from .dispatch.event_dispatcher import EventDispatcher
+from .dispatch.prefix_dispatcher import PrefixDispatcher
+from .dispatch.command_dispatcher import CommandDispatcher
+
+class Client:
+    """Main entry point for Discord bots.
+        Ties together the moving parts: gateway, HTTP, event dispatching, command handling, and resource managers.
+    """
+    def __init__(self, 
+        *,
+        token: str,
+        application_id: int,
+        intents: int = Intents.DEFAULT,
+        debug_mode: bool = False,
+        prefix = None,
+        quiet: bool = False
+    ):
+        """
+        Args:
+            token (str): the bot's token
+            application_id (int): the bot's user ID
+            intents (int, optional): gateway intents. Defaults to Intents.DEFAULT.
+            debug_mode (bool, optional): toggle debug messages. Defaults to False.
+            prefix (str, optional): set message prefix if using command prefixes
+            quiet (bool, optional): if INFO, DEBUG, and WARN should be logged
+        """
+        self.token = token
+        self.application_id = application_id
+
+        self._logger = Logger(debug_mode, quiet)
+        self._ws = GatewayClient(token, intents, self._logger)
+        self._http = HTTPClient(token, self._logger)
+
+        if prefix and (intents & Intents.MESSAGE_CONTENT == 0):
+            self._logger.log_warn('Prefix set without message content enabled.')
+
+        self.dispatcher = EventDispatcher(self.application_id, self._http, self._logger)
+        self.prefix_dispatcher = PrefixDispatcher(self._http, self._logger, prefix)
+        self.command_dispatcher = CommandDispatcher(self.application_id, self._http, self._logger)
+
+        self._global_commands = [] # SlashCommand
+        self._guild_commands = {} # {guild_id : [commands], ...}
+
+        self._is_set_up = False
+        self._setup_hooks = []
+        
+        self.emojis = BotEmojis(self._http, self.application_id)
+
+    def prefix_command(self, func):
+        """Decorator registers prefix commands by the name of the function.
+
+        Args:
+            func (callable): callback handle for command response
+        """
+        self.prefix_dispatcher.register(func.__name__, func)
+
+    def component(self, func):
+        """Decorator registers a function for a component handler.
+
+        Args:
+            func (callable): callback handle for component response
+        """
+        self.command_dispatcher.component(func)
+
+    def command(self, command: SlashCommand | MessageCommand | UserCommand, guild_id: int = 0):
+        """Decorator registers a function for a command handler.
+
+        Args:
+            command (SlashCommand | MessageCommand | UserCommand): command to register
+            guild_id (int): ID of guild in which to register command (if a guild command)
+        """
+        def decorator(func):
+            # hash out command type
+            if isinstance(command, MessageCommand):
+                self.command_dispatcher.message_command(func)
+            elif isinstance(command, UserCommand):
+                self.command_dispatcher.user_command(func)
+            elif isinstance(command, SlashCommand):
+                self.command_dispatcher.command(func)
+            else:
+                raise ValueError(f'Command {func.__name__} expected to be of type SlashCommand, UserCommand, MessageCommand; \
+                    got {type(command).__name__}.')
+            
+            # then hash out if this command should be guild or global level
+            if guild_id != 0:
+                self._guild_commands.setdefault(guild_id, []).append(command)
+            else:
+                self._global_commands.append(command)
+        return decorator
+    
+    def event(self, event_name: str):
+        """Decorator registers a function for an event handler.
+
+        Args:
+            event_name (str): event name (must be a valid event)
+        """
+        def decorator(func):
+            self.dispatcher.register(event_name, func)
+            return func
+        return decorator
+    
+    def setup_hook(self, func):
+        """Decorator registers a setup hook.
+            (Runs once before the bot starts listening)
+
+        Args:
+            func (callable): callback to the setup function
+        """
+        self._setup_hooks.append(func)
+
+    def application_from_id(self, application_id: int):
+        """Creates an interactable application resource.
+
+        Args:
+            application_id (int): id of target application
+
+        Returns:
+            (Application): the Application resource
+        """
+        return Application(application_id, self._http)
+
+    def guild_from_id(self, guild_id: int):
+        """Creates an interactable guild resource.
+
+        Args:
+            guild_id (int): id of target guild
+
+        Returns:
+            (Guild): the Guild resource
+        """
+        return Guild(guild_id, self._http)
+
+    def channel_from_id(self, channel_id: int):
+        """Creates an interactable channel resource.
+
+        Args:
+            channel_id (int): id of target channel
+
+        Returns:
+            (Channel): the Channel resource
+        """
+        return Channel(channel_id, self._http)
+
+    def message_from_id(self, channel_id: int, message_id: int):
+        """Creates an interactable message resource.
+
+        Args:
+            message_id (int): id of target message
+            channel_id (int): channel id of target message
+
+        Returns:
+            (Message): the Message resource
+        """
+        return Message(message_id, channel_id, self._http)
+    
+    def user_from_id(self, user_id: int):
+        """Creates an interactable user resource.
+
+        Args:
+            user_id (int): id of target user
+
+        Returns:
+            (User): the User resource
+        """
+        return User(user_id, self._http)
+    
+    async def clear_guild_commands(self, guild_id: int):
+        """Clear a guild's slash commands.
+
+        Args:
+            guild_id (int): id of the target guild
+        """
+        if self._guild_commands.get(guild_id):
+            self._logger.log_info(f"Guild {guild_id} already queued, skipping clear.")
+            return
+
+        await self.command_dispatcher._register_guild_commands({guild_id: []})
+
+    async def _listen(self):
+        """Main event loop for incoming gateway requests."""
+        while True:
+            try:
+                message = await self._ws.receive()
+                if not message:
+                    raise ConnectionError("No message received.")
+
+                op_code = message.get('op')
+
+                if op_code == 0:
+                    dispatch_type = message.get('t')
+                    self._logger.log_info(f"DISPATCH -> {dispatch_type}")
+                    event_data = message.get('d')
+                    self._ws.sequence = message.get('s') or self._ws.sequence
+
+                    if dispatch_type == "READY":
+                        self._ws.session_id = event_data.get("session_id")
+                        self._ws.connect_url = event_data.get("resume_gateway_url", self._ws.connect_url)
+
+                    try:
+                        if self.prefix_dispatcher.prefix and dispatch_type == 'MESSAGE_CREATE':
+                            await self.prefix_dispatcher.dispatch(event_data)
+                            
+                        elif dispatch_type == 'INTERACTION_CREATE':
+                            await self.command_dispatcher.dispatch(event_data)
+
+                        await self.dispatcher.dispatch(dispatch_type, event_data)
+                    except DiscordError as e:
+                        if e.fatal:
+                            raise  # let run() handle fatal errors
+                        else:
+                            self._logger.log_warn(f"Recoverable DiscordError: {e}")
+                            continue  # keep listening
+
+                elif op_code == 7:
+                    raise ConnectionError("Reconnect requested by server.")
+                elif op_code == 9:
+                    self._ws.session_id = None
+                    self._ws.sequence = None
+                    raise ConnectionError("Invalid session.")
+            except asyncio.CancelledError:
+                raise
+            except DiscordError as e:
+                if e.fatal:
+                    raise  # propagate fatal errors
+                else:
+                    self._logger.log_warn(f"Recoverable DiscordError: {e}")
+            except ConnectionError as e:
+                self._logger.log_warn(f"Connection lost: {e}")
+                await self._ws.close()
+                await asyncio.sleep(2)
+
+    async def start(self):
+        """Runs the main lifecycle of the bot.
+            Handles connection setup, heartbeat management, event loop, and automatic reconnects.
+        """
+        while True:
+            try:
+                await self._http.start_session()
+                await self._ws.connect()
+                await self._ws.start_heartbeat()
+
+                if self._ws.session_id and self._ws.sequence:
+                    await self._ws.reconnect()
+                else:
+                    await self._ws.identify()
+
+                if not self._is_set_up:
+                    if self._setup_hooks:
+                        for hook in self._setup_hooks:
+                            self._logger.log_info(f"Setting hook {hook.__name__}")
+                            await hook()
+                        self._logger.log_high_priority("Hooks set up.")
+
+                    # register GUILD commands
+                    await self.command_dispatcher._register_guild_commands(self._guild_commands)
+
+                    # register GLOBAL commands
+                    await self.command_dispatcher._register_global_commands(self._global_commands)
+
+                    self._is_set_up = True
+
+                await self._listen()
+
+            except ConnectionError as e:
+                self._logger.log_warn("Connection lost. Attempting reconnect...")
+                await self._ws.close()
+                await asyncio.sleep(2)
+                continue
+            except asyncio.CancelledError:
+                self._logger.log_info("Cancelling connection...")
+                break
+            except DiscordError as e:
+                self._logger.log_error(f"Fatal DiscordError: {e}")
+                break
+            except Exception as e:
+                self._logger.log_error(f"Unspecified Error Type {type(e).__name__} - {e}")
+                break
+            finally:
+                await self._ws.close()
+                await self._http.close_session()
+
+    def run(self):
+        """Starts the bot.
+            Handles starting the session, WS, and heartbeat, reconnection logic,
+            setting up emojis and hooks, and then listens for gateway events.
+        """
+        try:
+            asyncio.run(self.start())
+        except KeyboardInterrupt:
+            self._logger.log_debug("Shutdown requested via KeyboardInterrupt.")
+        except Exception as e:
+            self._logger.log_error(f"{type(e).__name__} {e}")
+        finally:
+            self._logger.log_high_priority("Bot shutting down.")
+            self._logger.close()

scurrypy-0.1.0/discord/dispatch/__init__.py

@@ -0,0 +1 @@
+# discord/dispatch

scurrypy-0.1.0/discord/dispatch/command_dispatcher.py

@@ -0,0 +1,156 @@
+import asyncio
+
+from ..http import HTTPClient
+from ..logger import Logger
+
+from ..events.interaction_events import ApplicationCommandData, MessageComponentData, ModalData, InteractionEvent
+from ..resources.interaction import Interaction, InteractionDataTypes
+
+class InteractionTypes:
+    """Interaction types constants."""
+
+    APPLICATION_COMMAND = 2
+    """Slash command interaction."""
+
+    MESSAGE_COMPONENT = 3
+    """Message component interaction (e.g., button, select menu, etc.)."""
+
+    MODAL_SUBMIT = 5
+    """Modal submit interaction."""
+
+class CommandDispatcher:
+    """Central hub for registering and dispatching interaction responses."""
+
+    RESOURCE_MAP = { # maps discord events to their respective dataclass
+        InteractionTypes.APPLICATION_COMMAND: ApplicationCommandData,
+        InteractionTypes.MESSAGE_COMPONENT: MessageComponentData,
+        InteractionTypes.MODAL_SUBMIT: ModalData
+    }
+    """Maps [`InteractionTypes`][discord.dispatch.command_dispatcher.InteractionTypes] to their respective dataclass."""
+
+    def __init__(self, application_id: int, http: HTTPClient, logger: Logger):
+        self.application_id = application_id
+        """Bot's application ID."""
+
+        self._http = http
+        """HTTP session for requests."""
+
+        self._logger = logger
+        """Logger instance to log events."""
+
+        self._component_handlers = {}
+        """Mapping of component custom IDs to handler."""
+
+        self._handlers = {}
+        """Mapping of command names to handler."""
+
+        self._message_handlers = {}
+        """Mapping of message command names to handler."""
+
+        self._user_handlers = {}
+        """Mapping of user command names to handler."""
+
+    async def _register_guild_commands(self, commands: dict):
+        """Registers a command at the guild level.
+
+        Args:
+            commands (dict): mapping of guild IDs to respective serialized command data
+        """
+        
+        for guild_id, cmds in commands.items():
+            # register commands PER GUILD
+            await self._http.request(
+                'PUT', 
+                f"applications/{self.application_id}/guilds/{guild_id}/commands", 
+                [command._to_dict() for command in cmds]
+            )
+    
+    async def _register_global_commands(self, commands: list):
+        """Registers a command at the global/bot level. (ALL GUILDS)
+
+        Args:
+            commands (list): list of serialized commands
+        """
+
+        global_commands = [command._to_dict() for command in commands]
+
+        await self._http.request('PUT', f"applications/{self.application_id}/commands", global_commands)
+
+    def command(self, handler):
+        """Decorator to register slash commands.
+
+        Args:
+            handler (callable): callback handle for command response
+        """
+        self._handlers[handler.__name__] = handler
+
+    def component(self, handler):
+        """Decorator to register component interactions.
+
+        Args:
+            handler (callable): callback handle for component response
+        """
+        self._component_handlers[handler.__name__] = handler
+
+    def user_command(self, handler):
+        """Decorator to register user commands.
+
+        Args:
+            handler (callable): callback handle for user command response
+        """
+        self._user_handlers[handler.__name__] = handler
+
+    def message_command(self, handler):
+        """Decorator to register message commands.
+
+        Args:
+            handler (callable): callback handle for message command response
+        """
+        self._message_handlers[handler.__name__] = handler
+
+    async def dispatch(self, data: dict):
+        """Dispatch a response to an `INTERACTION_CREATE` event
+
+        Args:
+            data (dict): interaction data
+        """
+        event = InteractionEvent(interaction=Interaction.from_dict(data, self._http))
+
+        event_data_obj = self.RESOURCE_MAP.get(event.interaction.type)
+
+        if not event_data_obj:
+            return
+        
+        event.data = event_data_obj.from_dict(data.get('data'))
+        handler = None
+        name = None
+
+        match event.interaction.type:
+            case InteractionTypes.APPLICATION_COMMAND:
+                name = event.data.name
+
+                match event.data.type:
+                    case InteractionDataTypes.SLASH_COMMAND:
+                        handler = self._handlers.get(name)
+                    case InteractionDataTypes.USER_COMMAND:
+                        handler = self._user_handlers.get(name)
+                    case InteractionDataTypes.MESSAGE_COMMAND:
+                        handler = self._message_handlers.get(name)
+
+            case InteractionTypes.MESSAGE_COMPONENT:
+                name = event.data.custom_id
+                handler = self._component_handlers.get(name)
+
+            case InteractionTypes.MODAL_SUBMIT:
+                name = event.data.custom_id
+                handler = self._component_handlers.get(name)
+
+        if not handler:
+            self._logger.log_warn(f"No handler registered for interaction '{name}'")
+            return
+
+        try:
+            await handler(event) # NOTE: treat command options as args!
+            self._logger.log_info(f"Interaction Event '{name}' Acknowledged.")
+        except Exception as e:
+            self._logger.log_error(f"Error in interaction '{name}': {e}")

scurrypy-0.1.0/discord/dispatch/event_dispatcher.py

@@ -0,0 +1,85 @@
+from ..http import HTTPClient
+from ..logger import Logger
+
+from ..events.ready_event import *
+from ..events.reaction_events import *
+from ..events.guild_events import *
+from ..events.message_events import *
+from ..events.channel_events import *
+from ..events.interaction_events import *
+
+from ..resources.message import Message
+
+class EventDispatcher:
+    """Central hub for handling Discord Gateway events."""
+    RESOURCE_MAP = { # maps discord events to their respective dataclass
+        'READY': ReadyEvent,
+        
+        "MESSAGE_CREATE": MessageCreateEvent,
+        "MESSAGE_UPDATE": MessageUpdateEvent,
+        'MESSAGE_DELETE': MessageDeleteEvent,
+
+        'MESSAGE_REACTION_ADD': ReactionAddEvent,
+        'MESSAGE_REACTION_REMOVE': ReactionRemoveEvent,
+        'MESSAGE_REACTION_REMOVE_ALL': ReactionRemoveAllEvent,
+        'MESSAGE_REACTION_REMOVE_EMOJI': ReactionRemoveEmojiEvent,
+
+        'CHANNEL_CREATE': GuildChannelCreateEvent,
+        'CHANNEL_UPDATE': GuildChannelUpdateEvent,
+        'CHANNEL_DELETE': GuildChannelDeleteEvent,
+
+        'CHANNEL_PINS_UPDATE': ChannelPinsUpdateEvent,
+
+        'GUILD_CREATE': GuildCreateEvent,
+        'GUILD_UPDATE': GuildUpdateEvent,
+        'GUILD_DELETE': GuildDeleteEvent,
+
+        'INTERACTION_CREATE': InteractionEvent
+
+        # and other events...
+    }
+    """Mapping of event names to respective dataclass."""
+    
+    def __init__(self, application_id: int, http: HTTPClient, logger: Logger):
+        self.application_id = application_id
+        """Bot's ID."""
+
+        self._http = http
+        """HTTP session for requests."""
+
+        self._logger = logger
+        """HTTP session for requests"""
+
+        self._handlers = {}
+        """Mapping of event names to handler."""
+
+    def register(self, event_name: str, handler):
+        """Registers the given handler to the given event name.
+            (Event name must be a valid Discord event)
+
+        Args:
+            event_name (str): name of the event
+            handler (callable): callback to handle event
+        """
+        self._handlers[event_name] = handler
+
+    async def dispatch(self, event_name: str, data: dict):
+        """Hydrate the corresponding dataclass and call the handler.
+
+        Args:
+            event_name (str): name of the event
+            data (dict): Discord's raw event payload
+        """
+        cls = self.RESOURCE_MAP.get(event_name)
+        
+        if not cls:
+            return
+        
+        if isinstance(cls, Message) and cls.author.id == self.application_id:
+            return # ignore bot's own messages
+        
+        handler = self._handlers.get(event_name, None)
+        if handler:
+            obj = cls.from_dict(data, self._http)
+            await handler(obj)
+            self._logger.log_info(f"Event {event_name} Acknowledged.")

scurrypy-0.1.0/discord/dispatch/prefix_dispatcher.py

@@ -0,0 +1,53 @@
+from ..http import HTTPClient
+from ..logger import Logger
+
+from ..events.message_events import MessageCreateEvent
+
+from ..resources.message import Message
+from ..models.member import MemberModel
+
+class PrefixDispatcher:
+    """Handles text-based command messages that start with a specific prefix."""
+    def __init__(self, http: HTTPClient, logger: Logger, prefix: str):
+        self._http = http
+        """HTTP session for requests."""
+
+        self._logger = logger
+        """Logger instance to log events."""
+
+        self.prefix = prefix
+        """User-defined command prefix."""
+
+        self._handlers = {}
+        """Mapping of command prefix names to handler"""
+
+    def register(self, name: str, handler):
+        """Registers a handler for a command name (case-insensitive)
+
+        Args:
+            name (str): name of handler (and command)
+            handler (callable): handler callback
+        """
+        self._handlers[name.lower()] = handler
+
+    async def dispatch(self, data: dict):
+        """Hydrate the corresponding dataclass and call the handler.
+
+        Args:
+            data (dict): Discord's raw event payload
+        """
+        event = MessageCreateEvent(
+            guild_id=data.get('guild_id'),
+            message=Message.from_dict(data, self._http),
+            member=MemberModel.from_dict(data.get('member'))
+        )
+
+        if event.message._has_prefix(self.prefix):
+            command, *args = event.message._extract_args(self.prefix)
+            handler = self._handlers.get(command)
+            if handler:
+                try:
+                    await handler(event, *args)
+                    self._logger.log_info(f"Prefix Event '{command}' Acknowledged.")
+                except Exception as e:
+                    self._logger.log_error(f"Error in prefix command '{command}': {e}")