scurry-kit 0.2__py3-none-any.whl

scurry_kit/__init__.py

@@ -0,0 +1,9 @@
+# scurry_kit
+
+from .client import ScurryKit
+
+__all__ = [
+    "ScurryKit"
+]
+
+from .addons import *

scurry_kit/addons/__init__.py

@@ -0,0 +1,9 @@
+# easybot/addons
+
+from .component_builder import ComponentBuilder
+from .embed_builder import EmbedBuilder
+
+__all__ = [
+    "ComponentBuilder",
+    "EmbedBuilder"
+]

scurry_kit/addons/cache/__init__.py

@@ -0,0 +1,13 @@
+# easybot/addons/cache
+
+from .bot_emojis import BotEmojisCacheAddon
+from .channel import GuildChannelCacheAddon
+from .guild_emojis import GuildEmojiCacheAddon
+from .role import RoleCacheAddon
+
+__all__ = [
+    'BotEmojisCacheAddon',
+    'GuildChannelCacheAddon',
+    'GuildEmojiCacheAddon',
+    'RoleCacheAddon'
+]

scurry_kit/addons/cache/bot_emojis.py

@@ -0,0 +1,34 @@
+from scurrypy import (
+    Addon,
+    Client,
+    EmojiModel
+)
+
+class BotEmojisCacheAddon(Addon):
+    """Defines caching bot emojis and lookup."""
+
+    def __init__(self, client: Client):
+        self.bot = client
+        self.emojis: dict[str, EmojiModel] = {}   # index by unique name
+        client.addons.add(self)
+
+    def setup(self):
+        self.bot.add_startup_hook(self.load_bot_emojis)
+
+    async def load_bot_emojis(self):
+        """Fetch all bot's emojis and add them to the cache."""
+        emojis = await self.bot.bot_emoji().fetch_all()
+
+        for emoji in emojis:
+            self.emojis[emoji.name] = emoji
+
+    def get_emoji(self, name: str):
+        """Get an emoji from the cache.
+
+        Args:
+            name (str): name of the emoji
+
+        Returns:
+            (EmojiModel | None): the emoji object if found else None
+        """
+        return self.emojis.get(name)

scurry_kit/addons/cache/channel.py

@@ -0,0 +1,113 @@
+from scurrypy import (
+    Addon,
+    Client,
+    ChannelModel,
+    GuildCreateEvent, GuildDeleteEvent,
+    GuildChannelCreateEvent, GuildChannelUpdateEvent, GuildChannelDeleteEvent
+)
+
+class GuildChannelCacheAddon(Addon):
+    """Defines caching channels and lookup."""
+
+    def __init__(self, client: Client):
+        self.bot = client
+
+        self.channels: dict[int, dict[int, ChannelModel]] = {}  # stores OBJECTS
+        self.channel_index: dict[int, ChannelModel] = {}        # stores REFERENCES
+
+        client.addons.add(self)
+
+    def setup(self):
+        self.bot.add_startup_hook(self.on_startup)
+
+    def on_startup(self):
+        self.bot.add_event_listener('GUILD_CREATE', self.on_guild_create)
+        self.bot.add_event_listener('GUILD_DELETE', self.on_guild_delete)
+
+        self.bot.add_event_listener('CHANNEL_CREATE', self.on_channel_create)
+        self.bot.add_event_listener('CHANNEL_UPDATE', self.on_channel_update)
+        self.bot.add_event_listener('CHANNEL_DELETE', self.on_channel_delete)
+
+    def on_guild_create(self, event: GuildCreateEvent):
+        """Append new guild channels to cache. Also add channels to index.
+
+        Args:
+            event (GuildCreateEvent): the GUILD_CREATE event
+        """
+        guild_dict = self.channels.setdefault(event.id, {})
+
+        for ch in event.channels:
+            guild_dict[ch.id] = ch
+            self.channel_index[ch.id] = ch
+
+    def on_guild_delete(self, event: GuildDeleteEvent):
+        """Remove guild channels from cache. Also remove channels from index
+
+        Args:
+            event (GuildDeleteEvent): the GUILD_DELETE event
+        """
+        removed_channels = self.channels.pop(event.id, {})
+
+        for ch in removed_channels.values():
+            self.channel_index.pop(ch.id, None)
+
+    def on_channel_create(self, event: GuildChannelCreateEvent):
+        """Append channel to guild key. Also append channel to index.
+
+        Args:
+            event (GuildChannelCreateEvent): the CHANNEL_CREATE event
+        """
+        model = ChannelModel.from_dict(event.raw)
+        guild_dict = self.channels.setdefault(event.guild_id, {})
+
+        guild_dict[event.id] = model
+        self.channel_index[event.id] = model
+
+    def on_channel_update(self, event: GuildChannelUpdateEvent):
+        """Replace channel in guild key. Also replace channel in index.
+
+        Args:
+            event (GuildChannelUpdateEvent): the CHANNEL_UPDATE event
+        """
+        model = ChannelModel.from_dict(event.raw)
+        guild_dict = self.channels.setdefault(event.guild_id, {})
+
+        guild_dict[event.id] = model
+        self.channel_index[event.id] = model
+
+    def on_channel_delete(self, event: GuildChannelDeleteEvent):
+        """Remove channel from guild key. Also remove channel from index.
+
+        Args:
+            event (GuildChannelDeleteEvent): the CHANNEL_DELETE event
+        """
+        model = self.channel_index.pop(event.id, None)
+        if model:
+            self.channels.get(event.guild_id, {}).pop(event.id, None)
+
+    def get_channel(self, channel_id: int):
+        """Get a channel from the cache.
+
+        Args:
+            channel_id (int): ID of the channel
+
+        Returns:
+            (ChannelModel | None): the channel object if found else None
+        """
+        return self.channel_index.get(channel_id)
+
+    def put(self, channel: ChannelModel):
+        """Put a new channel into the cache.
+
+        Args:
+            channel (ChannelModel): the channel object
+
+        Raises:
+            ValueError: missing `guild_id`
+        """
+        if channel.guild_id is None:
+            raise ValueError("Cannot cache a channel without a guild_id.")
+        
+        guild_dict = self.channels.setdefault(channel.guild_id, {})
+        guild_dict[channel.id] = channel
+        self.channel_index[channel.id] = channel

scurry_kit/addons/cache/guild_emojis.py

@@ -0,0 +1,92 @@
+from scurrypy import (
+    Addon,
+    Client,
+    Intents,
+    EmojiModel,
+    GuildCreateEvent, GuildDeleteEvent,
+    GuildEmojisUpdateEvent
+)
+
+class GuildEmojiCacheAddon(Addon):
+    """Defines caching guild emojis and lookup.
+    
+    !!! important
+        This cache requires `Intents.GUILD_EMOJIS_AND_STICKERS` to keep up-to-date.
+    """
+
+    def __init__(self, client: Client):
+        self.bot = client
+
+        if not Intents.has(client.intents, Intents.GUILD_EMOJIS_AND_STICKERS):
+            raise ValueError("GuildEmojiCache requires Intents.GUILD_EMOJIS_AND_STICKERS for GUILD_EMOJIS_UPDATE event.")
+
+        self.guild_emojis: dict[int, dict[int, EmojiModel]] = {}  # owns emoji objects
+        self.guild_emoji_index: dict[int, EmojiModel] = {}        # index by ID (reference)
+
+        client.addons.add(self)
+
+    def setup(self):
+        self.bot.add_startup_hook(self.on_startup)
+
+    def on_startup(self):
+        self.bot.add_event_listener('GUILD_CREATE', self.on_guild_create)
+        self.bot.add_event_listener('GUILD_DELETE', self.on_guild_delete)
+
+        self.bot.add_event_listener('GUILD_EMOJIS_UPDATE', self.on_emojis_update)
+
+    def on_guild_create(self, event: GuildCreateEvent):
+        """Append new guild emojis to cache. Also add emojis to index.
+
+        Args:
+            event (GuildCreateEvent): the GUILD_CREATE event
+        """
+        guild_dict = self.guild_emojis.setdefault(event.id, {})
+
+        # event.emojis is already hydrated
+        for emoji in event.emojis:
+            guild_dict[emoji.id] = emoji
+            self.guild_emoji_index[emoji.id] = emoji
+
+    def on_guild_delete(self, event: GuildDeleteEvent):
+        """Remove guild emojis from cache. Also remove emojis from index
+
+        Args:
+            event (GuildDeleteEvent): the GUILD_DELETE event
+        """
+        removed = self.guild_emojis.pop(event.id, {})
+
+        for emoji in removed.values():
+            self.guild_emoji_index.pop(emoji.id, None)
+
+    def on_emojis_update(self, event: GuildEmojisUpdateEvent):
+        """Refresh guild emojis with new list. Also refresh the index
+
+        Args:
+            event (GuildEmojisUpdateEvent): the GUILD_EMOJIS_UPDATE event
+        """
+        guild_id = event.guild_id
+
+        # remove old emojis
+        removed = self.guild_emojis.pop(guild_id, {})
+
+        for emoji in removed.values():
+            self.guild_emoji_index.pop(emoji.id, None)
+
+        # add new emoji set (full replacement)
+        guild_dict = self.guild_emojis.setdefault(guild_id, {})
+
+        for emoji in event.emojis:
+            guild_dict[emoji.id] = emoji
+            self.guild_emoji_index[emoji.id] = emoji
+
+    def get_emoji(self, emoji_id: int):
+        """Get an emoji from the cache.
+
+        Args:
+            emoji_id (int): ID of the emoji
+
+        Returns:
+            (EmojiModel | None): the Emoji object if found, else None
+        """
+        return self.guild_emoji_index.get(emoji_id, None)
+    

scurry_kit/addons/cache/role.py

@@ -0,0 +1,108 @@
+from scurrypy import (
+    Addon,
+    Client,
+    RoleModel,
+    GuildCreateEvent, GuildDeleteEvent,
+    RoleCreateEvent, RoleUpdateEvent, RoleDeleteEvent
+)
+
+class RoleCacheAddon(Addon):
+    """Defines caching guild roles and lookup."""
+
+    def __init__(self, client: Client):
+        self.bot = client
+
+        self.roles: dict[int, dict[int, RoleModel]] = {} # stores OBJECTS
+        self.role_index: dict[int, RoleModel] = {} # stores REFERENCES
+
+        client.addons.add(self)
+
+    def setup(self):
+        self.bot.add_startup_hook(self.on_startup)
+
+    def on_startup(self):
+        self.bot.add_event_listener('GUILD_CREATE', self.on_guild_create)
+        self.bot.add_event_listener('GUILD_DELETE', self.on_guild_delete)
+
+        self.bot.add_event_listener('ROLE_CREATE', self.on_role_create)
+        self.bot.add_event_listener('ROLE_UPDATE', self.on_role_update)
+        self.bot.add_event_listener('ROLE_DELETE', self.on_role_delete)
+
+    def on_guild_create(self, event: GuildCreateEvent):
+        """Append new guild roles to cache. Also add roles to index.
+
+        Args:
+            event (GuildCreateEvent): the GUILD_CREATE event
+        """
+        guild_dict = self.roles.setdefault(event.id, {})
+
+        for role in event.roles:
+            guild_dict[role.id] = role
+            self.role_index[role.id] = role
+
+    def on_guild_delete(self, event: GuildDeleteEvent):
+        """Remove guild roles from cache. Also remove roles from index
+
+        Args:
+            event (GuildDeleteEvent): the GUILD_DELETE event
+        """
+        removed_roles = self.roles.pop(event.id, {})
+
+        for role in removed_roles.values():
+            self.role_index.pop(role.id, None)
+
+    def on_role_create(self, event: RoleCreateEvent):
+        """Append role to guild key. Also append role to index.
+
+        Args:
+            event (RoleCreateEvent): the ROLE_CREATE event
+        """
+        model = RoleModel.from_dict(event.raw)
+        guild_dict = self.roles.setdefault(event.guild_id, {})
+
+        guild_dict[event.role.id] = model
+        self.role_index[event.role.id] = model
+
+    def on_role_update(self, event: RoleUpdateEvent):
+        """Replace role in guild key. Also replace role in index.
+
+        Args:
+            event (RoleUpdateEvent): the ROLE_UPDATE event
+        """
+        model = RoleModel.from_dict(event.raw)
+        guild_dict = self.roles.setdefault(event.guild_id, {})
+
+        guild_dict[event.role.id] = model
+        self.role_index[event.role.id] = model
+
+    def on_role_delete(self, event: RoleDeleteEvent):
+        """Remove role from guild key. Also remove role from index.
+
+        Args:
+            event (RoleDeleteEvent): the ROLE_DELETE event
+        """
+        model = self.role_index.pop(event.role_id, None)
+        if model:
+            self.roles.get(event.guild_id, {}).pop(event.role_id, None)
+
+    def get_role(self, role_id: int):
+        """Get a role from the cache.
+
+        Args:
+            role_id (int): ID of the role
+
+        Returns:
+            (RoleModel | None): the role object if found else None
+        """
+        return self.role_index.get(role_id)
+
+    def put(self, guild_id: int, role: RoleModel):
+        """Put a new role into the cache.
+
+        Args:
+            guild_id (int): guild ID of the role
+            role (RoleModel): the role object
+        """
+        guild_dict = self.roles.setdefault(guild_id, {})
+        guild_dict[role.id] = role
+        self.role_index[role.id] = role

scurry_kit/addons/component_builder.py

@@ -0,0 +1,290 @@
+from scurrypy import (
+    Addon,
+    EmojiModel,
+    Button, ButtonStyles,
+    ActionRowChild, ActionRowPart,
+    SelectOption,
+    TextInput, TextInputStyles,
+    DefaultValue
+)
+
+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'
+        )