scurrypy 0.3.0__tar.gz → 0.3.3__tar.gz

scurrypy-0.3.3/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: scurrypy
+Version: 0.3.3
+Summary: Discord API Wrapper in Python
+Author: Furmissile
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# __Welcome to ScurryPy__
+
+[![PyPI version](https://badge.fury.io/py/scurrypy.svg)](https://badge.fury.io/py/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
+
+## Some things to consider...
+* This is an early version — feedback, ideas, and contributions are very welcome! That said, there may be bumps along the way, so expect occasional bugs and quirks.
+* Certain features are not yet supported, while others are intentionally omitted. See the [docs](https://furmissile.github.io/scurrypy) for full details.
+
+## Getting Started
+*Note: This section also appears in the documentation, but here are complete examples ready to use with your bot credentials.*
+
+### Installation
+To install the ScurryPy package, run:
+```bash
+pip install scurrypy
+```
+
+### Minimal Slash Command
+The following demonstrates building and responding to a slash command.
+
+*Note: Adjust `dotenv_path` if your `.env` file is not in the same directory as this script.*
+
+```python
+import discord, os
+from dotenv import load_dotenv
+
+load_dotenv(dotenv_path='./path/to/env')
+
+client = discord.Client(
+    token=os.getenv("DISCORD_TOKEN"),
+    application_id=APPLICATION_ID  # replace with your bot's user ID
+)
+
+@client.command(
+    command=discord.SlashCommand(
+        name='example',
+        description='Demonstrate the minimal slash command!'
+    ),
+    guild_id=GUILD_ID  # must be a guild ID your bot is in
+)
+async def example(bot: discord.Client, event: discord.InteractionEvent):
+    await event.interaction.respond(f'Hello, {event.interaction.member.user.username}!')
+
+client.run()
+```
+
+### Minimal Prefix Command (Legacy)
+The following demonstrates building and responding to a message prefix command.
+
+```python
+import discord, os
+from dotenv import load_dotenv
+
+load_dotenv(dotenv_path='./path/to/env')
+
+client = discord.Client(
+    token=os.getenv("DISCORD_TOKEN"),
+    application_id=APPLICATION_ID,  # replace with your bot's user ID
+    intents=discord.set_intents(message_content=True),
+    prefix='!'  # your custom prefix
+)
+
+@client.prefix_command
+async def ping(bot: discord.Client, event: discord.MessageCreateEvent):
+    # The function name is the name of the command
+    await event.message.send("Pong!")
+
+client.run()
+```
+
+## Like what you see?
+Check out the full [documentation](https://furmissile.github.io/scurrypy) for more examples, guides, and API reference!

scurrypy-0.3.3/README.md

@@ -0,0 +1,82 @@
+# __Welcome to ScurryPy__
+
+[![PyPI version](https://badge.fury.io/py/scurrypy.svg)](https://badge.fury.io/py/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
+
+## Some things to consider...
+* This is an early version — feedback, ideas, and contributions are very welcome! That said, there may be bumps along the way, so expect occasional bugs and quirks.
+* Certain features are not yet supported, while others are intentionally omitted. See the [docs](https://furmissile.github.io/scurrypy) for full details.
+
+## Getting Started
+*Note: This section also appears in the documentation, but here are complete examples ready to use with your bot credentials.*
+
+### Installation
+To install the ScurryPy package, run:
+```bash
+pip install scurrypy
+```
+
+### Minimal Slash Command
+The following demonstrates building and responding to a slash command.
+
+*Note: Adjust `dotenv_path` if your `.env` file is not in the same directory as this script.*
+
+```python
+import discord, os
+from dotenv import load_dotenv
+
+load_dotenv(dotenv_path='./path/to/env')
+
+client = discord.Client(
+    token=os.getenv("DISCORD_TOKEN"),
+    application_id=APPLICATION_ID  # replace with your bot's user ID
+)
+
+@client.command(
+    command=discord.SlashCommand(
+        name='example',
+        description='Demonstrate the minimal slash command!'
+    ),
+    guild_id=GUILD_ID  # must be a guild ID your bot is in
+)
+async def example(bot: discord.Client, event: discord.InteractionEvent):
+    await event.interaction.respond(f'Hello, {event.interaction.member.user.username}!')
+
+client.run()
+```
+
+### Minimal Prefix Command (Legacy)
+The following demonstrates building and responding to a message prefix command.
+
+```python
+import discord, os
+from dotenv import load_dotenv
+
+load_dotenv(dotenv_path='./path/to/env')
+
+client = discord.Client(
+    token=os.getenv("DISCORD_TOKEN"),
+    application_id=APPLICATION_ID,  # replace with your bot's user ID
+    intents=discord.set_intents(message_content=True),
+    prefix='!'  # your custom prefix
+)
+
+@client.prefix_command
+async def ping(bot: discord.Client, event: discord.MessageCreateEvent):
+    # The function name is the name of the command
+    await event.message.send("Pong!")
+
+client.run()
+```
+
+## Like what you see?
+Check out the full [documentation](https://furmissile.github.io/scurrypy) for more examples, guides, and API reference!

scurrypy-0.3.3/discord/__init__.py

@@ -0,0 +1,223 @@
+# discord
+
+import importlib
+from typing import TYPE_CHECKING
+
+__all__ = [
+    # top-level
+    "Logger",
+    "Client",
+    "Intents",
+    "set_intents",
+    "BaseConfig",
+
+    # events
+    "ReadyEvent",
+    "ReactionAddEvent",
+    "ReactionRemoveEvent",
+    "ReactionRemoveEmojiEvent",
+    "ReactionRemoveAllEvent",
+    "GuildCreateEvent",
+    "GuildUpdateEvent",
+    "GuildDeleteEvent",
+    "MessageCreateEvent",
+    "MessageUpdateEvent",
+    "MessageDeleteEvent",
+    "GuildChannelCreateEvent",
+    "GuildChannelUpdateEvent",
+    "GuildChannelDeleteEvent",
+    "ChannelPinsUpdateEvent",
+    "InteractionEvent",
+
+    # models
+    "ApplicationModel",
+    "EmojiModel",
+    "GuildModel",
+    "MemberModel",
+    "UserModel",
+    "RoleModel",
+
+    # parts
+    "GuildChannel",
+    "Role",
+    "MessageBuilder",
+    "ModalBuilder",
+    "EmbedBuilder",
+    "ActionRow",
+    "StringSelect",
+    "UserSelect",
+    "RoleSelect",
+    "ChannelSelect",
+    "MentionableSelect",
+    "SlashCommand",
+    "MessageCommand",
+    "UserCommand",
+    "Container",
+    "Section",
+    "MediaGalleryItem",
+    "Label",
+
+    # resources
+    "Guild",
+    "Channel",
+    "Message",
+    "BotEmojis",
+    "User",
+    "Interaction",
+    "Application",
+]
+
+# For editor support / autocomplete
+if TYPE_CHECKING:
+    from .logger import Logger
+    from .client import Client
+    from .intents import Intents, set_intents
+    from .config import BaseConfig
+
+    # events
+    from .events.ready_event import ReadyEvent
+    from .events.reaction_events import (
+        ReactionAddEvent,
+        ReactionRemoveEvent,
+        ReactionRemoveEmojiEvent,
+        ReactionRemoveAllEvent,
+    )
+    from .events.guild_events import (
+        GuildCreateEvent,
+        GuildUpdateEvent,
+        GuildDeleteEvent,
+    )
+    from .events.message_events import (
+        MessageCreateEvent,
+        MessageUpdateEvent,
+        MessageDeleteEvent,
+    )
+    from .events.channel_events import (
+        GuildChannelCreateEvent,
+        GuildChannelUpdateEvent,
+        GuildChannelDeleteEvent,
+        ChannelPinsUpdateEvent,
+    )
+    from .events.interaction_events import InteractionEvent
+
+    # models
+    from .models.application import ApplicationModel
+    from .models.emoji import EmojiModel
+    from .models.guild import GuildModel
+    from .models.member import MemberModel
+    from .models.user import UserModel
+    from .models.role import RoleModel
+
+    # parts
+    from .parts.channel import GuildChannel
+    from .parts.role import Role
+    from .parts.message import MessageBuilder
+    from .parts.modal import ModalBuilder
+    from .parts.embed import EmbedBuilder
+    from .parts.action_row import (
+        ActionRow, 
+        StringSelect,
+        UserSelect,
+        RoleSelect,
+        ChannelSelect,
+        MentionableSelect
+    )
+
+    from .parts.command import (
+        SlashCommand, 
+        MessageCommand, 
+        UserCommand
+    )
+
+    from .parts.components_v2 import (
+        Container,
+        Section,
+        MediaGalleryItem,
+        Label
+    )
+
+    # resources
+    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.interaction import Interaction
+    from .resources.application import Application
+
+# Lazy loader
+def __getattr__(name: str):
+    if name not in __all__:
+        raise AttributeError(f"module {__name__} has no attribute {name}")
+
+    mapping = {
+        # top-level
+        "Logger": "discord.logger",
+        "Client": "discord.client",
+        "Intents": "discord.intents",
+        "set_intents": "discord.intents",
+        "BaseConfig": "discord.config",
+
+        # events
+        "ReadyEvent": "discord.events.ready_event",
+        "ReactionAddEvent": "discord.events.reaction_events",
+        "ReactionRemoveEvent": "discord.events.reaction_events",
+        "ReactionRemoveEmojiEvent": "discord.events.reaction_events",
+        "ReactionRemoveAllEvent": "discord.events.reaction_events",
+        "GuildCreateEvent": "discord.events.guild_events",
+        "GuildUpdateEvent": "discord.events.guild_events",
+        "GuildDeleteEvent": "discord.events.guild_events",
+        "MessageCreateEvent": "discord.events.message_events",
+        "MessageUpdateEvent": "discord.events.message_events",
+        "MessageDeleteEvent": "discord.events.message_events",
+        "GuildChannelCreateEvent": "discord.events.channel_events",
+        "GuildChannelUpdateEvent": "discord.events.channel_events",
+        "GuildChannelDeleteEvent": "discord.events.channel_events",
+        "ChannelPinsUpdateEvent": "discord.events.channel_events",
+        "InteractionEvent": "discord.events.interaction_events",
+
+        # models
+        'ApplicationModel': "discord.models.application",
+        'EmojiModel': "discord.models.emoji",
+        'GuildModel': "discord.models.guild",
+        'MemberModel': "discord.models.member",
+        'UserModel': "discord.models.user",
+        'RoleModel': "discord.models.role",
+
+        # parts
+        'GuildChannel': "discord.parts.channel",
+        'Role': "discord.parts.role",
+        'MessageBuilder': "discord.parts.message",
+        'ModalBuilder': "discord.parts.modal",
+        'EmbedBuilder': "discord.parts.embed",
+        'ActionRow': "discord.parts.action_row",
+        'StringSelect': "discord.parts.action_row",
+        'UserSelect': "discord.parts.action_row",
+        'RoleSelect': "discord.parts.action_row",
+        'ChannelSelect': "discord.parts.action_row",
+        'MentionableSelect': "discord.parts.action_row",
+        'SlashCommand': "discord.parts.command",
+        'MessageCommand': "discord.parts.command",
+        'UserCommand': "discord.parts.command",
+        'Container': "discord.parts.components_v2",
+        'Section': "discord.parts.components_v2",
+        'MediaGalleryItem': "discord.parts.components_v2",
+        'Label': "discord.parts.components_v2",
+
+        # resources
+        'Guild': "discord.resources.guild",
+        'Channel': "discord.resources.channel",
+        'Message': "discord.resources.message",
+        'BotEmojis': "discord.resources.bot_emojis",
+        'User': "discord.resources.user",
+        'Interaction': "discord.resources.interaction",
+        'Application': "discord.resources.application"
+    }
+
+    module = importlib.import_module(mapping[name])
+    attr = getattr(module, name)
+    globals()[name] = attr  # cache it for future lookups
+    return attr
+
+def __dir__():
+    return sorted(list(globals().keys()) + __all__)

{scurrypy-0.3.0 → scurrypy-0.3.3}/discord/client.py

@@ -1,26 +1,10 @@
-import asyncio
-
-from .logger import Logger
-from .gateway import GatewayClient
-from .http import HTTPClient
+from .config import BaseConfig
 from .intents import Intents
 from .error import DiscordError
-from .config import BaseConfig
 from .client_like import ClientLike
 
-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(ClientLike):
     """Main entry point for Discord bots.
         Ties together the moving parts: gateway, HTTP, event dispatching, command handling, and resource managers.
@@ -45,6 +29,14 @@ class Client(ClientLike):
             prefix (str, optional): set message prefix if using command prefixes
             quiet (bool, optional): if INFO, DEBUG, and WARN should be logged
         """
+        from .logger import Logger
+        from .gateway import GatewayClient
+        from .http import HTTPClient
+        from .resources.bot_emojis import BotEmojis
+        from .dispatch.event_dispatcher import EventDispatcher
+        from .dispatch.prefix_dispatcher import PrefixDispatcher
+        from .dispatch.command_dispatcher import CommandDispatcher
+
         self.token = token
         self.application_id = application_id
         self.config = config
@@ -100,13 +92,13 @@ class Client(ClientLike):
         def decorator(func):
             # hash out command type
             if isinstance(command, MessageCommand):
-                self.command_dispatcher.message_command(func)
+                self.command_dispatcher.message_command(command.name, func)
             elif isinstance(command, UserCommand):
-                self.command_dispatcher.user_command(func)
+                self.command_dispatcher.user_command(command.name, func)
             elif isinstance(command, SlashCommand):
-                self.command_dispatcher.command(func)
+                self.command_dispatcher.command(command.name, func)
             else:
-                raise ValueError(f'Command {func.__name__} expected to be of type SlashCommand, UserCommand, MessageCommand; \
+                raise ValueError(f'Command {command.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
@@ -154,6 +146,8 @@ class Client(ClientLike):
         Returns:
             (Application): the Application resource
         """
+        from .resources.application import Application
+
         return Application(application_id, self._http)
 
     def guild_from_id(self, guild_id: int):
@@ -165,6 +159,8 @@ class Client(ClientLike):
         Returns:
             (Guild): the Guild resource
         """
+        from .resources.guild import Guild
+
         return Guild(guild_id, self._http)
 
     def channel_from_id(self, channel_id: int):
@@ -176,6 +172,8 @@ class Client(ClientLike):
         Returns:
             (Channel): the Channel resource
         """
+        from .resources.channel import Channel
+
         return Channel(channel_id, self._http)
 
     def message_from_id(self, channel_id: int, message_id: int):
@@ -188,6 +186,8 @@ class Client(ClientLike):
         Returns:
             (Message): the Message resource
         """
+        from .resources.message import Message
+
         return Message(message_id, channel_id, self._http)
     
     def user_from_id(self, user_id: int):
@@ -199,6 +199,8 @@ class Client(ClientLike):
         Returns:
             (User): the User resource
         """
+        from .resources.user import User
+
         return User(user_id, self._http)
     
     async def clear_guild_commands(self, guild_id: int):
@@ -215,6 +217,8 @@ class Client(ClientLike):
 
     async def _listen(self):
         """Main event loop for incoming gateway requests."""
+        import asyncio
+
         while True:
             try:
                 message = await self._ws.receive()
@@ -270,6 +274,8 @@ class Client(ClientLike):
         """Runs the main lifecycle of the bot.
             Handles connection setup, heartbeat management, event loop, and automatic reconnects.
         """
+        import asyncio
+
         while True:
             try:
                 await self._http.start_session()
@@ -338,6 +344,8 @@ class Client(ClientLike):
             Handles starting the session, WS, and heartbeat, reconnection logic,
             setting up emojis and hooks, and then listens for gateway events.
         """
+        import asyncio
+        
         try:
             asyncio.run(self.start())
         except KeyboardInterrupt:

{scurrypy-0.3.0 → scurrypy-0.3.3}/discord/dispatch/command_dispatcher.py

@@ -78,39 +78,42 @@ class CommandDispatcher:
 
         await self._http.request('PUT', f"applications/{self.application_id}/commands", global_commands)
 
-    def command(self, handler):
+    def command(self, name: str, handler):
         """Decorator to register slash commands.
 
         Args:
+            name (str): name of the command to register
             handler (callable): callback handle for command response
         """
-        self._handlers[handler.__name__] = handler
-    
-    def component(self, func, custom_id: str):
-        """Decorator to register component interactions.
-
-        Args:
-            custom_id (str): Identifier of the component 
-                !!! warning "Important"
-                    Must match the `custom_id` set where the component was created.
-        """
-        self._component_handlers[custom_id] = func
+        self._handlers[name] = handler
 
-    def user_command(self, handler):
+    def user_command(self, name: str, handler):
         """Decorator to register user commands.
 
         Args:
+            name (str): name of the command to register
             handler (callable): callback handle for user command response
         """
-        self._user_handlers[handler.__name__] = handler
+        self._user_handlers[name] = handler
 
-    def message_command(self, handler):
+    def message_command(self, name: str, handler):
         """Decorator to register message commands.
 
         Args:
+            name (str): name of the command to register
             handler (callable): callback handle for message command response
         """
-        self._message_handlers[handler.__name__] = handler
+        self._message_handlers[name] = handler
+
+    def component(self, func, custom_id: str):
+        """Decorator to register component interactions.
+
+        Args:
+            custom_id (str): Identifier of the component 
+                !!! warning "Important"
+                    Must match the `custom_id` set where the component was created.
+        """
+        self._component_handlers[custom_id] = func
 
     async def dispatch(self, data: dict):
         """Dispatch a response to an `INTERACTION_CREATE` event

{scurrypy-0.3.0 → scurrypy-0.3.3}/discord/dispatch/event_dispatcher.py

@@ -1,42 +1,19 @@
+from importlib import import_module
 from ..client_like import ClientLike
 
-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
+    RESOURCE_MAP = { # maps discord events to their respective dataclass (lazy loading)
+        'READY': ('discord.events.ready_event', 'ReadyEvent'),
 
+        'MESSAGE_CREATE': ('discord.events.message_events', 'MessageCreateEvent')
+        
         # and other events...
     }
+    
     """Mapping of event names to respective dataclass."""
     
     def __init__(self, client: ClientLike):
@@ -75,9 +52,21 @@ class EventDispatcher:
             event_name (str): name of the event
             data (dict): Discord's raw event payload
         """
-        cls = self.RESOURCE_MAP.get(event_name)
+        module_info = self.RESOURCE_MAP.get(event_name)
+        
+        if not module_info:
+            return
         
+        module_name, class_name = module_info
+
+        module = import_module(module_name)
+        if not module:
+            print(f"Cannot find module '{module_name}'!")
+            return
+
+        cls = getattr(module, class_name)
         if not cls:
+            print(f"Cannot find class '{class_name}'!")
             return
         
         if isinstance(cls, Message) and cls.author.id == self.application_id:

scurrypy-0.3.3/discord/events/__init__.py

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

{scurrypy-0.3.0 → scurrypy-0.3.3}/discord/events/guild_events.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from ..models import MemberModel
+from ..models.member import MemberModel
 from ..resources.channel import Channel
 
 @dataclass

{scurrypy-0.3.0 → scurrypy-0.3.3}/discord/logger.py

@@ -1,6 +1,3 @@
-from datetime import datetime
-import copy
-
 class Logger:
     """A utility class for logging messages, supporting log levels, color-coded console output, 
         optional file logging, and redaction of sensitive information. 
@@ -51,6 +48,8 @@ class Logger:
         Returns:
             (str): timestamp formatted in YYYY-MM-DD HH:MM:SS
         """
+        from datetime import datetime
+        
         return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
     
     def _log(self, level: str, color: str, message: str):
@@ -140,6 +139,8 @@ class Logger:
                 return [_redact(item) for item in obj]
             return obj
 
+        import copy
+
         return _redact(copy.deepcopy(data))
     
     def close(self):