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

scurrypy/http.py

@@ -0,0 +1,310 @@
+"""
+R = request
+EP = endpoint
+L = Lock
+Q = Queue
+H = header
+B = Bucket
+A + B = {A:B}
+
+[R + EP]--|L|-->[Q + EP]--|send R|-->[add/update H + B]
+    1. request by endpoint
+    2. push request to queue with lock
+    3. add/update header by bucket ID with send request
+
+    * Queue by ENDPOINT/REQUEST
+    * Bucket by HEADER
+"""
+
+import asyncio
+import aiohttp
+import aiofiles
+import json
+from typing import Any
+
+from dataclasses import dataclass
+
+from .error import DiscordError
+from .logger import Logger
+
+@dataclass
+class RequestItem:
+    method: str
+    endpoint: str
+    data: Any = None
+    params: dict = None
+    files: dict = None
+    future: asyncio.Future = None
+
+@dataclass
+class Bucket:
+    remaining: int
+    reset_after: float
+    reset_on: float
+    sleep_task: asyncio.Task = None
+
+class HTTPClient:
+    BASE = "https://discord.com/api/v10"
+    MAX_RETRIES = 3
+
+    def __init__(self, logger: Logger):
+        self.session = None
+        self.logger = logger
+
+        # PRE-REQUEST
+        self.queues: dict[str, asyncio.Queue] = {}  # maps EP -> Q
+        self.queues_lock = asyncio.Lock() # locks queues dict for editing
+
+        self.workers: dict[str, asyncio.Task] = {}  # maps EP -> worker
+
+        # POST-REQUEST
+        self.buckets: dict[str, Bucket] = {}  # maps B -> Bucket
+        self.bucket_lock: dict[str, asyncio.Lock] = {} # maps B to Lock
+        self.buckets_lock = asyncio.Lock() # locks buckets dict for editing
+
+        self.global_lock = asyncio.Lock()
+        self.global_reset = 0.0
+
+    async def start(self, token: str):
+        """Start the HTTP session."""
+
+        if not self.session:
+            self.session = aiohttp.ClientSession(headers={"Authorization": f"Bot {token}"})
+            self.logger.log_info("HTTP session started.")
+        else:
+            self.logger.log_warn("HTTP session already initialized.")
+
+    async def close(self):
+        """Gracefully stop all workers and close the HTTP session."""
+
+        if self.session: # just the session that needs to close!
+            await self.session.close()
+            self.logger.log_info("Session closed.")
+
+    async def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        data: Any | None = None,
+        params: dict | None = None,
+        files: Any | None = None,
+    ):
+        """Queue a request for the given endpoint.
+
+        Args:
+            method (str): HTTP method (e.g., POST, GET, DELETE, PATCH, etc.)
+            endpoint (str): Discord endpoint (e.g., /channels/123/messages)
+            data (dict, optional): relevant data
+            params (dict, optional): relevant query params
+            files (list[str], optional): relevant files
+
+        Returns:
+            (Future): result or promise of request
+        """
+
+        # ensure a queue is in place for the requested endpoint
+        async with self.queues_lock:
+            queue = self.queues.setdefault(endpoint, asyncio.Queue())
+
+        if endpoint not in self.workers:
+            self.workers[endpoint] = asyncio.create_task(self._worker(endpoint))
+
+        # set promise
+        future = asyncio.get_event_loop().create_future()
+
+        def sanitize_query_params(params: dict | None) -> dict | None:
+            """Sanitize a request's params for session.request
+
+            Args:
+                params (dict | None): query params (if any)
+
+            Returns:
+                (dict | None): the session.request-friendly version of params
+            """
+            if not params:
+                return None
+            return {k: ('true' if v is True else 'false' if v is False else v)
+                for k, v in params.items() if v is not None}
+
+        await queue.put(RequestItem(method, endpoint, data, sanitize_query_params(params), files, future))
+
+        # return promise
+        return await future
+
+    async def _worker(self, endpoint: str):
+        """Background worker that processes requests for this endpoint.
+
+        Args:
+            endpoint (str): the endpoint to receive requests
+        """
+
+        # fetch the queue by endpoint
+        queue = self.queues[endpoint]
+
+        while True:
+            # get the next item in the queue
+            item: RequestItem = await queue.get()
+
+            if item is None: # sentinel = time to stop
+                queue.task_done()
+                break
+
+            try:
+                result = await self._send(item)
+            except Exception as e:
+                item.future.set_exception(e)
+            else:
+                item.future.set_result(result)
+            finally:
+                queue.task_done()
+
+    async def _sleep_endpoint(self, endpoint: str, bucket: Bucket):
+        """Let an endpoint sleep for the designated reset_after seconds.
+
+        Args:
+            endpoint (str): endpoint to sleep
+            bucket (Bucket): endpoint's bucket info
+        """
+        self.logger.log_warn(f"Bucket {endpoint} rate limit is active. Sleeping for {bucket.reset_after}s...")
+        await asyncio.sleep(bucket.reset_after)
+        bucket.sleep_task = None
+        self.logger.log_high_priority(f"Bucket {endpoint} reset after {bucket.reset_after}s")
+
+    async def _check_global_rate_limit(self):
+        """Checks if the global rate limit is after now (active)."""
+        now = asyncio.get_event_loop().time()
+        if self.global_reset > now:
+            async with self.global_lock:
+                self.logger.log_warn(f"Global reset is active. Sleeping for {self.global_reset - now}s...")
+                await asyncio.sleep(self.global_reset - now)
+                self.logger.log_high_priority(f"Global has reset after {self.global_reset - now}s...")
+
+    async def _parse_response(self, resp: aiohttp.ClientResponse):
+        """Parse the request's response for response details.
+
+        Args:
+            resp (aiohttp.ClientResponse): the response object
+
+        Raises:
+            DiscordError: Error object for pretty printing if an error is returned.
+
+        Returns:
+            (str | dict | None): request info (if any)
+        """
+        match resp.status:
+            case 204:
+                return None
+            case 200 | 201 | 202:
+                try:
+                    return await resp.json()
+                except aiohttp.ContentTypeError:
+                    return await resp.text()
+            case _:
+                try:
+                    body = await resp.json()
+                except aiohttp.ContentTypeError:
+                    body = await resp.text()
+                raise DiscordError(resp.status, body)
+            
+    async def _update_bucket_rate_limit(self, resp: aiohttp.ClientResponse, bucket_id: str, endpoint: str):
+        """Update the bucket for this endpoint and sleep if necessary.
+
+        Args:
+            resp (aiohttp.ClientResponse): the response object
+            bucket_id (str): bucket ID provided by Discord's headers
+            endpoint (str): endpoint in which request was sent
+        """
+        # grab lock from dict of bucket locks with a lock on dict access
+        async with self.buckets_lock:
+            lock = self.bucket_lock.setdefault(bucket_id, asyncio.Lock())
+
+        # update/add the bucket with Bucket lock
+        async with lock:
+            remaining = int(resp.headers.get('x-ratelimit-remaining', 1))
+            reset_after = float(resp.headers.get('x-ratelimit-reset-after', 0))
+            reset_on = float(resp.headers.get('x-ratelimit-reset', 0))
+
+            bucket = self.buckets.get(bucket_id)
+
+            if not bucket:
+                bucket = Bucket(remaining, reset_after, reset_on)
+                self.buckets[bucket_id] = bucket
+            else:
+                bucket.remaining = remaining
+                bucket.reset_after = reset_after
+                bucket.reset_on = reset_on
+
+            if bucket.remaining == 0 and not bucket.sleep_task:
+                bucket.sleep_task = asyncio.create_task(
+                    self._sleep_endpoint(endpoint, bucket)
+                )
+
+            elif bucket.sleep_task and not bucket.sleep_task.done():
+                await bucket.sleep_task
+
+    async def _prepare_payload(self, item: RequestItem):
+        """Prepares the payload based on `RequestItem`.
+
+        Args:
+            item (RequestItem): the request object
+
+        Returns:
+            (dict): kwargs to pass to session.request
+        """
+        if item.files and any(item.files):
+            # payload = await self._make_payload(item.data, item.files)
+            form = aiohttp.FormData()
+            form.add_field("payload_json", json.dumps(item.data))
+
+            for idx, file_path in enumerate(item.files):
+                async with aiofiles.open(file_path, 'rb') as f:
+                    f_data = await f.read()
+                    form.add_field(
+                        f'files[{idx}]',
+                        f_data,
+                        filename=file_path.split('/')[-1],
+                        content_type='application/octet-stream'
+                    )
+
+            return {"data": form}
+
+        return {"json": item.data}
+
+    async def _send(self, item: RequestItem):
+        """Core HTTP request executor.
+
+        Sends a request to Discord, handling JSON payloads, files, query parameters,
+        and rate limits.
+
+        Args:
+            item (RequestItem): request object
+
+        Raises:
+            (DiscordError): If the request fails after the maximum number of retries
+                or receives an error response.
+
+        Returns:
+            (dict | str | None): Parsed JSON response if available, raw text if the
+                response is not JSON, or None for HTTP 204 responses.
+        """
+        await self._check_global_rate_limit()
+
+        kwargs = await self._prepare_payload(item)
+
+        url = f"{self.BASE.rstrip('/')}/{item.endpoint.lstrip('/')}"
+        
+        async with self.session.request(
+            method=item.method, url=url, params=item.params, timeout=15, **kwargs
+        ) as resp:
+
+            if resp.headers.get("X-RateLimit-Global") == "true":
+                retry_after = float(resp.headers.get("Retry-After", 0))
+                self.global_reset = asyncio.get_event_loop().time() + retry_after
+
+            bucket_id = resp.headers.get('x-ratelimit-bucket')
+
+            if bucket_id:
+                await self._update_bucket_rate_limit(resp, bucket_id, item.endpoint)
+
+            return await self._parse_response(resp)

{discord → scurrypy}/intents.py

@@ -54,11 +54,11 @@ class IntentFlagParams(TypedDict, total=False):
     message_content: bool
 
 def set_intents(**flags: Unpack[IntentFlagParams]):
-    """Set bot intents using [`IntentFlagParams`][discord.intents.IntentFlagParams].  
+    """Set bot intents. See [`Intents`][scurrypy.intents.Intents]  
     `Intents.DEFAULT` = (GUILDS | GUILD_MESSAGES) will also be set.
 
     Args:
-        flags (Unpack[IntentFlagParams]): intents to set. (set respective flag to True to toggle.)
+        **flags (Unpack[IntentFlagParams]): intents to set
 
     Raises:
         (ValueError): invalid flag
@@ -78,10 +78,8 @@ def set_intents(**flags: Unpack[IntentFlagParams]):
     }
 
     intents = Intents.DEFAULT
-    for name, value in flags.items():
-        if name not in _flag_map:
-            raise ValueError(f"Invalid flag: {name}")
-        if value:
-            intents |= _flag_map[name]
+    for k, v in flags.items():
+        if v:
+            intents |= _flag_map.get(k)
     
     return intents

{discord → scurrypy}/logger.py

@@ -14,20 +14,17 @@ class Logger:
     ERROR = '\033[31m'
     """Error color: RED"""
 
-    CRITICAL = '\033[41m'
-    """Critical color: RED HIGHLIGHT"""
-
     TIME = '\033[90m'
     """Timestamp color: GRAY"""
 
     RESET = '\033[0m'
     """Reset color: DEFAULT"""
     
-    def __init__(self, dev_mode: bool = False, quiet: bool = False):
+    def __init__(self, debug_mode: bool = False, quiet: bool = False):
         """Initializes logger. Opens log file 'bot.log' for writing.
 
         Args:
-            dev_mode (bool, optional): toggle debug messages. Defaults to False.
+            debug_mode (bool, optional): toggle debug messages. Defaults to False.
             quiet: (bool, optional): supress low-priority logs (INFO, DEBUG, WARN). Defaults to False.
         """
         try:
@@ -36,21 +33,15 @@ class Logger:
         except Exception as e:
             self.log_error(f"Error {type(e)}: {e}")
 
-        self.dev_mode = dev_mode
+        self.debug_mode = debug_mode
         """If debug logs should be printed."""
 
         self.quiet = quiet
         """If only high-level logs should be printed."""
     
-    def now(self):
-        """Returns current timestamp
-
-        Returns:
-            (str): timestamp formatted in YYYY-MM-DD HH:MM:SS
-        """
-        from datetime import datetime
-        
-        return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    def log_traceback(self):
+        import traceback
+        self._log("DEBUG", self.DEBUG, traceback.format_exc())
     
     def _log(self, level: str, color: str, message: str):
         """Internal helper that writes formatted log to both file and console.
@@ -60,23 +51,16 @@ class Logger:
             color (str): color specified by Logger properties
             message (str): descriptive message to log
         """
-        if self.quiet and level not in ('ERROR', 'CRITICAL', 'HIGH'):
+        if self.quiet and level not in ('ERROR', 'WARN', 'HIGH'):
             return # suppress lower-level logs in quiet mode
         
-        date = self.now()
+        from datetime import datetime
+        date = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
         self.fp.write(f"[{date}] {level}: {message}\n")
         self.fp.flush()
         print(f"{self.TIME}[{date}]{self.RESET} {color}{level}:{self.RESET} {message}\n")
     
-    def log_debug(self, message: str):
-        """Logs a debug-level message.
-
-        Args:
-            message (str): descriptive message to log
-        """
-        if self.dev_mode == True:
-            self._log("DEBUG", self.DEBUG, message)
-    
     def log_info(self, message: str):
         """Logs a info-level message.
 
@@ -100,48 +84,17 @@ class Logger:
             message (str): descriptive message to log
         """
         self._log("ERROR", self.ERROR, message)
-    
-    def log_critical(self, message: str):
-        """Logs a critical-level message.
-
-        Args:
-            message (str): descriptive message to log
-        """
-        self._log("CRITICAL", self.CRITICAL, message)
 
+        if self.debug_mode == True:
+            self.log_traceback()
+    
     def log_high_priority(self, message: str):
-        """Always log this, regardless of quiet/dev_mode.
+        """Always log this, regardless of quiet/debug_mode.
 
         Args:
             message (str): descriptive message to log
         """
         self._log("HIGH", self.INFO, message)
-        
-    def redact(self, data: dict, replacement: str ='*** REDACTED ***'):
-        """Recusively redact sensitive fields (token, password, authorization, api_key) from data.
-
-        Args:
-            data (_type_): JSON to sanitize
-            replacement (str, optional): what sensitive data is replaced with. Defaults to '*** REDACTED ***'.
-
-        Returns:
-            (dict): sanitized JSON
-        """
-        keys_to_redact = ['token', 'password', 'authorization', 'api_key']
-        
-        def _redact(obj):
-            if isinstance(obj, dict):
-                return {
-                    k: (replacement if k.lower() in keys_to_redact else _redact(v))
-                    for k, v in obj.items()
-                }
-            elif isinstance(obj, list):
-                return [_redact(item) for item in obj]
-            return obj
-
-        import copy
-
-        return _redact(copy.deepcopy(data))
     
     def close(self):
         """Closes the log file."""

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