scurrypy 0.4.2__py3-none-any.whl → 0.5.3__py3-none-any.whl

scurrypy/parts/embed.py

@@ -0,0 +1,83 @@
+from dataclasses import dataclass, field
+from typing import Optional
+from ..model import DataModel
+
+@dataclass
+class EmbedAuthor(DataModel):
+    """Embed author parameters."""
+
+    name: str
+    """Name of the author."""
+
+    url: Optional[str] = None
+    """URL of the author. http or attachment://<filename> scheme."""
+
+    icon_url: Optional[str] = None
+    """URL of author's icon. http or attachment://<filename> scheme."""
+
+@dataclass
+class EmbedThumbnail(DataModel):
+    """Embed thumbnail."""
+
+    url: str
+    """Thumbnail content. http or attachment://<filename> scheme."""
+
+@dataclass
+class EmbedField(DataModel):
+    """Embed field."""
+
+    name: str
+    """Name of the field."""
+
+    value: str
+    """Value of the field."""
+
+    inline: Optional[bool] = None
+    """Whether or not this field should display inline."""
+
+@dataclass
+class EmbedImage(DataModel):
+    """Embed image."""
+
+    url: str
+    """Image content. http or attachment://<filename> scheme."""
+
+@dataclass
+class EmbedFooter(DataModel):
+    """Embed footer."""
+    text: str
+    """Footer text."""
+
+    icon_url: Optional[str] = None
+    """URL of the footer icon. http or attachment://<filename> scheme."""
+
+@dataclass
+class EmbedPart(DataModel):
+    """Represents the Embed portion of a message."""
+
+    title: Optional[str] = None
+    """This embed's title."""
+
+    description: Optional[str] = None
+    """This embed's description."""
+
+    timestamp: Optional[str] = None
+    """Timestamp of when the embed was sent."""
+
+    color: Optional[int] = None
+    """Embed's accent color."""
+
+    author: Optional[EmbedAuthor] = None
+    """Embed's author."""
+
+    thumbnail: Optional[EmbedThumbnail] = None
+    """Embed's thumbnail attachment."""
+
+    image: Optional[EmbedImage] = None
+    """Embed's image attachment."""
+
+    fields: Optional[list[EmbedField]] = field(default_factory=list)
+    """List of embed's fields."""
+
+    footer: Optional[EmbedFooter] = None
+    """Embed's footer."""

scurrypy/parts/message.py

@@ -0,0 +1,137 @@
+from dataclasses import dataclass, field
+from typing import Optional, TypedDict, Unpack
+from ..model import DataModel
+from .embed import EmbedPart
+from .components import ActionRowPart
+from .components_v2 import ContainerPart
+
+class MessageFlags:
+    """Flags that can be applied to a message."""
+
+    CROSSPOSTED = 1 << 0
+    """Message has been published."""
+
+    IS_CROSSPOST = 1 << 1
+    """Message originated from another channel."""
+
+    SUPPRESS_EMBEDS = 1 << 2
+    """Hide embeds (if any)."""
+
+    EPHEMERAL = 1 << 6
+    """Only visible to the invoking user."""
+
+    LOADING = 1 << 7
+    """Thinking response."""
+
+    IS_COMPONENTS_V2 = 1 << 15
+    """This message includes Discord's V2 Components."""
+
+class MessageFlagParams(TypedDict, total=False):
+    """Parameters for setting message flags. See [`MessageFlags`][scurrypy.parts.message.MessageFlags]."""
+    crossposted: bool
+    is_crosspost: bool
+    suppress_embeds: bool
+    ephemeral: bool
+    loading: bool
+    is_components_v2: bool
+
+class MessageReferenceTypes:
+    """Constants associated with how reference data is populated."""
+
+    DEFAULT = 0
+    """Standard reference used by replies."""
+
+    FORWARD = 1
+    """Reference used to point to a message at a point in time."""
+
+@dataclass
+class MessageReference(DataModel):
+    """Represents the Message Reference object."""
+
+    message_id: int
+    """ID of the originating message."""
+
+    channel_id: int
+    """
+        Channel ID of the originating message.
+        !!! note
+            Optional for default type, but REQUIRED for forwards.
+    """
+
+    type: int = MessageReferenceTypes.DEFAULT
+    """Type of reference. Defaults to `DEFAULT`. See [`MessageReferenceTypes`][scurrypy.parts.message.MessageReferenceTypes]."""
+
+@dataclass
+class Attachment(DataModel):
+    """Represents an attachment."""
+
+    id: int
+    """User-defined ID for the attachment."""
+
+    path: str
+    """Relative path to the file."""
+
+    filename: str
+    """Name of the file."""
+
+    description: str
+    """Description of the file."""
+
+    def to_dict(self):
+        return {
+            'id': self.id,
+            'filename': self.filename,
+            'description': self.description
+        }
+
+@dataclass
+class MessagePart(DataModel):
+    """Describes expected params when editing/creating a message."""
+
+    content: Optional[str] = None
+    """Message text content."""
+
+    flags: Optional[int] = 0
+    """Message flags. See [`MessageFlags`][scurrypy.parts.message.MessageFlags]."""
+
+    components: Optional[list[ActionRowPart | ContainerPart]] = field(default_factory=list)
+    """Components to be attached to this message."""
+
+    attachments: Optional[list[Attachment]] = field(default_factory=list)
+    """Attachments to be attached to this message."""
+
+    embeds: Optional[list[EmbedPart]] = field(default_factory=list)
+    """Embeds to be attached to this message."""
+
+    message_reference: Optional[MessageReference] = None
+    """Message reference if reply."""
+
+    def set_flags(self, **flags: Unpack[MessageFlagParams]):
+        """Set this message's flags using MessageFlagParams.
+
+        Args:
+            flags (Unpack[MessageFlagParams]): message flags to set. (set respective flag to True to toggle.)
+
+        Raises:
+            (ValueError): invalid flag
+
+        Returns:
+            (MessagePart): self
+        """
+        _flag_map = {
+            'crossposted': MessageFlags.CROSSPOSTED,
+            'is_crosspost': MessageFlags.IS_CROSSPOST,
+            'suppress_embeds': MessageFlags.SUPPRESS_EMBEDS,
+            'ephemeral': MessageFlags.EPHEMERAL,
+            'loading': MessageFlags.LOADING,
+            'is_components_v2': MessageFlags.IS_COMPONENTS_V2,
+        }
+
+        # each flag maps to a specific combined bit!
+        for name, value in flags.items():
+            if name not in _flag_map:
+                raise ValueError(f"Invalid flag: {name}")
+            if value:
+                self.flags |= _flag_map[name]
+                
+        return self

scurrypy/parts/modal.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass, field
+from ..model import DataModel
+from .components_v2 import Label
+
+@dataclass
+class ModalPart(DataModel):
+    """Represents the Modal object."""
+
+    title: str
+    """Title of the popup modal."""
+
+    custom_id: str = None
+    """ID for the modal."""
+
+    components: list[Label] = field(default_factory=list)
+    """1 to 5 components that make up the modal."""

{discord → scurrypy}/parts/role.py

@@ -1,6 +1,6 @@
 from dataclasses import dataclass
 from typing import Optional
-from discord.model import DataModel
+from ..model import DataModel
 
 from ..models.role import RoleColors
 
@@ -25,15 +25,3 @@ class Role(DataModel):
 
     unicode_emoji: Optional[str] = None
     """Unicode emoji of the role."""
-
-    def set_color(self, hex: str):
-        """Set this role's color with a hex. (format: #FFFFFF)
-
-        Args:
-            hex (str): color as a hex code
-
-        Returns:
-            (Role): self
-        """
-        self.color=int(hex.strip('#'), 16)
-        return self

{discord → scurrypy}/resources/channel.py

@@ -6,7 +6,7 @@ from ..model import DataModel
 from .message import Message
 
 from ..parts.channel import GuildChannel
-from ..parts.message import MessageBuilder
+from ..parts.message import MessagePart
 
 class MessagesFetchParams(TypedDict, total=False):
     """Params when fetching guild channel messages."""
@@ -132,7 +132,7 @@ class Channel(DataModel):
 
         return [Message.from_dict(msg, self._http) for msg in data]
     
-    async def send(self, message: str | MessageBuilder):
+    async def send(self, message: str | MessagePart):
         """
         Send a message to this channel.
 
@@ -140,15 +140,15 @@ class Channel(DataModel):
             * SEND_MESSAGES → required to create a message in this channel
 
         Args:
-            message (str | MessageBuilder): can be just text or the MessageBuilder for dynamic messages
+            message (str | MessagePart): can be just text or the MessagePart for dynamic messages
 
         Returns:
             (Message): The created Message object
         """
         if isinstance(message, str):
-            message = MessageBuilder(content=message)
+            message = MessagePart(content=message)
 
-        data = await self._http.request("POST", f"/channels/{self.id}/messages", data=message._to_dict())
+        data = await self._http.request("POST", f"/channels/{self.id}/messages", data=message.to_dict())
 
         return Message.from_dict(data, self._http)
 
@@ -164,7 +164,7 @@ class Channel(DataModel):
         Returns:
             (Channel): The updated channel object
         """
-        data = await self._http.request("PATCH", f"/channels/{self.id}", data=channel._to_dict())
+        data = await self._http.request("PATCH", f"/channels/{self.id}", data=channel.to_dict())
         self._update(data)
 
         return self

{discord → scurrypy}/resources/guild.py

@@ -1,6 +1,5 @@
 from dataclasses import dataclass
 from typing import Optional, TypedDict, Unpack
-from urllib.parse import urlencode
 
 from ..http import HTTPClient
 from ..model import DataModel
@@ -137,7 +136,7 @@ class Guild(DataModel):
         Returns:
             (Channel): the created channel
         """
-        data = await self._http.request('POST', f'/guilds/{self.id}/channels', data=channel._to_dict())
+        data = await self._http.request('POST', f'/guilds/{self.id}/channels', data=channel.to_dict())
 
         return Channel.from_dict(data, self._http)
 
@@ -234,7 +233,7 @@ class Guild(DataModel):
         Returns:
             (RoleModel): new role data
         """
-        data = await self._http.request('POST', f'/guilds/{self.id}/roles', data=role._to_dict())
+        data = await self._http.request('POST', f'/guilds/{self.id}/roles', data=role.to_dict())
 
         return RoleModel.from_dict(data)
 
@@ -250,7 +249,7 @@ class Guild(DataModel):
         Returns:
             (RoleModel): role with changes
         """
-        data = await self._http.request('PATCH', f'/guilds/{self.id}/roles/{role_id}', data=role._to_dict())
+        data = await self._http.request('PATCH', f'/guilds/{self.id}/roles/{role_id}', data=role.to_dict())
 
         return RoleModel.from_dict(data)
     

{discord → scurrypy}/resources/interaction.py

@@ -4,8 +4,8 @@ from typing import Optional, Unpack
 from ..http import HTTPClient
 from ..model import DataModel
 
-from ..parts.modal import ModalBuilder
-from ..parts.message import *
+from ..parts.modal import ModalPart
+from ..parts.message import MessagePart, MessageFlagParams
 
 from ..models.guild import GuildModel
 from ..models.member import MemberModel
@@ -38,8 +38,9 @@ class InteractionCallbackTypes:
     """Acknowledge an interaction and edit a response later. User sees a loading state."""
 
     DEFERRED_UPDATE_MESSAGE = 6
-    """Acknowledge an interaction and edit the original message later. 
-    The user does NOT see a loading state. (Components only)
+    """
+        Acknowledge an interaction and edit the original message later. 
+        The user does NOT see a loading state. (Components only)
     """
 
     UPDATE_MESSAGE = 7
@@ -68,7 +69,7 @@ class Interaction(DataModel):
     """HTTP session for requests."""
 
     type: int
-    """Type of interaction."""
+    """Type of interaction. See [`InteractionTypes`][scurrypy.dispatch.command_dispatcher.InteractionTypes]."""
 
     channel_id: int
     """ID of the channel where the interaction was sent."""
@@ -97,24 +98,24 @@ class Interaction(DataModel):
     channel: Optional[Channel] = None
     """Partial channel object the interaction was invoked."""
 
-    async def respond(self, message: str | MessageBuilder, with_response: bool = False, **flags: Unpack[MessageFlagParams]):
+    async def respond(self, message: str | MessagePart, with_response: bool = False, **flags: Unpack[MessageFlagParams]):
         """Create a message in response to an interaction.
 
         Args:
-            message (str | MessageBuilder): content as a string or from MessageBuilder
+            message (str | MessagePart): content as a string or from MessagePart
             with_response (bool, optional): if the interaction data should be returned. Defaults to False.
 
         Raises:
             TypeError: invalid type
         """
         if isinstance(message, str):
-            message = MessageBuilder(content=message).set_flags(**flags)
-        elif not isinstance(message, MessageBuilder):
-            raise TypeError(f"Interaction.respond expects type str or MessageBuilder, got {type(message).__name__}")
+            message = MessagePart(content=message).set_flags(**flags)
+        elif not isinstance(message, MessagePart):
+            raise TypeError(f"Interaction.respond expects type str or MessagePart, got {type(message).__name__}")
 
         content = {
             'type': InteractionCallbackTypes.CHANNEL_MESSAGE_WITH_SOURCE,
-            'data': message._to_dict()
+            'data': message.to_dict()
         }
 
         params = {'with_response': with_response}
@@ -129,23 +130,23 @@ class Interaction(DataModel):
         if with_response:
             return InteractionCallbackModel.from_dict(data, self._http)
         
-    async def update(self, message: str | MessageBuilder, **flags: Unpack[MessageFlagParams]):
+    async def update(self, message: str | MessagePart, **flags: Unpack[MessageFlagParams]):
         """Update a message in response to an interaction.
 
         Args:
-            message (str | MessageBuilder): content as a string or from MessageBuilder
+            message (str | MessagePart): content as a string or from MessagePart
 
         Raises:
             TypeError: invalid type
         """
         if isinstance(message, str):
-            message = MessageBuilder(content=message).set_flags(**flags)
-        elif not isinstance(message, MessageBuilder):
-            raise TypeError(f"Interaction.update expects type str or MessageBuilder, got {type(message).__name__}")
+            message = MessagePart(content=message).set_flags(**flags)
+        elif not isinstance(message, MessagePart):
+            raise TypeError(f"Interaction.update expects type str or MessagePart, got {type(message).__name__}")
 
         content = {
             'type': InteractionCallbackTypes.UPDATE_MESSAGE,
-            'data': message._to_dict()
+            'data': message.to_dict()
         }
 
         await self._http.request(
@@ -154,21 +155,21 @@ class Interaction(DataModel):
             data=content, 
             files=[fp.path for fp in message.attachments])
 
-    async def respond_modal(self, modal: ModalBuilder):
+    async def respond_modal(self, modal: ModalPart):
         """Create a modal in response to an interaction.
 
         Args:
-            modal (ModalBuilder): modal data
+            modal (ModalPart): modal data
 
         Raises:
             TypeError: invalid type
         """
-        if not isinstance(modal, ModalBuilder):
-            raise TypeError(f"Interaction.respond_modal expects type ModalBuilder, got {type(modal).__name__}")
+        if not isinstance(modal, ModalPart):
+            raise TypeError(f"Interaction.respond_modal expects type ModalPart, got {type(modal).__name__}")
         
         content = {
             'type': InteractionCallbackTypes.MODAL,
-            'data': modal._to_dict()
+            'data': modal.to_dict()
         }
 
         await self._http.request(

{discord → scurrypy}/resources/message.py

@@ -6,7 +6,7 @@ from ..model import DataModel
 
 from ..models.user import UserModel
 from ..models.emoji import EmojiModel
-from ..parts.message import MessageBuilder
+from ..parts.message import MessagePart
 
 @dataclass
 class Message(DataModel):
@@ -50,67 +50,67 @@ class Message(DataModel):
 
         return Message.from_dict(data, self._http)
 
-    async def send(self, message: str | MessageBuilder):
+    async def send(self, message: str | MessagePart):
         """Sends a new message to the current channel.
 
         Permissions:
             * SEND_MESSAGES → required to senf your own messages
 
         Args:
-            message (str | MessageBuilder): can be just text or the MessageBuilder for dynamic messages
+            message (str | MessagePart): can be just text or the MessagePart for dynamic messages
 
         Returns:
             (Message): the new Message object with all fields populated
         """
         if isinstance(message, str):
-            message = MessageBuilder(content=message)
+            message = MessagePart(content=message)
 
         data = await self._http.request(
             "POST",
             f"/channels/{self.channel_id}/messages",
-            data=message._to_dict(),
+            data=message.to_dict(),
             files=[fp.path for fp in message.attachments] if message.attachments else None
         )
         return Message.from_dict(data, self._http)
 
-    async def edit(self, message: str | MessageBuilder):
+    async def edit(self, message: str | MessagePart):
         """Edits this message.
 
         Permissions:
             * MANAGE_MESSAGES → ONLY if editing another user's message
 
         Args:
-            message (str | MessageBuilder): can be just text or the MessageBuilder for dynamic messages
+            message (str | MessagePart): can be just text or the MessagePart for dynamic messages
         """
         if isinstance(message, str):
-            message = MessageBuilder(content=message)
+            message = MessagePart(content=message)
 
         data = await self._http.request(
             "PATCH", 
             f"/channels/{self.channel_id}/messages/{self.id}", 
-            data=message._to_dict(),
+            data=message.to_dict(),
             files=[fp.path for fp in message.attachments] if message.attachments else None)
 
         self._update(data)
 
-    async def reply(self, message: str | MessageBuilder):
+    async def reply(self, message: str | MessagePart):
         """Reply to this message with a new message.
 
         Permissions:
             * SEND_MESSAGES → required to send the message
 
         Args:
-            message (str | MessageBuilder): the new message
+            message (str | MessagePart): the new message
         """
         if isinstance(message, str):
-            message = MessageBuilder(content=message)
+            message = MessagePart(content=message)
 
         message = message._set_reference(self.id, self.channel_id)
 
         await self._http.request(
             'POST', 
             f"/channels/{self.channel_id}/messages",
-            data=message._to_dict(),
+            data=message.to_dict(),
             files=[fp.path for fp in message.attachments] if message.attachments else None)
 
     async def crosspost(self):

{scurrypy-0.4.2.dist-info → scurrypy-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scurrypy
-Version: 0.4.2
+Version: 0.5.3
 Summary: Dataclass-driven Discord API Wrapper in Python
 Author: Furmissile
 Requires-Python: >=3.10
@@ -8,7 +8,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
 
-# __Welcome to ScurryPy__
+# __ScurryPy__
 
 [![PyPI version](https://badge.fury.io/py/scurrypy.svg)](https://badge.fury.io/py/scurrypy)
 
@@ -20,22 +20,17 @@ 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  
-
----
+* 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
 
-## Some Things to Consider...
+## Notes & Early Status
 * 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.*
 
@@ -51,24 +46,24 @@ 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
+import scurrypy, os
 from dotenv import load_dotenv
 
 load_dotenv(dotenv_path='./path/to/env')
 
-client = discord.Client(
+client = scurrypy.Client(
     token=os.getenv("DISCORD_TOKEN"),
-    application_id=APPLICATION_ID  # replace with your bot's user ID
+    application_id=APPLICATION_ID  # your bot’s application ID
 )
 
 @client.command(
-    command=discord.SlashCommand(
+    command=scurrypy.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):
+async def example(bot: scurrypy.Client, event: scurrypy.InteractionEvent):
     await event.interaction.respond(f'Hello, {event.interaction.member.user.username}!')
 
 client.run()
@@ -77,20 +72,20 @@ client.run()
 ## Minimal Prefix Command (Legacy)
 The following demonstrates building and responding to a message prefix command.
 ```py
-import discord, os
+import scurrypy, os
 from dotenv import load_dotenv
 
 load_dotenv(dotenv_path='./path/to/env')
 
-client = discord.Client(
+client = scurrypy.Client(
     token=os.getenv("DISCORD_TOKEN"),
-    application_id=APPLICATION_ID,  # replace with your bot's user ID
-    intents=discord.set_intents(message_content=True),
+    application_id=APPLICATION_ID  # your bot’s application ID
+    intents=scurrypy.set_intents(message_content=True),
     prefix='!'  # your custom prefix
 )
 
 @client.prefix_command
-async def ping(bot: discord.Client, event: discord.MessageCreateEvent):
+async def ping(bot: scurrypy.Client, event: scurrypy.MessageCreateEvent):
     # The function name is the name of the command
     await event.message.send("Pong!")
 
@@ -126,5 +121,4 @@ If you plan to make substantial changes or release your own variant:
 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!
+Explore the full [documentation](https://furmissile.github.io/scurrypy) for more examples, guides, and API reference.