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

scurrypy/model.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass, fields, is_dataclass
+from typing import get_args, get_origin, Union
+
+from .http import HTTPClient
+
+@dataclass
+class DataModel:    
+    """DataModel is a base class for Discord JSONs that provides hydration from raw dicts, 
+        optional field defaults, and access to HTTP-bound methods.
+    """
+    
+    @classmethod
+    def from_dict(cls, data: dict, http: 'HTTPClient' = None):
+        """Hydrates the given data into the dataclass child.
+
+        Args:
+            data (dict): JSON data
+            http (HTTPClient, optional): HTTP session for requests
+
+        Returns:
+            (dataclass): hydrated dataclass
+        """
+        def unwrap_optional(t):
+            if get_origin(t) is Union:
+                args = tuple(a for a in get_args(t) if a is not type(None))
+                return args[0] if len(args) == 1 else Union[args]
+            return t
+
+        kwargs = {}
+        for f in fields(cls):
+            v = data.get(f.name)
+            t = unwrap_optional(f.type)
+
+            if v is None:
+                kwargs[f.name] = None
+            elif is_dataclass(t):
+                kwargs[f.name] = t.from_dict(v, http)
+            elif get_origin(t) is list:
+                lt = get_args(t)[0]
+                kwargs[f.name] = [lt.from_dict(x, http) if is_dataclass(lt) else x for x in v]
+            else:
+                try:
+                    kwargs[f.name] = t(v)
+                except Exception:
+                    kwargs[f.name] = v  # fallback to raw
+
+        inst = cls(**kwargs)
+        if http: inst._http = http
+        return inst
+
+    def to_dict(self):
+        """Recursively turns the dataclass into a dictionary and drops empty fields.
+
+        Returns:
+            (dict): serialized dataclasss
+        """
+        def serialize(val):
+            if isinstance(val, list):
+                return [serialize(v) for v in val if v is not None]
+            if isinstance(val, DataModel):
+                return val.to_dict()
+            return val
+
+        result = {}
+        for f in fields(self):
+            if f.name.startswith('_'):
+                continue
+            val = getattr(self, f.name)
+            # if val not in (None, [], {}, "", 0):
+            result[f.name] = serialize(val)
+        return result

{discord → scurrypy}/models/emoji.py

@@ -13,7 +13,7 @@ class EmojiModel(DataModel):
     """ID of the emoji (if custom)."""
 
     animated: bool = False
-    """If the emoji is animated. Defaults to `False`."""
+    """If the emoji is animated. Defaults to False."""
 
     @property
     def mention(self) -> str:
@@ -32,3 +32,19 @@ class EmojiModel(DataModel):
             return quote(f"a:{self.name}:{self.id}")
         
         return quote(f"{self.name}:{self.id}")
+
+    @property
+    def url(self) -> str:
+        """
+            Return the full qualifying link for this emoji.
+
+            !!! important
+                This only works for custom Discord emojis (those with an ID). 
+                Unicode emojis will return `None`.
+        """
+        if not self.id:
+            return None
+        
+        ext = 'gif' if self.animated else 'png'
+
+        return f"https://cdn.discordapp.com/emojis/{self.id}.{ext}"

{discord → scurrypy}/models/interaction.py

@@ -3,6 +3,8 @@ from ..model import DataModel
 
 @dataclass
 class InteractionCallbackDataModel(DataModel):
+    """Represents the interaction callback object."""
+
     id: int
     """ID of the interaction."""
 
@@ -23,4 +25,7 @@ class InteractionCallbackDataModel(DataModel):
 
 @dataclass
 class InteractionCallbackModel(DataModel):
+    """Represents the interaction callback response object."""
+
     interaction: InteractionCallbackDataModel
+    """The interaction object associated with the interaction response."""

scurrypy/parts/channel.py

@@ -0,0 +1,42 @@
+from dataclasses import dataclass
+from typing import Optional
+from ..model import DataModel
+
+class ChannelTypes:
+    """
+        Constants for channel types.
+
+        !!! note
+            Only supported Channel Types listed here
+    """
+
+    GUILD_TEXT = 0
+    """Text channel within a server."""
+
+    GUILD_CATEGORY = 4
+    """Organizational category that contains up to 50 channels."""
+
+    GUILD_ANNOUNCEMENT = 5
+    """Channel that users can follow and crosspost into their own server (formerly news channels)."""
+
+@dataclass
+class GuildChannel(DataModel):
+    """Parameters for creating/editing a guild channel."""
+
+    name: Optional[str] = None
+    """Name of the channel."""
+
+    type: Optional[int] = None
+    """Type of channel. See [`ChannelTypes`][scurrypy.parts.channel.ChannelTypes]."""
+
+    topic: Optional[str] = None
+    """Topic of channel."""
+
+    position: Optional[int] = None
+    """Sorting position of the channel (channels with the same position are sorted by id)."""
+
+    parent_id: Optional[int] = None
+    """ID of the parent category for a channel."""
+
+    nsfw: Optional[bool] = None
+    """Whether the channel is NSFW."""

scurrypy/parts/command.py

@@ -0,0 +1,90 @@
+from dataclasses import dataclass, field
+
+from ..model import DataModel
+
+class CommandTypes:
+    CHAT_INPUT = 1
+    USER_COMMAND = 2
+    MESSAGE_COMMAND = 3
+
+class CommandOptionTypes:
+    """Slash command option input types."""
+
+    STRING = 3
+    """string (text)"""
+
+    INTEGER = 4
+    """integer (whole)"""
+
+    BOOLEAN = 5
+    """boolean (true/false)"""
+
+    USER = 6
+    """user pangination"""
+
+    CHANNEL = 7
+    """channel pangination"""
+
+    ROLE = 8
+    """role pangination"""
+
+    MENTIONABLE = 9
+    """any pangination (role, channel, user)"""
+
+    NUMBER = 10
+    """number (float, integer)"""
+
+    ATTACHMENT = 11
+    """file upload"""
+
+@dataclass
+class CommandOption(DataModel):
+    """Option for a slash command."""
+
+    type: int
+    """Type of option. See [`CommandOptionTypes`][scurrypy.parts.command.CommandOptionTypes]."""
+
+    name: str
+    """Name of option."""
+
+    description: str
+    """Description of option."""
+
+    required: bool = False
+    """Whether this option is required. Defaults to False."""
+
+@dataclass
+class SlashCommand(DataModel):
+    """Represents the slash command object."""
+
+    name: str
+    """Name of the command."""
+
+    description: str
+    """Description of the command."""
+
+    options: list[CommandOption] = field(default_factory=list)
+    """Parameters or options for the command."""
+
+    type: int = field(init=False, default=CommandTypes.CHAT_INPUT)
+    """Command type. Always `CommandTypes.CHAT_INPUT` for this class. See [`CommandTypes`][scurrypy.parts.command.CommandTypes]."""
+
+@dataclass
+class UserCommand(DataModel):
+    """Represents the user command object"""
+
+    name: str
+    """Name of the command."""
+
+    type: int = field(init=False, default=CommandTypes.USER_COMMAND)
+    """Command type. Always `CommandTypes.USER_COMMAND` for this class. See [`CommandTypes`][scurrypy.parts.command.CommandTypes]."""
+
+@dataclass
+class MessageCommand(DataModel):
+    """Represents the message command object."""
+    
+    name: str
+    """Name of the command."""
+
+    type: int = field(init=False, default=CommandTypes.MESSAGE_COMMAND)
+    """Command type. Always `CommandTypes.MESSAGE_COMMAND` for this class. See [`CommandTypes`][scurrypy.parts.command.CommandTypes]."""

scurrypy/parts/components.py

@@ -0,0 +1,224 @@
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+from ..model import DataModel
+
+from .component_types import *
+
+from ..models.emoji import EmojiModel
+
+class ComponentTypes:
+    ACTION_ROW = 1
+    BUTTON = 2
+    STRING_SELECT = 3
+    TEXT_INPUT = 4
+    USER_SELECT = 5
+    ROLE_SELECT = 6
+    MENTIONABLE_SELECT = 7
+    CHANNEL_SELECT = 8
+
+@dataclass
+class ActionRowPart(DataModel, ContainerChild):
+    """Represents a container of interactable components."""
+    
+    components: list[ActionRowChild] = field(default_factory=list)
+    """Up to 5 interactive button components or a single select component."""
+
+    type: int = field(init=False, default=ComponentTypes.ACTION_ROW)
+    """Component type. Always `ComponentTypes.ACTION_ROW` for this class. See [`ComponentTypes`][scurrypy.parts.components.ComponentTypes]."""
+
+class ButtonStyles:
+    """Represents button styles for a Button component."""
+
+    PRIMARY = 1
+    """The most important or recommended action in a group of options. (Blurple)"""
+
+    SECONDARY = 2
+    """Alternative or supporting actions. (Gray)"""
+
+    SUCCESS = 3
+    """Positive confirmation or completion actions. (Green)"""
+
+    DANGER = 4
+    """An action with irreversible consequences. (Red)"""
+
+    LINK = 5
+    """Navigates to a URL. (Gray + window)"""
+
+@dataclass
+class Button(DataModel, ActionRowChild, SectionAccessory):
+    """Represents the Button component."""
+
+    style: int
+    """A button style. See [`ButtonStyles`][scurrypy.parts.components.ButtonStyles]."""
+
+    custom_id: str
+    """ID for the button."""
+
+    label: Optional[str] = None
+    """Text that appears on the button."""
+
+    emoji: EmojiModel = None
+    """Partial emoji icon."""
+
+    url: Optional[str] = None
+    """URL for link-style buttons."""
+
+    disabled: Optional[bool] = False
+    """Whether the button is disabled. Defaults to False."""
+
+    type: int = field(init=False, default=ComponentTypes.BUTTON)
+    """Component type. Always `ComponentTypes.BUTTON` for this class. See [`ComponentTypes`][scurrypy.parts.components.ComponentTypes]."""
+
+@dataclass
+class SelectOption(DataModel):
+    """Represents the Select Option component"""
+
+    label: str
+    """User-facing name of the option."""
+
+    value: str
+    """Developer-defined value of the option."""
+
+    description: Optional[str] = None
+    """Additional description of the option."""
+
+    emoji: Optional[EmojiModel] = None
+    """Partial emoji obhect."""
+
+    default: Optional[bool] = False
+    """Whether this option is selected by default."""
+
+@dataclass
+class StringSelect(DataModel, ActionRowChild, LabelChild):
+    """Represents the String Select component."""
+
+    custom_id: str
+    """ID for the select menu."""
+
+    options: list[SelectOption] = field(default_factory=list)
+    """Specified choices in a select menu. See [`SelectOption`][scurrypy.parts.components.SelectOption]."""
+
+    placeholder: Optional[str] = None
+    """Placeholder text if nothing is selected or default."""
+
+    min_values: Optional[int] = 1
+    """Minimum number of items that must be chosen."""
+
+    max_values: Optional[int] = 1
+    """Maximum number of items that can be chosen."""
+
+    required: Optional[bool] = False
+    """Whether the string select is required to answer in a modal. Defaults to False."""
+
+    disabled: Optional[bool] = False # does not work on Modals!
+    """Whether select menu is disabled in a message. Defaults to False."""
+
+    type: int = field(init=False, default=ComponentTypes.STRING_SELECT)
+    """Component type. Always `ComponentTypes.STRING_SELECT` for this class. See [`ComponentTypes`][scurrypy.parts.components.ComponentTypes]."""
+
+class TextInputStyles:
+    """Represents the types of Text Inputs."""
+
+    SHORT = 1
+    """One line text input."""
+
+    PARAGRAPH = 2
+    """Multi-line text input."""
+
+@dataclass
+class TextInput(DataModel, LabelChild):
+    """Represents the Text Input component."""
+
+    style: TextInputStyles = TextInputStyles.SHORT
+    """Text input style. See [`TextInputStyles`][scurrypy.parts.components.TextInputStyles]."""
+
+    custom_id: str = None
+    """ID for the input."""
+
+    required: Optional[bool] = False
+    """Whether this component is required to be filled."""
+
+    min_length: Optional[int] = None
+    """Minimum input length for a text input."""
+
+    max_length: Optional[int] = None
+    """Maximum input length for a text input."""
+
+    required: Optional[bool] = True
+    """Whether this component is required to be filled. Defaults to True."""
+
+    value: Optional[str] = None
+    """Pre-filled value for this component."""
+
+    placeholder: Optional[str] = None
+    """Custom placeholder text if the input is empty."""
+
+    type: int = field(init=False, default=ComponentTypes.TEXT_INPUT)
+    """Component type. Always `ComponentTypes.TEXT_INPUT` for this class. See [`ComponentTypes`][scurrypy.parts.components.ComponentTypes]."""
+
+@dataclass
+class DefaultValue(DataModel):
+    """Represents the Default Value for Select components."""
+
+    id: int
+    """ID of role, user, or channel."""
+
+    type: Literal["role", "user", "channel"]
+    """Type of value that `id` represents."""
+
+@dataclass
+class SelectMenu(DataModel):
+    """Represents common fields for Discord's select menus."""
+
+    custom_id: str
+    """ID for the select menu."""
+
+    placeholder: Optional[str] = None
+    """Placeholder text if nothing is selected."""
+
+    default_values: list[DefaultValue] = field(default_factory=list)
+    """
+        List of default values for auto-populated select menu components. See [`DefaultValue`][scurrypy.parts.components.DefaultValue].
+        Number of default values must be in the range of `min_values` to `max_values`.
+    """
+
+    min_values: Optional[int] = 1
+    """Minimum number of items that must be chosen. Defaults to 1."""
+
+    max_values: Optional[int] = 1
+    """Maximum number of items that can be chosen. Defaults to 1."""
+
+    required: Optional[bool] = False
+    """Whether the user select is required to answer in a modal. Defaults to False."""
+
+    disabled: Optional[bool] = False
+    """Whether select menu is disabled in a message. Defaults to False."""
+
+
+@dataclass
+class UserSelect(SelectMenu, ActionRowChild, LabelChild):
+    """Represents the User Select component."""
+
+    type: int = field(init=False, default=ComponentTypes.USER_SELECT)
+    """Component type. Always `ComponentTypes.USER_SELECT` for this class. See [`ComponentTypes`][scurrypy.parts.components.ComponentTypes]."""
+
+@dataclass
+class RoleSelect(SelectMenu, ActionRowChild, LabelChild):
+    """Represents the Role Select component."""
+
+    type: int = field(init=False, default=ComponentTypes.ROLE_SELECT)
+    """Component type. Always `ComponentTypes.ROLE_SELECT` for this class. See [`ComponentTypes`][scurrypy.parts.components.ComponentTypes]."""
+
+@dataclass
+class MentionableSelect(SelectMenu, ActionRowChild, LabelChild):
+    """Represents the Mentionable Select component."""
+
+    type: int = field(init=False, default=ComponentTypes.MENTIONABLE_SELECT)
+    """Component type. Always `ComponentTypes.MENTIONABLE_SELECT` for this class. See [`ComponentTypes`][scurrypy.parts.components.ComponentTypes]."""
+
+@dataclass
+class ChannelSelect(SelectMenu, ActionRowChild, LabelChild):
+    """Represents the Channel Select component."""
+
+    type: int = field(init=False, default=ComponentTypes.CHANNEL_SELECT)
+    """Component type. Always `ComponentTypes.CHANNEL_SELECT` for this class. See [`ComponentTypes`][scurrypy.parts.components.ComponentTypes]."""

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]."""