scurrypy 0.8.5.1__tar.gz

scurrypy-0.8.5.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.8.5.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: scurrypy
+Version: 0.8.5.1
+Summary: Dataclass-driven Discord API Wrapper in Python
+Author: Furmissile
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: websockets>=11.0.0
+Dynamic: license-file
+
+## __<center> ScurryPy </center>__
+
+[![PyPI version](https://badge.fury.io/py/scurrypy.svg)](https://badge.fury.io/py/scurrypy)
+
+A lightweight, fully readable Discord API framework built to accommodate everything from basic bots to custom frameworks.
+
+While ScurryPy powers many squirrel-related shenanigans, it works just as well for game bots, interactive components, and educational projects.
+
+## Philosophy
+
+ScurryPy is built on a simple idea: clarity over magic.
+
+* Every operation should be traceable.
+* No hidden behavior or side effects.
+* Explicit design over clever abstractions.
+* If you can’t explain a function in 3–6 steps, simplify it.
+* Legacy features can be removed or replaced without rewriting the library.
+* Models = pure data
+* Resources = HTTP logic
+* Nothing mixes responsibilities.
+
+ScurryPy is not discord.py, hikari, disnake, or any other framework.
+ScurryPy is built from scratch.
+It is a true Discord API wrapper built on predictable, modern Python principles.
+
+## Features
+* Easy to extend and build frameworks on top
+* Lightweight core (<1000 lines)
+* Command, and event handling
+* Unix shell-style wildcards for component routing
+* Declarative style using decorators
+* Supports both legacy and new features
+* Respects Discord's rate limits
+* No `__future__` hacks to avoid circular import
+* Capable of sharding
+
+## 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
+```
+
+> **About the Following Examples**:
+    These examples are built using [EasyBot](https://scurry-works.github.io/scurrypy/addons/easy_bot), an extension of ScurryPy designed with pre-packaged convenience!
+
+## Minimal Slash Command
+
+The following demonstrates building and responding to a slash command.
+
+```py
+import scurrypy 
+from scurrypy.addons.easy_bot import EasyBot
+
+client = EasyBot(token=TOKEN, application_id=APP_ID)
+
+@client.slash_command("hello", "Say hello", guild_ids=GUILD_ID) # specify guild ID for guild command
+async def hello(bot, interaction: scurrypy.Interaction):
+    await interaction.respond("Hello!")
+
+client.run()
+```
+
+## Minimal Prefix Command (Legacy)
+
+The following demonstrates building and responding to a message prefix command.
+
+```py
+import scurrypy 
+from scurrypy.addons.easy_bot import EasyBot
+
+client = EasyBot(token=TOKEN, application_id=APP_ID, prefix="!")
+
+@client.prefix("ping")
+async def ping_cmd(bot, message: scurrypy.Message):
+    await message.send("Pong!")
+
+client.run()
+```
+
+## Building on Top of ScurryPy
+
+ScurryPy is designed to be easy to extend with your own abstractions.
+See [Addons](https://scurry-works.github.io/scurrypy/addons) documentation for details!
+
+## Like What You See?
+Explore the full [documentation](https://scurry-works.github.io/scurrypy) for more examples, guides, and API reference.

scurrypy-0.8.5.1/README.md

@@ -0,0 +1,92 @@
+## __<center> ScurryPy </center>__
+
+[![PyPI version](https://badge.fury.io/py/scurrypy.svg)](https://badge.fury.io/py/scurrypy)
+
+A lightweight, fully readable Discord API framework built to accommodate everything from basic bots to custom frameworks.
+
+While ScurryPy powers many squirrel-related shenanigans, it works just as well for game bots, interactive components, and educational projects.
+
+## Philosophy
+
+ScurryPy is built on a simple idea: clarity over magic.
+
+* Every operation should be traceable.
+* No hidden behavior or side effects.
+* Explicit design over clever abstractions.
+* If you can’t explain a function in 3–6 steps, simplify it.
+* Legacy features can be removed or replaced without rewriting the library.
+* Models = pure data
+* Resources = HTTP logic
+* Nothing mixes responsibilities.
+
+ScurryPy is not discord.py, hikari, disnake, or any other framework.
+ScurryPy is built from scratch.
+It is a true Discord API wrapper built on predictable, modern Python principles.
+
+## Features
+* Easy to extend and build frameworks on top
+* Lightweight core (<1000 lines)
+* Command, and event handling
+* Unix shell-style wildcards for component routing
+* Declarative style using decorators
+* Supports both legacy and new features
+* Respects Discord's rate limits
+* No `__future__` hacks to avoid circular import
+* Capable of sharding
+
+## 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
+```
+
+> **About the Following Examples**:
+    These examples are built using [EasyBot](https://scurry-works.github.io/scurrypy/addons/easy_bot), an extension of ScurryPy designed with pre-packaged convenience!
+
+## Minimal Slash Command
+
+The following demonstrates building and responding to a slash command.
+
+```py
+import scurrypy 
+from scurrypy.addons.easy_bot import EasyBot
+
+client = EasyBot(token=TOKEN, application_id=APP_ID)
+
+@client.slash_command("hello", "Say hello", guild_ids=GUILD_ID) # specify guild ID for guild command
+async def hello(bot, interaction: scurrypy.Interaction):
+    await interaction.respond("Hello!")
+
+client.run()
+```
+
+## Minimal Prefix Command (Legacy)
+
+The following demonstrates building and responding to a message prefix command.
+
+```py
+import scurrypy 
+from scurrypy.addons.easy_bot import EasyBot
+
+client = EasyBot(token=TOKEN, application_id=APP_ID, prefix="!")
+
+@client.prefix("ping")
+async def ping_cmd(bot, message: scurrypy.Message):
+    await message.send("Pong!")
+
+client.run()
+```
+
+## Building on Top of ScurryPy
+
+ScurryPy is designed to be easy to extend with your own abstractions.
+See [Addons](https://scurry-works.github.io/scurrypy/addons) documentation for details!
+
+## Like What You See?
+Explore the full [documentation](https://scurry-works.github.io/scurrypy) for more examples, guides, and API reference.

scurrypy-0.8.5.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scurrypy"
+version = "0.8.5.1"
+
+description = "Dataclass-driven Discord API Wrapper in Python"
+readme = "README.md"
+authors = [{ name = "Furmissile" }]
+requires-python = ">=3.10"
+dependencies = [
+  "aiohttp>=3.8.0",
+  "websockets>=11.0.0"
+]
+
+[tool.setuptools]
+packages = [
+  "scurrypy",
+  "scurrypy.events",
+  "scurrypy.addons",
+  "scurrypy.resources",
+  "scurrypy.parts", 
+  "scurrypy.core",
+  "scurrypy.models"
+]

scurrypy-0.8.5.1/scurrypy/__init__.py

@@ -0,0 +1,16 @@
+# scurrypy
+
+from .client import Client
+
+__all__ = [
+    # top-level modules
+    "Client"
+]
+
+# imports listed  __all__ libs
+from .events import *
+from .parts import *
+from .resources import *
+from .models import *
+from .core import *
+from .addons import *

scurrypy-0.8.5.1/scurrypy/addons/__init__.py

@@ -0,0 +1,7 @@
+# scurrypy/plugins
+
+from .addon import Addon
+
+__all__ = [
+    "Addon"
+]

scurrypy-0.8.5.1/scurrypy/addons/addon.py

@@ -0,0 +1,6 @@
+class Addon:
+    """Defines the minimal setup for an addon."""
+
+    def setup(self): 
+        """Called when adding the child addon."""
+        raise NotImplementedError("Missing setup function.")

scurrypy-0.8.5.1/scurrypy/addons/addon_manager.py

@@ -0,0 +1,79 @@
+import inspect
+from ..core.base_client import BaseClient
+from .addon import Addon
+
+class AddonManager:
+    """Defines constraits for custom addons."""
+
+    def __init__(self, client: BaseClient):
+        self.client = client
+
+    # --- validation ---
+
+    def _check_event(self, handler):
+        """Inspects the addon's event handler.
+
+        Args:
+            handler (callable): addon's handler
+
+        Raises:
+            TypeError: invalid parameters
+        """
+        sig = inspect.signature(handler)
+        if len(sig.parameters) != 1:
+            raise TypeError(
+                f"Addon listener '{handler.__name__}' must accept exactly one arg (event)."
+            )
+
+    def _check_hook(self, handler):
+        """Inspects the addon's hook handler.
+
+        Args:
+            handler (callable): addon's handler
+
+        Raises:
+            TypeError: invalid parameters
+        """
+        sig = inspect.signature(handler)
+        if len(sig.parameters) != 0:
+            raise TypeError(
+                f"Addon hook '{handler.__name__}' must accept no parameters."
+            )
+
+    # --- registration ---
+
+    def add(self, addon: Addon):
+        """Helper function to auto-register an addon on instantiation.
+
+        Args:
+            addon (Addon): the addon object
+        """
+        addon.setup()
+
+    def add_event_listener(self, event_name: str, handler):
+        """Register an addon's handler to an event name to receive the event.
+
+        Args:
+            event_name (str): name of event to receive
+            handler (callable): addon's handler
+        """
+        self._check_event(handler)
+        self.client.add_event_listener(event_name, handler)
+
+    def add_startup_hook(self, handler):
+        """Register an addon's handler to run on startup.
+
+        Args:
+            handler (callable): addon's handler
+        """
+        self._check_hook(handler)
+        self.client.add_startup_hook(handler)
+
+    def add_shutdown_hook(self, handler):
+        """Register an addon's handler to run on shutdown.
+
+        Args:
+            handler (callable): addon's handler
+        """
+        self._check_hook(handler)
+        self.client.add_shutdown_hook(handler)

scurrypy-0.8.5.1/scurrypy/addons/component_builder.py

@@ -0,0 +1,253 @@
+from .addon import Addon
+
+from ..parts.components import *
+
+class ComponentBuilder(Addon):
+
+    @staticmethod
+    def _basic_button(style: int, custom_id: str, label: str = None, emoji: str | EmojiModel = None, disabled: bool = False):
+        if emoji:
+            if isinstance(emoji, str):
+                emoji = EmojiModel(name=emoji)
+            elif not isinstance(emoji, EmojiModel):
+                raise TypeError(f"EasyBot.primary expects type str or EmojiModel, got {type(emoji).__name__}")
+        
+        return Button(
+            style=style,
+            custom_id=custom_id,
+            label=label,
+            emoji=emoji ,
+            disabled=disabled
+        )
+    
+    @staticmethod
+    def primary(custom_id: str, label: str = None, emoji: str | EmojiModel = None, disabled: bool = False):
+        """Builds a primary button
+
+        Args:
+            custom_id (str): unique button identifier
+            label (str, optional): user-facing label
+            emoji (str | EmojiModel, optional): emoji icon as str or EmojiModel if custom
+            disabled (bool, optional): Whether the button should be disabled. Defaults to False.
+
+        Returns:
+            (Button): the button object
+        """
+        return ComponentBuilder._basic_button(ButtonStyles.PRIMARY, custom_id, label, emoji, disabled)
+    
+    @staticmethod
+    def secondary(custom_id: str, label: str = None, emoji: str | EmojiModel = None, disabled: bool = False):
+        """Builds a secondary button
+
+        Args:
+            custom_id (str): unique button identifier
+            label (str, optional): user-facing label
+            emoji (str | EmojiModel, optional): emoji icon as str or EmojiModel if custom
+            disabled (bool, optional): Whether the button should be disabled. Defaults to False.
+
+        Returns:
+            (Button): the button object
+        """
+        return ComponentBuilder._basic_button(ButtonStyles.SECONDARY, custom_id, label, emoji, disabled)
+    
+    @staticmethod
+    def success(custom_id: str, label: str = None, emoji: str | EmojiModel = None, disabled: bool = False):
+        """Builds a success button
+
+        Args:
+            custom_id (str): unique button identifier
+            label (str, optional): user-facing label
+            emoji (str | EmojiModel, optional): emoji icon as str or EmojiModel if custom
+            disabled (bool, optional): Whether the button should be disabled. Defaults to False.
+
+        Returns:
+            (Button): the button object
+        """
+        return ComponentBuilder._basic_button(ButtonStyles.SUCCESS, custom_id, label, emoji, disabled)
+    
+    @staticmethod
+    def danger(custom_id: str, label: str = None, emoji: str | EmojiModel = None, disabled: bool = False):
+        """Builds a danger button
+
+        Args:
+            custom_id (str): unique button identifier
+            label (str, optional): user-facing label
+            emoji (str | EmojiModel, optional): emoji icon as str or EmojiModel if custom
+            disabled (bool, optional): Whether the button should be disabled. Defaults to False.
+
+        Returns:
+            (Button): the button object
+        """
+        return ComponentBuilder._basic_button(ButtonStyles.DANGER, custom_id, label, emoji, disabled)
+    
+    @staticmethod
+    def link(url: str, label: str = None, emoji: str | EmojiModel = None, disabled: bool = False):
+        """Builds a link button
+
+        Args:
+            url (str): button URL to open
+            label (str, optional): user-facing label
+            emoji (str | EmojiModel, optional): emoji icon as str or EmojiModel if custom
+            disabled (bool, optional): Whether the button should be disabled. Defaults to False.
+
+        Returns:
+            (Button): the button object
+        """
+        btn = ComponentBuilder._basic_button(ButtonStyles.LINK, label, emoji, disabled)
+        btn.url = url
+        return btn
+    
+    @staticmethod
+    def row(components: list[ActionRowChild]):
+        """Shorthand for action row.
+
+        Args:
+            components (list[ActionRowChild]): the action row objects.
+
+        Returns:
+            (ActionRowPart): the action row object
+        """
+        if not isinstance(components, list):
+            components = [components]
+
+        return ActionRowPart(components)
+    
+    @staticmethod
+    def option(
+        label: str,
+        value: str,
+        description: str = None,
+        emoji: EmojiModel | str = None,
+        default: bool = False
+    ):
+        """Builds a string menu select option.
+
+        Args:
+            label (str): user-facing label
+            value (str): unique identifier
+            description (str, optional): option descriptor
+            emoji (EmojiModel | str, optional): emoji icon as str or EmojiModel if custom
+            default (bool, optional): Whether this value should be the default if none is selected. Defaults to False.
+
+        Raises:
+            (TypeError): invalid `emoji` type
+
+        Returns:
+            (SelectOption): the SelectOption object
+        """
+        if emoji:
+            if isinstance(emoji, str):
+                emoji = EmojiModel(name=emoji)
+            elif not isinstance(emoji, EmojiModel):
+                raise TypeError(f"EasyBot.primary expects type str or EmojiModel, got {type(emoji).__name__}")
+        
+        return SelectOption(
+            label=label,
+            value=value,
+            description=description,
+            emoji=emoji,
+            default=default
+        )
+    
+    @staticmethod
+    def short_text(
+        custom_id: str,
+        required: bool = True,
+        placeholder: str | None = None,
+        min_length: int | None = None,
+        max_length: int | None = None
+    ):
+        """Builds a TextInput with `TextInputStyles.SHORT` style.
+
+        Args:
+            custom_id (str): unique identifier
+            required (bool, optional): Whether this field is required. Defaults to True.
+            placeholder (str | None, optional): default text if nothing is entered
+            min_length (int | None, optional): minimum input length
+            max_length (int | None, optional): maximum input length
+
+        Returns:
+            (TextInput): the TextInput object
+        """
+        return TextInput(
+            style=TextInputStyles.SHORT,
+            custom_id=custom_id,
+            required=required,
+            placeholder=placeholder,
+            min_length=min_length,
+            max_length=max_length
+        )
+
+    @staticmethod
+    def long_text(
+        custom_id: str,
+        required: bool = True,
+        placeholder: str | None = None,
+        min_length: int | None = None,
+        max_length: int | None = None
+    ):
+        """Builds a TextInput with `TextInputStyles.PARAGRAPH` style.
+
+        Args:
+            custom_id (str): unique identifier
+            required (bool, optional): Whether this field is required. Defaults to True.
+            placeholder (str | None, optional): default text if nothing is entered
+            min_length (int | None, optional): minimum input length
+            max_length (int | None, optional): maximum input length
+
+        Returns:
+            (TextInput): the TextInput object
+        """
+        return TextInput(
+            style=TextInputStyles.PARAGRAPH,
+            custom_id=custom_id,
+            required=required,
+            placeholder=placeholder,
+            min_length=min_length,
+            max_length=max_length
+        )
+
+    @staticmethod
+    def role_value(id: int):
+        """Builds a default role value.
+
+        Args:
+            id (int): role ID
+
+        Returns:
+            (DefaultValue): the DefaultValue object
+        """
+        return DefaultValue(
+            id=id,
+            type='role'
+        )
+
+    @staticmethod
+    def user_value(id: int):
+        """Builds a default user value.
+
+        Args:
+            id (int): user ID
+
+        Returns:
+            (DefaultValue): the DefaultValue object
+        """
+        return DefaultValue(
+            id=id,
+            type='user'
+        )
+    
+    @staticmethod
+    def channel_value(id: int):
+        """Builds a default channel value.
+
+        Args:
+            id (int): channel ID
+
+        Returns:
+            (DefaultValue): the DefaultValue object
+        """
+        return DefaultValue(
+            id=id,
+            type='channel'
+        )