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

{discord → scurrypy}/dispatch/prefix_dispatcher.py

@@ -3,10 +3,11 @@ from ..client_like import ClientLike
 from ..events.message_events import MessageCreateEvent
 
 from ..resources.message import Message
-from ..models.member import MemberModel
+from ..models import MemberModel
 
 class PrefixDispatcher:
     """Handles text-based command messages that start with a specific prefix."""
+    
     def __init__(self, client: ClientLike, prefix: str):
 
         self.bot = client
@@ -18,6 +19,9 @@ class PrefixDispatcher:
         self._logger = client._logger
         """Logger instance to log events."""
 
+        self.application_id = client.application_id
+        """The client's application ID."""
+
         self.prefix = prefix
         """User-defined command prefix."""
 
@@ -28,13 +32,13 @@ class PrefixDispatcher:
         """Mapping of command prefix names to handler"""
 
     def register(self, name: str, handler):
-        """Registers a handler for a command name (case-insensitive)
+        """Registers a handler for a command name
 
         Args:
             name (str): name of handler (and command)
             handler (callable): handler callback
         """
-        self._handlers[name.lower()] = handler
+        self._handlers[name] = handler
 
     async def dispatch(self, data: dict):
         """Hydrate the corresponding dataclass and call the handler.
@@ -48,12 +52,27 @@ class PrefixDispatcher:
             member=MemberModel.from_dict(data.get('member'))
         )
 
-        if event.message._has_prefix(self.prefix):
-            command, *args = event.message._extract_args(self.prefix)
-            handler = self._handlers.get(command)
-            if handler:
-                try:
-                    await handler(self.bot, event, *args)
-                    self._logger.log_info(f"Prefix Event '{command}' Acknowledged.")
-                except Exception as e:
-                    self._logger.log_error(f"Error in prefix command '{command}': {e}")
+        # ignore bot responding to itself
+        if event.message.author.id == self.application_id:
+            return
+
+        # ignore messages without prefix
+        if not event.message._has_prefix(self.prefix):
+            return
+        
+        command, *args = event.message._extract_args(self.prefix)
+        handler = self._handlers.get(command)
+
+        # warn if this command doesnt have a known handler
+        if not handler:
+            self._logger.log_warn(f"Prefix Event '{command}' not found.")
+            return
+
+        # now prefix info can be confidently set
+        try:
+            event.prefix_args = list(args)
+            await handler(self.bot, event)
+            
+            self._logger.log_info(f"Prefix Event '{command}' acknowledged with args: {event.prefix_args or 'No args'}")
+        except Exception as e:
+            self._logger.log_error(f"Error in prefix command '{command}': {e}")

{discord → scurrypy}/error.py

@@ -1,12 +1,6 @@
-METHOD_SUCCESS_CODES = {
-    "GET": (200),
-    "POST": (200, 201),
-    "PATCH": (200, 201),
-    "DELETE": (200, 204)
-}
-
 class DiscordError(Exception):
     """Represents a Discord API error."""
+
     def __init__(self, status: int, data: dict):
         """Initialize the error with Discord's response.
             Extracts reason, code, and walks the nested errors.
@@ -15,22 +9,14 @@ class DiscordError(Exception):
             data (dict): Discord's error JSON
         """
         self.data = data
-        """Raw error data."""
-
+        self.status = status
         self.reason = data.get('message', 'Unknown Error')
-        """Discord-generated reason for error."""
-
-        self.code = data.get('code', '???')
-        """Discord-generated code of error."""
+        self.code = data.get('code', 'Unknown Code')
 
         self.error_data = data.get('errors', {})
-        """Error-specific data."""
-
         self.details = self.walk(self.error_data)
-        """Error details."""
 
-        self.fatal = status in (401, 403)
-        """If this error is considered fatal."""
+        self.is_fatal = status in (401, 403)
 
         errors = [f"→ {path}: {reason}" for path, reason in self.details]
         full_message = f"{self.reason} ({self.code})"
@@ -58,6 +44,8 @@ class DiscordError(Exception):
                 if key == '_errors' and isinstance(value, list):
                     msg = value[0].get('message', 'Unknown error')
                     result.append(('.'.join(path), msg))
+
+                # the value should not be a dict -- keep going
                 elif isinstance(value, dict):
                     result.extend(self.walk(value, path + [key]))
         return result

{discord → scurrypy}/events/channel_events.py

@@ -46,8 +46,9 @@ class GuildChannelDeleteEvent(GuildChannelEvent):
     pass
 
 @dataclass
-class ChannelPinsUpdateEvent:
+class ChannelPinsUpdateEvent(DataModel):
     """Pin update event."""
+    
     channel_id: int
     """ID of channel where the pins were updated."""
 

scurrypy/events/gateway_events.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from ..model import DataModel
+
+@dataclass
+class SessionStartLimit(DataModel):
+    """Represents the Session Start Limit object."""
+
+    total: int
+    """Total remaining shards."""
+
+    remaining: int
+    """Shards left to connect."""
+
+    reset_after: int
+    """When `remaining` resets from now (in ms)."""
+
+    max_concurrency: int
+    """How many shards can be started at once."""
+
+@dataclass
+class GatewayEvent(DataModel):
+    """Represents the Gateway Event object."""
+
+    url: str 
+    """Gateway URL to connect."""
+
+    shards: int
+    """Recommended shard count for the aaplication."""
+
+    session_start_limit: SessionStartLimit
+    """Session start info."""

{discord → scurrypy}/events/guild_events.py

@@ -1,12 +1,13 @@
 from dataclasses import dataclass
 from ..model import DataModel
 
-from ..models.member import MemberModel
+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."""
 

{discord → scurrypy}/events/interaction_events.py

@@ -3,17 +3,20 @@ from typing import Optional
 from ..model import DataModel
 
 from ..resources.interaction import Interaction
+from ..parts.components import ComponentTypes
+
 
 # ----- 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]."""
+    """Type of command option. See [`CommandOptionTypes`][scurrypy.parts.command.CommandOptionTypes]."""
 
     value: str | int | float | bool
     """Input value for option."""
@@ -21,6 +24,7 @@ class ApplicationCommandOptionData(DataModel):
 @dataclass
 class ApplicationCommandData(DataModel):
     """Represents the response from a command."""
+
     id: int
     """ID of the command."""
 
@@ -39,7 +43,7 @@ class ApplicationCommandData(DataModel):
     options: Optional[list[ApplicationCommandOptionData]] = field(default_factory=list)
     """Options of the command (slash command only)."""
 
-    def get_command_option_value(self, option_name: str):
+    def get_command_option_value(self, option_name: str, default = None):
         """Get the input for a command option by name.
 
         Args:
@@ -52,12 +56,14 @@ class ApplicationCommandData(DataModel):
             (str | int | float | bool): input data of specified option
         """
         for option in self.options:
-            if option_name != option.name:
-                continue
-
-            return option.value
+            if option.name == option_name:
+                return option.value
+        
+        if default is not None:
+            return default
         
-        raise ValueError(f"Option name '{option_name}' could not be found.")
+        raise ValueError(f"Option '{option_name}' not found")
+
 
 # ----- Component Interaction -----
 
@@ -74,26 +80,29 @@ class MessageComponentData(DataModel):
     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."""
 
+    values: Optional[list[str]] = field(default_factory=list)
+    """String select values (String Select component only)."""
+
 @dataclass
 class ModalComponent(DataModel):
     """Represents the modal component response from a modal."""
+
     type: int
     """Type of component."""
 
@@ -128,20 +137,26 @@ class ModalData(DataModel):
 
             t = component.component.type
 
-            if t in [3,5,6,7,8]: # select menus (w. possibly many option selects!)
+            if t in [
+                ComponentTypes.STRING_SELECT, 
+                ComponentTypes.USER_SELECT, 
+                ComponentTypes.ROLE_SELECT, 
+                ComponentTypes.MENTIONABLE_SELECT, 
+                ComponentTypes.CHANNEL_SELECT      # select menus (w. possibly many option selects!)
+            ]:
                 return component.component.values
             
             # text input
             return component.component.value
 
-        raise ValueError(f"Component custom id '{custom_id}' not found.")
+        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]."""
+    """Interaction resource object. See [`Interaction`][scurrypy.resources.interaction.Interaction]."""
 
     data: Optional[ApplicationCommandData | MessageComponentData | ModalData] = None
     """Interaction response data."""

{discord → scurrypy}/events/message_events.py

@@ -3,31 +3,34 @@ from typing import Optional
 from ..model import DataModel
 
 from ..resources.message import Message
-from ..models.member import MemberModel
+from ..models import MemberModel
 
 @dataclass
 class MessageCreateEvent(DataModel):
     """Received when a message is created."""
     message: Message
-    """Message resource object. See [`Resource.Message`][discord.resources.message.Message]."""
+    """Message resource object. See [`Resource.Message`][scurrypy.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]."""
+    """Partial Member object of the author of the message. See [`MemberModel`][scurrypy.models.MemberModel]."""
+
+    prefix_args: Optional[list[str]] = None
+    """Prefix args as a list of string if a prefix command was made."""
     
 @dataclass
 class MessageUpdateEvent(DataModel):
     """Received when a message is updated."""
     message: Message
-    """Message resource object. See [`Resource.Message`][discord.resources.message.Message]."""
+    """Message resource object. See [`Resource.Message`][scurrypy.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]."""
+    """Partial Member object of the author of the message. See [`MemberModel`][scurrypy.models.MemberModel]."""
 
 @dataclass
 class MessageDeleteEvent(DataModel):

{discord → scurrypy}/events/reaction_events.py

@@ -2,8 +2,7 @@ from dataclasses import dataclass
 from typing import Optional
 from ..model import DataModel
 
-from ..models.member import MemberModel
-from ..models.emoji import EmojiModel
+from ..models import MemberModel, EmojiModel
 
 class ReactionType:
     """Reaction types."""

{discord → scurrypy}/events/ready_event.py

@@ -1,9 +1,7 @@
 from dataclasses import dataclass
 from ..model import DataModel
 
-from ..models.user import UserModel
-from ..models.guild import ReadyGuildModel
-from ..models.application import ApplicationModel
+from ..models import UserModel, ReadyGuildModel, ApplicationModel
 
 @dataclass
 class ReadyEvent(DataModel):

scurrypy/gateway.py

@@ -0,0 +1,183 @@
+import asyncio
+import json
+import websockets
+
+from .client_like import ClientLike
+
+class GatewayClient:
+    def __init__(self, client: ClientLike, gateway_url: str, shard_id: int, total_shards: int):
+        """Initialize this websocket.
+
+        Args:
+            client (ClientLike): the bot client
+            gateway_url (str): gateway URL provided by GET /gateway/bot endpoint
+            shard_id (int): assigned shard ID
+            total_shards (int): total shard count provided by GET /gateway/bot endpoint
+        """
+        self.token = client.token
+        self.intents = client.intents
+        self.logger = client._logger
+        self.shard_id = shard_id
+        self.total_shards = total_shards
+        self.ws = None
+        self.seq = None
+        self.session_id = None
+        self.heartbeat_task = None
+        self.heartbeat_interval = None
+        self.event_queue = asyncio.Queue()
+
+        self.base_url = gateway_url
+        self.url_params = "?v=10&encoding=json"
+
+    async def connect_ws(self):
+        """Connect to Discord's Gateway (websocket)."""
+
+        try:
+            # connect to websocket
+            self.ws = await websockets.connect(self.base_url + self.url_params)
+            self.logger.log_high_priority(f"SHARD ID {self.shard_id}: Connected to Discord!")
+
+            # wait to recv HELLO
+            hello = await self.receive()
+
+            # extra info from recv'd HELLO
+            self.heartbeat_interval = hello["d"]["heartbeat_interval"] / 1000
+            self.seq = hello.get('s')
+
+            # start heartbeat in background
+            self.heartbeat_task = asyncio.create_task(self.heartbeat())
+
+        except Exception as e:
+            self.logger.log_error(f"SHARD ID {self.shard_id}: Connection Error - {e}")
+
+    async def start(self):
+        """Starts the websocket and handles reconnections."""
+
+        backoff = 1
+        while True:
+            try:
+                await self.connect_ws()
+                
+                if self.session_id and self.seq:
+                    await self.resume()
+                else:
+                    await self.identify()
+                
+                await self._listen()  # blocks until disconnect
+
+            except (ConnectionError, websockets.exceptions.ConnectionClosedError) as e:
+                self.logger.log_error(f"SHARD ID {self.shard_id}: Disconnected: {e}, reconnecting in {backoff}s...")
+                await self.close_ws()
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, 30)
+            except asyncio.CancelledError:
+                # only break; don't close here — let Client handle shutdown
+                break
+            except Exception as e:
+                self.logger.log_error(f"SHARD ID {self.shard_id}: Unhandled error - {e}")
+                await self.close_ws()
+                await asyncio.sleep(backoff)
+
+    async def send(self, data: dict):
+        """Send data through the websocket."""
+
+        try:
+            await self.ws.send(json.dumps(data))
+        except Exception:
+            raise
+
+    async def receive(self):
+        """Receive data through the websocket."""
+
+        try:
+            return json.loads(await self.ws.recv())
+        except Exception:
+            raise
+    
+    async def heartbeat(self):
+        """Heartbeat task to keep connection alive."""
+        while self.ws:
+            await asyncio.sleep(self.heartbeat_interval)
+            await self.send({"op": 1, "d": self.seq})
+            self.logger.log_info(f"SHARD ID {self.shard_id} Heartbeat sent")
+
+    async def identify(self):
+        """Send an IDENTIFY payload to handshake for bot."""
+
+        await self.send({
+            'op': 2,
+            'd': {
+                'token': f"Bot {self.token}",
+                'intents': self.intents,
+                'properties': {
+                    'os': 'my_os',
+                    'browser': 'my_browser',
+                    'device': 'my_device'
+                },
+                'shards': [self.shard_id, self.total_shards]
+            }
+        })
+        self.logger.log_info(f"SHARD ID {self.shard_id}: IDENIFY Sent.")
+
+    async def resume(self):
+        """Send a RESUME payload to resume a connection."""
+
+        await self.send({
+            'op': 6,
+            'd': {
+                'token': f"Bot {self.token}",
+                'session_id': self.session_id,
+                'seq': self.seq
+            }
+        })
+        self.logger.log_info("Resume Sent.")
+
+    async def _listen(self):
+        """Listen for events and queue them to be picked up by Client."""
+
+        while self.ws:
+            try:
+                data = await self.receive()
+
+                op_code = data.get('op')
+                
+                match op_code:
+                    case 0:
+                        dispatcher_type = data.get('t')
+                        self.logger.log_info(f"SHARD ID {self.shard_id} DISPATCH -> {dispatcher_type}")
+                        event_data = data.get('d')
+                        self.seq = data.get('s') or self.seq
+
+                        if dispatcher_type == 'READY':
+                            self.session_id = event_data.get('session_id')
+                            self.base_url = event_data.get('resume_gateway_url') or self.base_url
+
+                        await self.event_queue.put((dispatcher_type, event_data))
+                    case 7:
+                        raise ConnectionError("Reconnect requested by server.")
+                    case 9:
+                        self.session_id = self.seq = None
+                        raise ConnectionError("Invalid session.")
+                    case 11:
+                        self.logger.log_info(f"SHARD ID {self.shard_id}: Heartbeat ACK")
+
+            except websockets.exceptions.ConnectionClosedOK:
+                break
+            except Exception as e:
+                self.logger.log_error(f"SHARD ID {self.shard_id}: Listen Error - {e}")
+                break
+    
+    async def close_ws(self):
+        """Close the websocket connection if one is still open."""
+
+        self.logger.log_high_priority(f"Closing Shard ID {self.shard_id}...")
+        if self.ws:
+            if self.heartbeat_task:
+                self.heartbeat_task.cancel()
+                try:
+                    await self.heartbeat_task
+                except asyncio.CancelledError:
+                    pass
+            await self.ws.close()
+
+        self.ws = None