scurrypy 0.1.0__py3-none-any.whl

discord/events/__init__.py

@@ -0,0 +1,33 @@
+# discord/events
+
+from .ready_event import ReadyEvent
+
+from .reaction_events import (
+    ReactionAddEvent,
+    ReactionRemoveEvent,
+    ReactionRemoveEmojiEvent,
+    ReactionRemoveAllEvent
+)
+
+from .guild_events import (
+    GuildCreateEvent,
+    GuildUpdateEvent,
+    GuildDeleteEvent
+)
+
+from .message_events import (
+    MessageCreateEvent,
+    MessageUpdateEvent,
+    MessageDeleteEvent
+)
+
+from .channel_events import (
+    GuildChannelCreateEvent,
+    GuildChannelUpdateEvent,
+    GuildChannelDeleteEvent,
+    ChannelPinsUpdateEvent
+)
+
+from .interaction_events import (
+    InteractionEvent
+)

discord/events/channel_events.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from typing import Optional
+from ..model import DataModel
+
+@dataclass
+class GuildChannelEvent(DataModel):
+    """Base guild channel event."""
+    id: int
+    """ID of the guild channel."""
+
+    type: int
+    """Type of channel."""
+
+    guild_id: Optional[int]
+    """Guild ID of the channel."""
+
+    position: Optional[int]
+    """Position of the channel within a category."""
+
+    name: Optional[str]
+    """Name of the channel."""
+
+    topic: Optional[str]
+    """Topic of the channel."""
+
+    nsfw: Optional[bool]
+    """If this channel is flagged NSFW."""
+
+    last_message_id: Optional[int]
+    """ID of the last message sent in the channel."""
+
+    parent_id: Optional[int]
+    """Category ID of the channel."""
+
+class GuildChannelCreateEvent(GuildChannelEvent):
+    """Received when a guild channel has been created."""
+    pass
+
+class GuildChannelUpdateEvent(GuildChannelEvent):
+    """Received when a guild channel has been updated."""
+    pass
+
+class GuildChannelDeleteEvent(GuildChannelEvent):
+    """Received when a guild channel has been deleted."""
+    pass
+
+@dataclass
+class ChannelPinsUpdateEvent(DataModel):
+    """Pin update event."""
+    channel_id: int
+    guild_id: Optional[int]
+    last_pin_timestamp: Optional[str]  # ISO8601 timestamp of last pinned message

discord/events/guild_events.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass
+from typing import Optional
+from ..model import DataModel
+from ..models import MemberModel
+from ..resources.channel import Channel
+
+@dataclass
+class GuildEvent(DataModel):
+    """Base guild event."""
+    joined_at: str
+    """ISO8601 timestamp of when app joined the guild."""
+
+    large: bool
+    """If the guild is considered large."""
+
+    member_count: int
+    """Total number of members in the guild."""
+
+    members: list[MemberModel]
+    """Users in the guild."""
+
+    channels: list[Channel]
+    """Channels in the guild."""
+
+    unavailable: Optional[bool]
+    """If the guild is unavailable due to an outage."""
+
+class GuildCreateEvent(GuildEvent):
+    """Received when the bot has joined a guild."""
+    pass
+
+class GuildUpdateEvent(GuildEvent):
+    """Received when a guild has been edited."""
+    pass
+
+class GuildDeleteEvent(GuildEvent):
+    """Received when the bot has left a guild or the guild was deleted."""
+    pass

discord/events/hello_event.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+from ..model import DataModel
+
+@dataclass
+class HelloEvent(DataModel):
+    """Heartbeat interval event."""
+
+    heartbeat_interval: int
+    """Heartbeat interval in milliseconds."""

discord/events/interaction_events.py

@@ -0,0 +1,145 @@
+from dataclasses import dataclass, field
+from typing import Optional
+from ..model import DataModel
+
+from ..resources.interaction import Interaction
+
+# ----- Command Interaction -----
+
+@dataclass
+class ApplicationCommandOptionData(DataModel):
+    """Represents the response options from a slash command."""
+    name: str
+    """Name of the command option."""
+
+    type: int
+    """Type of command option. See [`CommandOptionTypes`][discord.parts.command.CommandOptionTypes]."""
+
+    value: str | int | float | bool
+    """Input value for option."""
+
+@dataclass
+class ApplicationCommandData(DataModel):
+    """Represents the response from a command."""
+    id: int
+    """ID of the command."""
+
+    name: str
+    """Name of the command."""
+    
+    type: int
+    """Type of command (e.g., message, user, slash)."""
+
+    guild_id: Optional[int]
+    """ID of guild from which the command was invoked."""
+
+    target_id: Optional[int]
+    """ID of the user or message from which the command was invoked (message/user commands only)."""
+
+    options: Optional[list[ApplicationCommandOptionData]] = field(default_factory=list)
+    """Options of the command (slash command only)."""
+
+    def get_command_option_value(self, option_name: str):
+        """Get the input for a command option by name.
+
+        Args:
+            option_name (str): option to fetch input from
+
+        Raises:
+            ValueError: invalid option name
+
+        Returns:
+            (str | int | float | bool): input data of specified option
+        """
+        for option in self.options:
+            if option_name != option.name:
+                continue
+
+            return option.value
+        
+        raise ValueError(f"Option name '{option_name}' could not be found.")
+
+# ----- Component Interaction -----
+
+@dataclass
+class MessageComponentData(DataModel):
+    """Represents the select response from a select component."""
+
+    custom_id: str
+    """Unique ID associated with the component."""
+
+    component_type: int
+    """Type of component."""
+
+    values: Optional[list[str]] = field(default_factory=list)
+    """Select values (if any)."""
+
+# ----- Modal Interaction -----
+
+@dataclass
+class ModalComponentData(DataModel):
+    """Represents the modal field response from a modal."""
+    type: int
+    """Type of component."""
+    
+    value: Optional[str]
+    """Text input value (Text Input component only)."""
+
+    values: Optional[list[str]]
+    """String select values (String Select component only)."""
+
+    custom_id: str
+    """Unique ID associated with the component."""
+
+@dataclass
+class ModalComponent(DataModel):
+    """Represents the modal component response from a modal."""
+    type: int
+    """Type of component."""
+
+    component: ModalComponentData
+    """Data associated with the component."""
+
+@dataclass
+class ModalData(DataModel):
+    """Represents the modal response from a modal."""
+    
+    custom_id: str
+    """Unique ID associated with the modal."""
+
+    components: list[ModalComponent] = field(default_factory=list)
+    """Components on the modal."""
+
+    def get_modal_data(self, custom_id: str):
+        """Fetch a modal field's data by its custom ID
+
+        Args:
+            custom_id (str): custom ID of field to fetch
+
+        Raises:
+            ValueError: invalid custom ID
+
+        Returns:
+            (str | list[str]): component values (if string select) or value (if text input)
+        """
+        for component in self.components:
+            if custom_id != component.component.custom_id:
+                continue
+
+            match component.component.type:
+                case 3: # string select -> values
+                    return component.component.values
+                case 4: # text input -> value
+                    return component.component.value
+
+        raise ValueError(f"Component custom id '{custom_id}' not found.")
+
+@dataclass
+class InteractionEvent(DataModel):
+    """Represents the interaction response."""
+
+    interaction: Interaction
+    """Interaction resource object. See [`Interaction`][discord.resources.interaction.Interaction]."""
+
+    data: Optional[ApplicationCommandData | MessageComponentData | ModalData] = None
+    """Interaction response data."""

discord/events/message_events.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass
+from typing import Optional
+from ..model import DataModel
+
+from ..resources.message import Message
+from ..models.member import MemberModel
+
+@dataclass
+class MessageCreateEvent(DataModel):
+    """Received when a message is created."""
+    message: Message
+    """Message resource object. See [`Resource.Message`][discord.resources.message.Message]."""
+
+    guild_id: Optional[int]
+    """Guild ID of the updated message (if in a guild channel)."""
+
+    member: Optional[MemberModel]  # guild-only author info
+    """Partial Member object of the author of the message. See [`MemberModel`][discord.models.member.MemberModel]."""
+    
+@dataclass
+class MessageUpdateEvent(DataModel):
+    """Received when a message is updated."""
+    message: Message
+    """Message resource object. See [`Resource.Message`][discord.resources.message.Message]."""
+
+    guild_id: Optional[int]
+    """Guild ID of the updated message (if in a guild channel)."""
+
+    member: Optional[MemberModel]
+    """Partial Member object of the author of the message. See [`MemberModel`][discord.models.member.MemberModel]."""
+
+@dataclass
+class MessageDeleteEvent(DataModel):
+    """Received when a message is deleted."""
+
+    id: int
+    """ID of the deleted message."""
+
+    channel_id: int
+    """Channel ID of the deleted message."""
+
+    guild_id: Optional[int]
+    """Guild ID of the deleted message (if in a guild channel)."""

discord/events/reaction_events.py

@@ -0,0 +1,99 @@
+from dataclasses import dataclass
+from typing import Optional
+from ..model import DataModel
+
+from ..models.member import MemberModel
+from ..models.emoji import EmojiModel
+
+class ReactionType:
+    """Reaction types."""
+
+    NORMAL = 0
+    """A standard emoji."""
+
+    BURST = 1
+    """A super emoji."""
+
+@dataclass
+class ReactionAddEvent(DataModel):
+    """Reaction added event."""
+
+    type: int
+    """Type of reaction added."""
+
+    user_id: int
+    """ID of user who added the emoji."""
+
+    emoji: EmojiModel
+    """Emoji used to react."""
+
+    channel_id: int
+    """ID of the channel where the reaction took place."""
+
+    message_id: int
+    """ID of the message where the reaction took place."""
+
+    guild_id: Optional[int]
+    """ID of the guild where the reaction took place (if in a guild)."""
+
+    burst: bool
+    """Whether the emoji is super."""
+
+    member: Optional[MemberModel]
+    """Partial member object of the guild member that added the emoji (if in a guild)."""
+
+    message_author_id: Optional[int]
+    """ID of the user who sent the message where the reaction was added."""
+
+@dataclass
+class ReactionRemoveEvent(DataModel):
+    """Reaction removed event."""
+
+    type: int
+    """Type of reaction removed."""
+
+    user_id: int
+    """ID of user who removed their reaction."""
+
+    emoji: EmojiModel
+    """Emoji data of the emoji where the reaction was removed."""
+
+    channel_id: int
+    """ID of the channel where the reaction was removed."""
+
+    message_id: int
+    """ID of the message where the reaction was removed."""
+
+    guild_id: Optional[int]
+    """ID of the guild where the reaction was removed (if in a guild)."""
+
+    burst: bool
+    """If the emoji of the removed reaction is super."""
+
+class ReactionRemoveAllEvent(DataModel):
+    """Remove all reactions event."""
+
+    channel_id: int
+    """ID of the channel where all reaction were removed."""
+
+    message_id: int
+    """ID of the message where all reaction were removed."""
+
+    guild_id: Optional[int]
+    """ID of the guild where all reaction were removed (if in a guild)."""
+
+@dataclass
+class ReactionRemoveEmojiEvent(DataModel):
+    """All reactions of a specific emoji removed."""
+
+    emoji: EmojiModel
+    """Emoji data of the removed reaction emoji."""
+
+    channel_id: int
+    """ID of the channel where the reaction emoji was removed."""
+
+    message_id: int
+    """ID of the message where the reaction emoji was removed."""
+
+    guild_id: Optional[int]
+    """ID of the guild where the reaction emoji was removed. (if in a guild)"""

discord/events/ready_event.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+from ..model import DataModel
+from ..models.user import UserModel
+from ..models.guild import ReadyGuildModel
+from ..models.application import ApplicationModel
+
+@dataclass
+class ReadyEvent(DataModel):
+    """Received when bot goes online."""
+
+    v: int
+    """API version number."""
+
+    user: UserModel
+    """Information about the user."""
+
+    guilds: list[ReadyGuildModel]
+    """List of guilds bot is in."""
+
+    session_id: str
+    """Used for resuming connections."""
+
+    resume_gateway_url: str
+    """Gateway URL for resuming connections."""
+
+    shard: list[int]
+    """Shard information associated with this session."""
+
+    application: ApplicationModel
+    """Partial application object. Contains ID and flags."""

discord/gateway.py

@@ -0,0 +1,175 @@
+import asyncio
+import json
+import websockets
+
+from .logger import Logger
+from .events.hello_event import HelloEvent
+
+DISCORD_OP_CODES = {
+    0: "Dispatch",
+    1: "Heartbeat",
+    2: "Identify",
+    3: "Presence Update",
+    6: "Resume",
+    7: "Reconnect",
+    8: "Request Guild Members",
+    9: "Invalid Session",
+    10: "Hello",
+    11: "Heartbeat ACK",
+    None: "Unknown"
+}
+
+class GatewayClient:
+    """Handles real-time Websocket (WS) connection to Discord's Gateway.
+        Connects to Discord's WS, handles identify/resume logic, and maintains heartbeat.
+    """
+    def __init__(self, token: str, intents: int, logger: Logger):
+        self.token = token
+        """The bot's token."""
+
+        self._logger = logger
+        """Logger instance to log events."""
+
+        self.ws = None
+        """Websocket instance."""
+
+        self.heartbeat = None
+        """Heartbeat task instance."""
+
+        self.sequence = None
+        """Discord-generated sequence number for this websocket connection."""
+
+        self.session_id = None
+        """Discord-generated session ID for this websocket connection."""
+
+        self.intents = intents
+        """User-defined bot intents (for identify)."""
+
+        self.url_params = "?v=10&encoding=json"
+        """Discord WS query params."""
+
+        self.connect_url = f"wss://gateway.discord.gg/"
+        """URL to connect to Discord's gateway."""
+
+    async def connect(self):
+        """Established websocket connection to Discord."""
+        try:
+            self.ws = await websockets.connect(self.connect_url + self.url_params)
+            self._logger.log_high_priority("Connected to Discord.")
+        except Exception as e:
+            self._logger.log_error(f"Websocket Connection Error {type(e).__name__} - {e}")
+    
+    async def receive(self):
+        """Receives and logs messages from the gateway.
+
+        Returns:
+            (dict): parsed JSON data
+        """
+        try:
+            message = await self.ws.recv()
+            if message:
+                data: dict = json.loads(message)
+                self._logger.log_debug(f"Received: {DISCORD_OP_CODES.get(data.get('op'))} - {json.dumps(data, indent=4)}")
+                self._logger.log_info(f"Received: {DISCORD_OP_CODES.get(data.get('op'))}")
+                return data
+            else:
+                return None
+        except Exception as e:
+            self._logger.log_error(f"Error on receive: {type(e).__name__} - {e}")
+    
+    async def send(self, message: dict):
+        """Sends a JSON-encoded message to the gateway.
+
+        Args:
+            message (dict): the message to send
+        """
+        try:
+            await self.ws.send(json.dumps(message))
+        except Exception as e:
+            self._logger.log_error(f"Error on send: {type(e).__name__} - {e}")
+        
+    async def send_heartbeat_loop(self):
+        """Background task that sends heartbeat payloads in regular intervals.
+            Retries until cancelled.
+        """
+        try:
+            while True:
+                await asyncio.sleep(self.heartbeat_interval / 1000)
+                hb_data = {"op": 1, "d": self.sequence}
+                await self.send(hb_data)
+                self._logger.log_debug(f"Sending: {hb_data}")
+                self._logger.log_info("Heartbeat sent.")
+        except asyncio.CancelledError:
+            self._logger.log_debug("Heartbeat task cancelled")
+        except Exception as e:
+            self._logger.log_error(f"Error on heartbeat send: {type(e).__name__} - {e}")
+        
+    async def identify(self):
+        """Sends the IDENIFY payload (token, intents, connection properties).
+            Must be sent after connecting to the WS.
+        """
+        i = {
+            "op": 2,
+            "d": {
+                "token": f"Bot {self.token}",
+                "intents": self.intents,
+                "properties": {
+                    "$os": "my_os",
+                    "$browser": "my_bot",
+                    "$device": "my_bot"
+                }
+            }
+        }
+        await self.send(i)
+        log_i = self._logger.redact(i)
+        self._logger.log_debug(f"Sending: {log_i}")
+        self._logger.log_high_priority("Identify sent.")
+    
+    async def start_heartbeat(self):
+        """Waits for initial HELLO event, hydrates the HelloEvent class, and begins the heartbeat."""
+        try:
+            data = await self.receive()
+            hello = HelloEvent.from_dict(data.get('d'))
+            self.heartbeat_interval = hello.heartbeat_interval
+            self.heartbeat = asyncio.create_task(self.send_heartbeat_loop())
+            self._logger.log_high_priority("Heartbeat started.")
+        except Exception as e:
+            self._logger.log_error(f"Heartbeat Task Error: {type(e).__name__} - {e}")
+    
+    async def reconnect(self):
+        """Sends RESUME payload to reconnect with the same session ID and sequence number
+            as provided by Discord.
+        """
+        await self.send({
+            "op": 6,
+            "d": {
+                "token": f"Bot {self.token}",
+                "session_id": self.session_id,
+                "seq": self.sequence
+            }
+        })
+        self._logger.log_high_priority("RESUME sent")
+        
+    async def close(self):
+        """Cancels heart beat and cleanly closes WS with error handling."""
+        # Cancel heartbeat task if it's still running
+        if self.heartbeat:
+            self._logger.log_high_priority(f"Cancelling heartbeat...")
+            self.heartbeat.cancel()
+            try:
+                await asyncio.wait_for(self.heartbeat, timeout=3)  # Add timeout to avoid hanging
+            except asyncio.CancelledError:
+                self._logger.log_debug("Heartbeat cancelled by CancelledError.")
+            except asyncio.TimeoutError:
+                self._logger.log_error("Heartbeat cancel timed out.")
+            except Exception as e:
+                self._logger.log_error(f"Unexpected error cancelling heartbeat: {type(e).__name__} - {e}")
+            self.heartbeat = None
+
+        if self.ws:
+            try:
+                await self.ws.close()
+                self._logger.log_high_priority("WebSocket closed.")
+            except Exception as e:
+                self._logger.log_error(f"Error while closing websocket: {type(e).__name__} - {e}")
+            self.ws = None