scurrypy 0.4__py3-none-any.whl → 0.6.6__py3-none-any.whl

scurrypy/parts/components_v2.py

@@ -0,0 +1,144 @@
+from dataclasses import dataclass, field
+from typing import Optional
+from ..model import DataModel
+
+from .component_types import *
+
+class ComponentV2Types:
+    SECTION = 9
+    TEXT_DISPLAY = 10
+    THUMBNAIL = 11
+    MEDIA_GALLERY = 12
+    FILE = 13
+    SEPARATOR = 14
+    CONTAINER = 17
+    LABEL = 18
+
+@dataclass
+class SectionPart(DataModel, ContainerChild):
+    """Represents the Section component."""
+
+    accessory: Optional[SectionAccessory] = None
+    """A component that is contextually associated to the content of the section."""
+
+    components: list[SectionChild] = field(default_factory=list)
+    """Component(s) representing the content of the section that is contextually associated to the accessory."""
+
+    type: int = field(init=False, default=ComponentV2Types.SECTION)
+    """Component type. Always `ComponentV2Types.SECTION` for this class. See [`ComponentV2Types`][scurrypy.parts.components_v2.ComponentV2Types]."""
+
+@dataclass
+class TextDisplay(DataModel, ContainerChild, SectionChild):
+    """Represents the Text Display component."""
+
+    content: str
+    """Text that will be displayed similar to a message."""
+
+    type: int = field(init=False, default=ComponentV2Types.TEXT_DISPLAY)
+    """Component type. Always `ComponentV2Types.TEXT_DISPLAY` for this class. See [`ComponentV2Types`][scurrypy.parts.components_v2.ComponentV2Types]."""
+
+@dataclass
+class Thumbnail(DataModel, SectionAccessory):
+    """Represents the Thumbnail component."""
+    
+    media: str
+    """Media of the thumbnail. http or attachment://<filename> scheme."""
+
+    description: Optional[str] = None
+    """Description for the media."""
+
+    spoiler: Optional[bool] = False
+    """Whether the thumbnail should be a spoiler (or blurred out)."""
+
+    type: int = field(init=False, default=ComponentV2Types.THUMBNAIL)
+    """Component type. Always `ComponentV2Types.THUMBNAIL` for this class. See [`ComponentV2Types`][scurrypy.parts.components_v2.ComponentV2Types]."""
+
+@dataclass
+class MediaGalleryItem(DataModel):
+    """Represents the Media Gallery Item component."""
+
+    media: str
+    """Image data. http or attachment://<filename> scheme."""
+
+    description: Optional[str] = None
+    """Alt text for the media."""
+
+    spoiler: Optional[bool] = False
+    """Whether the thumbnail should be a spoiler (or blurred out)."""
+
+@dataclass
+class MediaGallery(DataModel, ContainerChild):
+    """Represents the Media Gallery component."""
+
+    items: list[MediaGalleryItem] = field(default_factory=list)
+    """1 to 10 nedia gallery items. See [`MediaGalleryItem`][scurrypy.parts.components_v2.MediaGalleryItem]."""
+
+    type: int = field(init=False, default=ComponentV2Types.MEDIA_GALLERY)
+    """Component type. Always `ComponentV2Types.MEDIA_GALLERY` for this class. See [`ComponentV2Types`][scurrypy.parts.components_v2.ComponentV2Types]."""
+
+@dataclass
+class File(DataModel, ContainerChild):
+    """Represents the File component."""
+
+    file: str
+    """File name. ONLY supports attachment://<filename> scheme."""
+
+    spoiler: Optional[bool] = False
+    """Whether the thumbnail should be a spoiler (or blurred out)."""
+
+    type: int = field(init=False, default=ComponentV2Types.FILE)
+    """Component type. Always `ComponentV2Types.File` for this class. See [`ComponentV2Types`][scurrypy.parts.components_v2.ComponentV2Types]."""
+
+class SeparatorTypes:
+    """Represents separator types constants."""
+
+    SMALL_PADDING = 1
+    """Small separator padding."""
+    
+    LARGE_PADDING = 2
+    """Large separator padding."""
+
+@dataclass
+class Separator(DataModel, ContainerChild):
+    """Represents the Separator component."""
+
+    divider: bool = True
+    """Whether a visual divider should be displayed in the component. Defaults to True."""
+
+    spacing: Optional[int] = SeparatorTypes.SMALL_PADDING
+    """Size of separator padding. Defaults to `SMALL_PADDING`. See [`SeparatorTypes`][scurrypy.parts.components_v2.SeparatorTypes]."""
+
+    type: int = field(init=False, default=ComponentV2Types.SEPARATOR)
+    """Component type. Always `ComponentV2Types.SEPARATOR` for this class. See [`ComponentV2Types`][scurrypy.parts.components_v2.ComponentV2Types]."""
+
+@dataclass
+class ContainerPart(DataModel):
+    """Represents a container of display and interactable components."""
+
+    components: list[ContainerChild] = field(default_factory=list)
+    """Child components that are encapsulated within the Container."""
+
+    accent_color: Optional[int] = None
+    """Color for the accent as an integer."""
+
+    spoiler: Optional[bool] = False
+    """If the container should be blurred out. Defaults to False."""
+
+    type: int = field(init=False, default=ComponentV2Types.CONTAINER)
+    """Component type. Always `ComponentV2Types.CONTAINER` for this class. See [`ComponentV2Types`][scurrypy.parts.components_v2.ComponentV2Types]."""
+
+@dataclass
+class Label(DataModel):
+    """Represents the Discord Label component."""
+
+    label: str
+    """Label text."""
+
+    component: LabelChild = None
+    """A component within the label."""
+
+    description: Optional[str] = None
+    """An optional description text for the label."""
+
+    type: int = field(init=False, default=ComponentV2Types.LABEL)
+    """Component type. Always `ComponentV2Types.LABEL` for this class. See [`ComponentV2Types`][scurrypy.parts.components_v2.ComponentV2Types]."""

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,134 @@
+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 = field(init=False)
+    """ID of the attachment (internally set)."""
+
+    path: str
+    """Relative path to the file."""
+
+    description: str
+    """Description of the file."""
+
+    def to_dict(self):
+        return {
+            'id': self.id,
+            'filename': self.path.split('/')[-1],
+            '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 bit position!
+        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,8 +1,8 @@
 from dataclasses import dataclass
 from typing import Optional
-from discord.model import DataModel
+from ..model import DataModel
 
-from ..models.role import RoleColors
+from ..models import RoleColors
 
 @dataclass
 class Role(DataModel):
@@ -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/application.py

@@ -4,8 +4,7 @@ from typing import Optional
 from ..http import HTTPClient
 from ..model import DataModel
 
-from ..models.user import UserModel
-from ..models.guild import GuildModel
+from ..models import UserModel, GuildModel
 
 class ApplicationFlags:
     """Application flags (bitwise constants)."""

{discord → scurrypy}/resources/bot_emojis.py

@@ -1,5 +1,5 @@
 from ..http import HTTPClient
-from ..models.emoji import EmojiModel
+from ..models import EmojiModel
 
 class BotEmojis:
     """Represents a collection of the bot's emojis."""

{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."""
@@ -118,7 +118,7 @@ class Channel(DataModel):
             * READ_MESSAGE_HISTORY → required for user, otherwise no messages are returned
 
         Args:
-            **kwargs: field-specific data
+            **kwargs: message fetch params
                 !!! note
                     if no kwargs are provided, default to 50 fetched messages limit.
 
@@ -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", 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
@@ -175,6 +175,7 @@ class Channel(DataModel):
         Args:
             message_id: ID of message to attach thread
             name (str): thread name
+            **kwargs (Unpack[ThreadFromMessageParams]): thread create params
 
         Returns:
             (Channel): The updated channel object
@@ -197,7 +198,7 @@ class Channel(DataModel):
             * READ_MESSAGE_HISTORY → required for reading pinned messages
 
         Args:
-            kwargs: field-specific data
+            **kwargs: pinned message fetch params
                 !!! note
                     If no kwargs are provided, default to 50 fetched messages limit.
             

{discord → scurrypy}/resources/guild.py

@@ -9,9 +9,7 @@ from .channel import Channel
 from ..parts.channel import GuildChannel
 from ..parts.role import Role
 
-from ..models.emoji import EmojiModel
-from ..models.member import MemberModel
-from ..models.role import RoleModel
+from ..models import EmojiModel, MemberModel, RoleModel
 
 class FetchGuildMembersParams(TypedDict, total=False):
     """Params when fetching guild members."""
@@ -20,7 +18,7 @@ class FetchGuildMembersParams(TypedDict, total=False):
     """Max number of members to return Range 1 - 1000. Default 1."""
 
     after: int
-    """Highest user id in previous page."""
+    """Highest user ID in previous page."""
 
 class FetchGuildParams(TypedDict, total=False):
     """Params when fetching a guild."""
@@ -101,7 +99,7 @@ class Guild(DataModel):
         """Fetch the Guild object by the given ID.
 
         Args:
-            kwargs: field-specific data
+            **kwargs: guild fetch params
                 !!! note
                     If no kwargs are provided, default to with_counts = False
             
@@ -136,7 +134,7 @@ class Guild(DataModel):
         Returns:
             (Channel): the created channel
         """
-        data = await self._http.request('POST', f'/guilds/{self.id}/channels', 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)
 
@@ -146,7 +144,7 @@ class Guild(DataModel):
             Requires the GUILD_MEMBERS privileged intent!
 
         Args:
-            user_id (int): user id of the member to fetch
+            user_id (int): user ID of the member to fetch
 
         Returns:
             (MemberModel): member's data
@@ -161,7 +159,7 @@ class Guild(DataModel):
             Requires the GUILD_MEMBERS privileged intent!
 
         Args:
-            **kwargs: field-specific data
+            **kwargs: guild members fetch params
                 !!! note
                     If no kwargs are provided, default to 1 guild member limit.
 
@@ -181,8 +179,8 @@ class Guild(DataModel):
             * MANAGE_ROLES → required to add a role to the user
         
         Args:
-            user_id (int): id of the member for the role
-            role_id (int): id of the role to append
+            user_id (int): ID of the member for the role
+            role_id (int): ID of the role to append
         """
         await self._http.request('PUT', f'/guilds/{self.id}/members/{user_id}/roles/{role_id}')
     
@@ -193,8 +191,8 @@ class Guild(DataModel):
             * MANAGE_ROLES → required to remove a role from the user
 
         Args:
-            user_id (int): id of the member with the role
-            role_id (int): id of the role to remove
+            user_id (int): ID of the member with the role
+            role_id (int): ID of the role to remove
         """
         await self._http.request('DELETE', f'/guilds/{self.id}/members/{user_id}/roles/{role_id}')
 
@@ -202,7 +200,7 @@ class Guild(DataModel):
         """Fetch a role in this guild.
 
         Args:
-            role_id (int): id of the role to fetch
+            role_id (int): ID of the role to fetch
 
         Returns:
             (RoleModel): fetched role's data
@@ -233,7 +231,7 @@ class Guild(DataModel):
         Returns:
             (RoleModel): new role data
         """
-        data = await self._http.request('POST', f'/guilds/{self.id}/roles', role._to_dict())
+        data = await self._http.request('POST', f'/guilds/{self.id}/roles', data=role.to_dict())
 
         return RoleModel.from_dict(data)
 
@@ -249,7 +247,7 @@ class Guild(DataModel):
         Returns:
             (RoleModel): role with changes
         """
-        data = await self._http.request('PATCH', f'/guilds/{self.id}/roles/{role_id}', 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)
     
@@ -260,6 +258,6 @@ class Guild(DataModel):
             * MANAGE_ROLES → required to delete a role in the guild
 
         Args:
-            role_id (int): id of role to delete
+            role_id (int): ID of role to delete
         """
         await self._http.request('DELETE', f'/guilds/{self.id}/roles/{role_id}')