scurrypy 0.3.4.3__tar.gz → 0.4.1__tar.gz

scurrypy-0.4.1/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2025 Furmissile. All rights reserved.
+
+Permission is granted to view, use, modify, and distribute copies of this software
+and its source code, provided that:
+
+1. Attribution to the original author, Furmissile, is preserved in all copies and
+   derivative works.
+2. The name "ScurryPy" and associated branding may not be used to promote derived
+   projects without explicit permission.
+3. This license and copyright notice must be included in all copies or substantial
+   portions of the software.
+4. This software is provided "as is", without warranty of any kind, express or
+   implied. The author assumes no liability for any damages arising from its use.
+
+5. This software may not be used for commercial purposes without written consent 
+    from the author.

scurrypy-0.4.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: scurrypy
+Version: 0.4.1
+Summary: Dataclass-driven 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)
+
+> **Official Repository**  
+> This is the original and official repository of **ScurryPy**, maintained by [Furmissile](https://github.com/Furmissile).  
+> Forks and community extensions are welcome under the project’s license and attribution guidelines.
+
+A dataclass-driven 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.*
+
+```py
+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_ids=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.
+```py
+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()
+```
+
+## Contribution and Fork Policy
+ScurryPy follows a simple philosophy: **clarity, simplicity, and direct interaction with the Discord API**.
+It favors explicit, dataclass-driven design over heavy abstraction — and contributions should stay true to that style.
+
+This is a community-supported project guided by the design and principles of **Furmissile**.
+You are welcome to explore, modify, and extend the codebase under the terms of its license — but please follow these guidelines to ensure proper attribution and clarity.
+
+### You May
+* Fork this repository for personal or collaborative development.
+* Submit pull requests for bug fixes or new features that align with ScurryPy’s goals.
+* Reuse parts of the code in your own projects, provided attribution is preserved.
+
+### You May NOT
+* Remove or alter existing copyright notices or attributions.
+* Present a fork as the official ScurryPy project.
+* Use the name “ScurryPy” or its documentation to promote a fork without permission.
+
+If you plan to make substantial changes or release your own variant:
+* Rename the fork to avoid confusion (e.g., `scurrypy-plus` or `scurrypy-extended`).
+* Add a note in your README acknowledging the original project:
+> "This project is a fork of [ScurryPy](https://github.com/Furmissile/scurrypy)
+ by Furmissile."
+
+ ## License
+ This project is licensed under the Furmissile License, which allows viewing, modification, and redistribution with proper attribution.
+
+See the [License](./LICENSE) for details.
+
+## Like What You See?
+Check out the full [documentation](https://furmissile.github.io/scurrypy)
+ for more examples, guides, and API reference!

scurrypy-0.4.1/README.md

@@ -0,0 +1,120 @@
+# __Welcome to ScurryPy__
+
+[![PyPI version](https://badge.fury.io/py/scurrypy.svg)](https://badge.fury.io/py/scurrypy)
+
+> **Official Repository**  
+> This is the original and official repository of **ScurryPy**, maintained by [Furmissile](https://github.com/Furmissile).  
+> Forks and community extensions are welcome under the project’s license and attribution guidelines.
+
+A dataclass-driven 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.*
+
+```py
+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_ids=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.
+```py
+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()
+```
+
+## Contribution and Fork Policy
+ScurryPy follows a simple philosophy: **clarity, simplicity, and direct interaction with the Discord API**.
+It favors explicit, dataclass-driven design over heavy abstraction — and contributions should stay true to that style.
+
+This is a community-supported project guided by the design and principles of **Furmissile**.
+You are welcome to explore, modify, and extend the codebase under the terms of its license — but please follow these guidelines to ensure proper attribution and clarity.
+
+### You May
+* Fork this repository for personal or collaborative development.
+* Submit pull requests for bug fixes or new features that align with ScurryPy’s goals.
+* Reuse parts of the code in your own projects, provided attribution is preserved.
+
+### You May NOT
+* Remove or alter existing copyright notices or attributions.
+* Present a fork as the official ScurryPy project.
+* Use the name “ScurryPy” or its documentation to promote a fork without permission.
+
+If you plan to make substantial changes or release your own variant:
+* Rename the fork to avoid confusion (e.g., `scurrypy-plus` or `scurrypy-extended`).
+* Add a note in your README acknowledging the original project:
+> "This project is a fork of [ScurryPy](https://github.com/Furmissile/scurrypy)
+ by Furmissile."
+
+ ## License
+ This project is licensed under the Furmissile License, which allows viewing, modification, and redistribution with proper attribution.
+
+See the [License](./LICENSE) for details.
+
+## Like What You See?
+Check out the full [documentation](https://furmissile.github.io/scurrypy)
+ for more examples, guides, and API reference!

{scurrypy-0.3.4.3 → scurrypy-0.4.1}/discord/client.py

@@ -228,9 +228,9 @@ class Client(ClientLike):
             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.")
+            self._logger.log_warn(f"Guild {guild_id} already queued, skipping clear.")
             return
-
+        
         self._guild_commands[guild_id] = []
 
     async def _listen(self):
@@ -268,7 +268,7 @@ class Client(ClientLike):
                         self._ws.sequence = None
                         raise ConnectionError("Invalid session.")
                     case 11:
-                        self._logger.log_debug("Heartbeat ACK received")
+                        self._logger.log_info("Heartbeat ACK received")
 
             except asyncio.CancelledError:
                 break
@@ -281,13 +281,17 @@ class Client(ClientLike):
             except ConnectionError as e:
                 self._logger.log_warn(f"Connection lost: {e}")
                 raise
+            except Exception as e:
+                self._logger.log_error(f"{type(e).__name__} - {e}")
+                self._logger.log_traceback()
+                continue
 
-    async def start(self):
+    async def _start(self):
         """Runs the main lifecycle of the bot.
             Handles connection setup, heartbeat management, event loop, and automatic reconnects.
         """
         try:
-            await self._http.start_session()
+            await self._http.start()
             await self._ws.connect()
             await self._ws.start_heartbeat()
 
@@ -347,7 +351,7 @@ class Client(ClientLike):
 
         # Close HTTP before gateway since it's more important
         self._logger.log_debug("Closing HTTP session...")
-        await self._http.close_session()
+        await self._http.close()
 
         # Then try websocket with short timeout
         try:
@@ -362,11 +366,12 @@ class Client(ClientLike):
             setting up emojis and hooks, and then listens for gateway events.
         """        
         try:
-            asyncio.run(self.start())
+            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}")
+            self._logger.log_traceback()
         finally:
             self._logger.log_high_priority("Bot shutting down.")
             self._logger.close()

{scurrypy-0.3.4.3 → scurrypy-0.4.1}/discord/dispatch/command_dispatcher.py

@@ -64,7 +64,7 @@ class CommandDispatcher:
             await self._http.request(
                 'PUT', 
                 f"applications/{self.application_id}/guilds/{guild_id}/commands", 
-                [command._to_dict() for command in cmds]
+                data=[command._to_dict() for command in cmds]
             )
     
     async def _register_global_commands(self, commands: list):
@@ -76,7 +76,7 @@ class CommandDispatcher:
 
         global_commands = [command._to_dict() for command in commands]
 
-        await self._http.request('PUT', f"applications/{self.application_id}/commands", global_commands)
+        await self._http.request('PUT', f"applications/{self.application_id}/commands", data=global_commands)
 
     def command(self, name: str, handler):
         """Decorator to register slash commands.
@@ -161,3 +161,4 @@ class CommandDispatcher:
             self._logger.log_info(f"Interaction Event '{name}' Acknowledged.")
         except Exception as e:
             self._logger.log_error(f"Error in interaction '{name}': {e}")
+            self._logger.log_traceback()

{scurrypy-0.3.4.3 → scurrypy-0.4.1}/discord/dispatch/event_dispatcher.py

@@ -43,7 +43,7 @@ class EventDispatcher:
         """HTTP session for requests."""
 
         self._logger = client._logger
-        """HTTP session for requests"""
+        """Logger instance to log events."""
 
         self.config = client.config
         """User-defined bot config for persistent data."""

{scurrypy-0.3.4.3 → scurrypy-0.4.1}/discord/dispatch/prefix_dispatcher.py

@@ -57,3 +57,8 @@ class PrefixDispatcher:
                     self._logger.log_info(f"Prefix Event '{command}' Acknowledged.")
                 except Exception as e:
                     self._logger.log_error(f"Error in prefix command '{command}': {e}")
+
+                    if self._logger.dev_mode:
+                        import traceback
+                        traceback.print_exc()
+                        print("-----------------------------------\n")

{scurrypy-0.3.4.3 → scurrypy-0.4.1}/discord/events/interaction_events.py

@@ -126,11 +126,13 @@ class ModalData(DataModel):
             if custom_id != component.component.custom_id:
                 continue
 
-            match component.component.type:
-                case 3: # string select -> values
-                    return component.component.values
-                case 4: # text input -> value
-                    return component.component.value
+            t = component.component.type
+
+            if t in [3,5,6,7,8]: # select menus (w. possibly many option selects!)
+                return component.component.values
+            
+            # text input
+            return component.component.value
 
         raise ValueError(f"Component custom id '{custom_id}' not found.")
 

{scurrypy-0.3.4.3 → scurrypy-0.4.1}/discord/gateway.py

@@ -67,7 +67,6 @@ class GatewayClient:
 
         if message:
             data: dict = json.loads(message)
-            self._logger.log_debug(f"Received: {DISCORD_OP_CODES.get(data.get('op'))} - {json.dumps(data, indent=4)}")
             self._logger.log_info(f"Received: {DISCORD_OP_CODES.get(data.get('op'))}")
             return data
 
@@ -79,7 +78,6 @@ class GatewayClient:
         Args:
             message (dict): the message to send
         """
-        self._logger.log_debug(f"Sending payload: {message}")
         await self.ws.send(json.dumps(message))
 
     async def send_heartbeat_loop(self):
@@ -90,8 +88,7 @@ class GatewayClient:
             await asyncio.sleep(self.heartbeat_interval / 1000)
             hb_data = {"op": 1, "d": self.sequence}
             await self.send(hb_data)
-            self._logger.log_debug(f"Sending: {hb_data}")
-            self._logger.log_info("Heartbeat sent.")
+            self._logger.log_debug(f"Sent HEARTBEAT: {hb_data}")
 
     async def identify(self):
         """Sends the IDENIFY payload (token, intents, connection properties).
@@ -111,7 +108,7 @@ class GatewayClient:
         }
         await self.send(i)
         log_i = self._logger.redact(i)
-        self._logger.log_debug(f"Sending: {log_i}")
+        self._logger.log_debug(f"Sent IDENTIFY: {log_i}")
         self._logger.log_high_priority("Identify sent.")
     
     async def start_heartbeat(self):

scurrypy-0.4.1/discord/http.py

@@ -0,0 +1,213 @@
+import aiohttp
+import aiofiles
+import asyncio
+import json
+
+from typing import Any, Optional
+
+from .logger import Logger
+
+class HTTPException(Exception):
+    """Represents an HTTP error response from Discord."""
+    def __init__(self, response: aiohttp.ClientResponse, message: str):
+        self.response = response
+        self.status = response.status
+        self.text = message
+        super().__init__(f"{response.status}: {message}")
+
+class HTTPClient:
+    BASE = "https://discord.com/api/v10"
+    MAX_RETRIES = 3
+
+    def __init__(self, token: str, logger: Logger):
+        self.token = token
+        self.session: Optional[aiohttp.ClientSession] = None
+        self.logger = logger
+        self.global_reset = 0.0
+        self.global_lock = asyncio.Lock()
+        self.endpoint_to_bucket: dict[str, str] = {}
+        self.queues: dict[str, asyncio.Queue] = {}
+        self.workers: dict[str, asyncio.Task] = {}
+
+    async def start(self):
+        """Start the HTTP session."""
+        if not self.session:
+            self.session = aiohttp.ClientSession(
+                headers={"Authorization": f"Bot {self.token}"}
+            )
+
+    async def close(self):
+        """Close the HTTP session."""
+        for task in self.workers.values():
+            task.cancel()
+        if self.session and not self.session.closed:
+            await self.session.close()
+
+    async def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        data: Any | None = None,
+        params: dict | None = None,
+        files: Any | None = None,
+    ):
+        """Enqueues request WRT rate-limit buckets.
+
+        Args:
+            method (str): HTTP method (e.g., POST, GET, DELETE, PATCH, etc.)
+            endpoint (str): Discord endpoint (e.g., /channels/123/messages)
+            data (dict, optional): relevant data
+            params (dict, optional): relevant query params
+            files (list[str], optional): relevant files
+
+        Returns:
+            (Future): future with response
+        """
+        if not self.session:
+            await self.start()
+
+        bucket = self.endpoint_to_bucket.get(endpoint, endpoint)
+        queue = self.queues.setdefault(bucket, asyncio.Queue())
+        future = asyncio.get_event_loop().create_future()
+
+        await queue.put((method, endpoint, data, params, files, future))
+        if bucket not in self.workers:
+            self.workers[bucket] = asyncio.create_task(self._worker(bucket))
+
+        return await future
+
+    async def _worker(self, bucket: str):
+        """Processes request from specific rate-limit bucket."""
+
+        q = self.queues[bucket]
+        while self.session:
+            method, endpoint, data, params, files, future = await q.get()
+            try:
+                result = await self._send(method, endpoint, data, params, files)
+                if not future.done():
+                    future.set_result(result)
+            except Exception as e:
+                if not future.done():
+                    future.set_exception(e)
+            finally:
+                q.task_done()
+
+    async def _send(
+        self,
+        method: str,
+        endpoint: str,
+        data: Any | None,
+        params: dict | None,
+        files: Any | None,
+    ):
+        """Core HTTP request executor.
+
+        Sends a request to Discord, handling JSON payloads, files, query parameters,
+        rate limits, and retries.
+
+        Args:
+            method (str): HTTP method (e.g., 'POST', 'GET', 'DELETE', 'PATCH').
+            endpoint (str): Discord API endpoint (e.g., '/channels/123/messages').
+            data (dict | None, optional): JSON payload to include in the request body.
+            params (dict | None, optional): Query parameters to append to the URL.
+            files (list[str] | None, optional): Files to send with the request.
+
+        Raises:
+            (HTTPException): If the request fails after the maximum number of retries
+                        or receives an error response.
+
+        Returns:
+            (dict | str | None): Parsed JSON response if available, raw text if the
+                            response is not JSON, or None for HTTP 204 responses.
+        """
+
+        url = f"{self.BASE.rstrip('/')}/{endpoint.lstrip('/')}"
+
+        def sanitize_query_params(params: dict | None) -> dict | None:
+            if not params:
+                return None
+            return {k: ('true' if v is True else 'false' if v is False else v)
+                    for k, v in params.items() if v is not None}
+
+        for attempt in range(self.MAX_RETRIES):
+            await self._check_global_limit()
+
+            kwargs = {}
+
+            if files and any(files):
+                payload, headers = await self._make_payload(data, files)
+                kwargs = {"data": payload, "headers": headers}
+            else:
+                kwargs = {"json": data}
+
+            try:
+                async with self.session.request(
+                    method, url, params=sanitize_query_params(params), timeout=15, **kwargs
+                ) as resp:
+                    if resp.status == 429:
+                        data = await resp.json()
+                        retry = float(data.get("retry_after", 1))
+                        if data.get("global"):
+                            self.global_reset = asyncio.get_event_loop().time() + retry
+                        self.logger.log_warn(
+                            f"Rate limited {retry}s ({'global' if data.get('global') else 'bucket'})"
+                        )
+                        await asyncio.sleep(retry + 0.5)
+                        continue
+
+                    if 200 <= resp.status < 300:
+                        if resp.status == 204:
+                            return None
+                        try:
+                            return await resp.json()
+                        except aiohttp.ContentTypeError:
+                            return await resp.text()
+
+                    text = await resp.text()
+                    raise HTTPException(resp, text)
+
+            except asyncio.TimeoutError:
+                self.logger.log_warn(f"Timeout on {method} {endpoint}, retrying...")
+                continue
+
+        raise HTTPException(resp, f"Failed after {self.MAX_RETRIES} retries")
+
+    async def _check_global_limit(self):
+        """Waits if the global rate-limit is in effect."""
+
+        now = asyncio.get_event_loop().time()
+        if now < self.global_reset:
+            delay = self.global_reset - now
+            self.logger.log_warn(f"Global rate limit active, sleeping {delay:.2f}s")
+            await asyncio.sleep(delay)
+
+    async def _make_payload(self, data: dict, files: list):
+        """Return (data, headers) for aiohttp request — supports multipart.
+
+        Args:
+            data (dict): request data
+            files (list): relevant files
+
+        Returns:
+            (tuple[aiohttp.FormData, dict]): form data and headers
+        """
+        headers = {}
+        if not files:
+            return data, headers
+
+        form = aiohttp.FormData()
+        if data:
+            form.add_field("payload_json", json.dumps(data))
+
+        for idx, file_path in enumerate(files):
+            async with aiofiles.open(file_path, 'rb') as f:
+                data = await f.read()
+            form.add_field(
+                f'files[{idx}]',
+                data,
+                filename=file_path.split('/')[-1],
+                content_type='application/octet-stream'
+            )
+
+        return form, headers

{scurrypy-0.3.4.3 → scurrypy-0.4.1}/discord/logger.py

@@ -35,6 +35,7 @@ class Logger:
             """Log file for writing."""
         except Exception as e:
             self.log_error(f"Error {type(e)}: {e}")
+            self.log_traceback()
 
         self.dev_mode = dev_mode
         """If debug logs should be printed."""
@@ -52,6 +53,11 @@ class Logger:
         
         return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
     
+    def log_traceback(self):
+        if self.dev_mode == True:
+            import traceback
+            self._log("DEBUG", self.DEBUG, traceback.format_exc())
+    
     def _log(self, level: str, color: str, message: str):
         """Internal helper that writes formatted log to both file and console.