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

scurrypy/models.py

@@ -0,0 +1,258 @@
+from dataclasses import dataclass
+from typing import Optional
+from .model import DataModel
+
+from urllib.parse import quote
+
+@dataclass
+class EmojiModel(DataModel):
+    """Represents a Discord emoji."""
+    name: str
+    """Name of emoji."""
+
+    id: int = 0
+    """ID of the emoji (if custom)."""
+
+    animated: bool = False
+    """If the emoji is animated. Defaults to False."""
+
+    @property
+    def mention(self) -> str:
+        """For use in message content."""
+        return f"<a:{self.name}:{self.id}>" if self.animated else f"<:{self.name}:{self.id}>"
+
+    @property
+    def api_code(self) -> str:
+        """Return the correct API code for this emoji (URL-safe)."""
+        if not self.id:
+            # unicode emoji
+            return quote(self.name)
+
+        # custom emoji
+        if self.animated:
+            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.
+
+            !!! warning "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}"
+
+# Guild Models
+
+@dataclass
+class ReadyGuildModel(DataModel):
+    """Guild info from Ready event."""
+    id: int
+    """ID of the associated guild."""
+
+    unavailable: bool
+    """If the guild is offline."""
+
+@dataclass
+class GuildModel(DataModel):
+    """Represents a Discord guild."""
+
+    id: int
+    """ID of the guild."""
+
+    name: str
+    """Name of the guild."""
+
+    icon: Optional[str] = None
+    """Icon hash of the guild."""
+
+    emojis: list[EmojiModel] = None
+    """List of emojis reigstered in the guild."""
+
+    approximate_member_count: Optional[int] = None
+    """Approximate member count."""
+
+    description: str = None
+    """Description of the guild."""
+
+# User Models
+
+@dataclass
+class UserModel(DataModel):
+    """Describes the User object."""
+    id: int
+    """ID of the user."""
+
+    username: str
+    """Username of the user."""
+
+    avatar: str
+    """Avatar hash of the user."""
+
+@dataclass
+class ApplicationModel(DataModel):
+    """Represents a bot application object."""
+    id: int
+    """ID of the app."""
+
+    name: str
+    """Name of the app."""
+
+    icon: str
+    """Icon hash of the app."""
+
+    description: str
+    """Description of the app."""
+
+    bot_public: bool
+    """If other users can add this app to a guild."""
+
+    bot: UserModel
+    """Partial user obhect for the bot user associated with the app."""
+
+    owner: UserModel
+    """Partial user object for the owner of the app."""
+
+    guild_id: int
+    """Guild ID associated with the app (e.g., a support server)."""
+
+    guild: GuildModel
+    """Partial guild object of the associated guild."""
+
+    approximate_guild_count: int
+    """Approximate guild member count."""
+
+@dataclass
+class IntegrationModel(DataModel):
+    """Represents a guild integration."""
+
+    id: int
+    """ID of the integration."""
+
+    name: str
+    """Name of the integration."""
+
+    type: str
+    """Type of integration (e.g., twitch, youtube, discord, or guild_subscription)."""
+
+    enabled: bool
+    """If the integration is enabled."""
+
+    application: Optional[ApplicationModel] = None
+    """The bot aaplication for Discord integrations."""
+
+@dataclass
+class MemberModel(DataModel):
+    """Represents a guild member."""
+
+    roles: list[int]
+    """List of roles registered to the guild member."""
+
+    user: UserModel
+    """User data associated with the guild member."""
+
+    nick: str
+    """Server nickname of the guild member."""
+
+    avatar: str
+    """Server avatar hash of the guild mmeber."""
+
+    joined_at: str
+    """ISO8601 timestamp of when the guild member joined server."""
+
+    deaf: bool
+    """If the member is deaf in a VC (input)."""
+
+    mute: bool
+    """If the member is muted in VC (output)."""
+
+# Interaction Models
+
+@dataclass
+class InteractionCallbackDataModel(DataModel):
+    """Represents the interaction callback object."""
+
+    id: int
+    """ID of the interaction."""
+
+    type: int
+    """Type of interaction."""
+
+    activity_instance_id: str
+    """Instance ID of activity if an activity was launched or joined."""
+
+    response_message_id: int
+    """ID of the message created by the interaction."""
+
+    response_message_loading: bool
+    """If the interaction is in a loading state."""
+
+    response_message_ephemeral: bool
+    """If the interaction is ephemeral."""
+
+@dataclass
+class InteractionCallbackModel(DataModel):
+    """Represents the interaction callback response object."""
+
+    interaction: InteractionCallbackDataModel
+    """The interaction object associated with the interaction response."""
+
+# Role Models
+
+@dataclass
+class RoleColors(DataModel):
+    """Role color data."""
+
+    primary_color: int
+    """Primary color of the role."""
+
+    secondary_color: int
+    """Secondary color of the role. Creates a gradient."""
+
+    tertiary_color: int
+    """Tertiary color of the role. Creates a holographic style."""
+
+@dataclass
+class RoleModel(DataModel):
+    """Represents a Discord role."""
+
+    id: int
+    """ID of the role."""
+
+    name: str
+    """Name of the role."""
+
+    colors: RoleColors
+    """Colors of the role."""
+
+    hoist: bool
+    """If the role is pinned in user listing."""
+
+    position: int
+    """Position of the role."""
+
+    permissions: str
+    """Permission bit set."""
+
+    managed: bool
+    """If the role is managed by an integration."""
+
+    mentionable: bool
+    """If the role is mentionable."""
+
+    flags: int
+    """Role flags combined as a bitfield."""
+
+    icon: Optional[str] = None
+    """Icon hash of the role."""
+
+    unicode_emoji: Optional[str] = None
+    """Unicode emoji of the role."""

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