scurrypy 0.1.0__py3-none-any.whl

discord/http.py

@@ -0,0 +1,292 @@
+import aiohttp
+import aiofiles
+import asyncio
+import time
+import json
+import ssl
+from dataclasses import dataclass
+from urllib.parse import urlencode
+
+from .logger import Logger
+from .error import DiscordError
+
+ssl_ctx = ssl.create_default_context()
+ssl_ctx.options |= ssl.OP_NO_SSLv2 | ssl.OP_NO_SSLv3  # Disable old SSL
+
+DISCORD_HTTP_CODES = {
+    200: "Successful Request",
+    201: "Successful Creation",
+    204: "No Content",
+    304: "Not Modified",
+    400: "Bad Request",
+    401: "Missing Authorization",
+    403: "Missing Permission",
+    404: "Resource Not Found",
+    405: "Invalid Method",
+    429: "Rate Limited",
+    502: "Gateway Unavailable"
+}
+
+@dataclass
+class RequestItem:
+    """Data container representing an HTTP request to Discord's API.
+        Used internally by HTTPClient for queuing and processing requests.
+    """
+    method: str
+    """HTTP method (e.g., GET, POST, DELETE, PUT, PATCH)"""
+
+    url: str
+    """Fully qualifying URL for this request."""
+
+    endpoint: str
+    """Endpoint of the URL for this request."""
+
+    data: dict | None
+    """Relevant data for this request."""
+
+    files: list | None
+    """Relevant files for this request."""
+
+    future: asyncio.Future
+    """Track the result of this request."""
+
+class RouteQueue:
+    """Represents a queue of requests for a single rate-limit bucket.
+        Manages task worker that processes requests for that bucket.
+    """
+    def __init__(self):
+        self.queue = asyncio.Queue()
+        """Queue holding RequestItem for this bucket."""
+
+        self.worker = None
+        """Process for executing request for this bucket."""
+
+class HTTPClient:
+    """Handles all HTTP communication with Discord's API
+        including rate-limiting by bucket and globally, async request handling,
+        multipart/form-data file uploads, and error handling/retries.
+    """
+    def __init__(self, token: str, logger: Logger):
+        self.token = token
+        """The bot's token."""
+
+        self._logger = logger
+        """Logger instance to log events."""
+
+        self.session: aiohttp.ClientSession = None
+        """Client session instance."""
+
+        self.global_reset = 0
+        """Global rete limit cooldown if a global rate limit is active."""
+
+        self.global_lock: asyncio.Lock = None
+        """Lock on queues to avoid race conditions."""
+
+        self.pending_queue: asyncio.Queue = None
+        """Queue for requests not yet assigned to bucket."""
+
+        self.pending_worker: asyncio.Task = None
+        """Task processing for the pending queue."""
+
+        self.endpoint_to_bucket: dict[str, str] = {}
+        """Maps endpoints to rate-limit buckets"""
+
+        self.bucket_queues: dict[str, RouteQueue] = {}
+        """Maps endpoints to RouteQueue objects."""
+
+        self._sentinel = object()
+        """Sentinel to terminate session."""
+
+        self.base_url = "https://discord.com/api/v10"
+        """Base URL for discord's API requests."""
+
+    async def start_session(self):
+        """Initializes aiohttp session, queues, locks, and starting pending worker."""
+        self.session = aiohttp.ClientSession()
+        self.pending_queue = asyncio.Queue()
+        self.global_lock = asyncio.Lock()
+        self.pending_worker = asyncio.create_task(self._pending_worker())
+        self._logger.log_debug("Session started.")
+
+    async def request(self, method: str, endpoint: str, data=None, params=None, files=None):
+        """Enqueues request WRT rate-limit buckets.
+
+        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
+            files (list[str], optional): relevant files
+
+        Returns:
+            (Future): future with response
+        """
+        url = f"{self.base_url.rstrip('/')}/{endpoint.lstrip('/')}" # normalize for single slashes
+        if params:
+            url += f"?{urlencode(params)}"
+
+        future = asyncio.get_event_loop().create_future()
+
+        if endpoint in self.endpoint_to_bucket:
+            bucket = self.endpoint_to_bucket[endpoint]
+            if bucket not in self.bucket_queues:
+                self.bucket_queues[bucket] = RouteQueue()
+                self.bucket_queues[bucket].worker = asyncio.create_task(
+                    self._route_worker(bucket)
+                )
+            await self.bucket_queues[bucket].queue.put(RequestItem(method, url, endpoint, data, files, future))
+        else:
+            await self.pending_queue.put(RequestItem(method, url, endpoint, data, files, future))
+
+        return await future
+
+    async def _pending_worker(self):
+        """Processes requests from global pending queue."""
+        while True:
+            item = await self.pending_queue.get()
+            if item is self._sentinel:
+                self.pending_queue.task_done()
+                break
+            await self._process_request(item)
+            self.pending_queue.task_done()
+
+    async def _route_worker(self, bucket: str):
+        """Processes request from specific rate-limit bucket.
+
+        Args:
+            bucket (str): endpoint
+        """
+        queue = self.bucket_queues[bucket].queue
+        while True:
+            item = await queue.get()
+            if item is self._sentinel:
+                queue.task_done()
+                break
+            await self._process_request(item)
+            queue.task_done()
+
+    async def _process_request(self, item: RequestItem):
+        """Core request execution. Handles headers, payload, files, retries, and bucket assignment.
+
+        Args:
+            item (RequestItem): incoming request
+
+        Raises:
+            DiscordError: discord error object
+        """
+        try:
+            await self._check_global_limit()
+
+            headers = {"Authorization": f"Bot {self.token}"}
+
+            # Build multipart if files exist
+            request_kwargs = {'headers': headers, 'ssl': ssl_ctx}
+
+            if item.files: # only create FormData if files exist
+                form = aiohttp.FormData()
+                form.add_field('payload_json', json.dumps(item.data))
+
+                for idx, file_path in enumerate(item.files):
+                    try:
+                        async with aiofiles.open(file_path, 'rb') as f:
+                            data = await f.read()
+                        form.add_field(
+                            f'files[{idx}]',
+                            data,
+                            filename=file_path.split('/')[-1],
+                            content_type='application/octet-stream'
+                        )
+                    except FileNotFoundError:
+                        self._logger.log_warn(f"File '{file_path}' could not be found.")
+                        break
+
+                request_kwargs['data'] = form
+
+            elif item.data is not None:
+                request_kwargs['json'] = item.data # aiohttp sets Content-Type automatically
+
+            async with self.session.request(item.method, item.url, **request_kwargs) as resp:
+                self._logger.log_debug(f"{item.method} {item.endpoint}: {resp.status} {DISCORD_HTTP_CODES.get(resp.status, 'Unknown Status')}")
+
+                # if triggered rate-limit
+                if resp.status == 429:
+                    data = await resp.json()
+                    retry_after = float(data.get("retry_after", 1))
+                    is_global = data.get("global")
+                    if is_global:
+                        self.global_reset = time.time() + retry_after
+
+                    try:
+                        self._logger.log_warn( f"You are being rate limited on {item.endpoint}. Retrying in {retry_after}s (global={is_global})")
+                        await asyncio.sleep(retry_after + 0.5)
+                    except asyncio.CancelledError:
+                        # shutdown is happening
+                        raise
+
+                    # retry the request
+                    await self._process_request(item)
+                    return
+
+                # if response failed (either lethal or recoverable)
+                elif resp.status not in [200, 201, 204]:
+                    raise DiscordError(resp.status, await resp.json())
+
+                await self._handle_response(item, resp)
+
+                # Handle rate-limit bucket headers
+                bucket = resp.headers.get("X-RateLimit-Bucket")
+                if bucket and item.endpoint not in self.endpoint_to_bucket:
+                    self.endpoint_to_bucket[item.endpoint] = bucket
+                    if bucket not in self.bucket_queues:
+                        self.bucket_queues[bucket] = RouteQueue()
+                        self.bucket_queues[bucket].worker = asyncio.create_task(
+                            self._route_worker(bucket)
+                        )
+
+        except Exception as e:
+            if not item.future.done():
+                item.future.set_exception(e)
+
+    async def _handle_response(self, item: RequestItem, resp: aiohttp.ClientResponse):
+        """Resolves future with parsed JSON/text response.
+
+        Args:
+            item (RequestItem): request data to handle
+            resp (aiohttp.ClientResponse): response for item
+        """
+        if resp.status == 204:
+            item.future.set_result((None, 204))
+        else:
+            try:
+                result = await resp.json()
+            except aiohttp.ContentTypeError:
+                result = await resp.text()
+            item.future.set_result(result)
+
+    async def _check_global_limit(self):
+        """Waits if the global rate-limit is in effect."""
+        async with self.global_lock:
+            now = time.time()
+            if now < self.global_reset:
+                await asyncio.sleep(self.global_reset - now)
+
+    async def close_session(self):
+        """Gracefully shuts down all workes and closes aiohttp session."""
+        # Stop all bucket workers
+        for q in self.bucket_queues.values():
+            await q.queue.put(self._sentinel)
+
+        # Stop pending worker
+        await self.pending_queue.put(self._sentinel)
+
+        # Cancel all tasks except the current one
+        tasks = [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
+        for task in tasks:
+            task.cancel()
+
+        # Wait for tasks to acknowledge cancellation
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Close the aiohttp session
+        if self.session and not self.session.closed:
+            await self.session.close()
+            self._logger.log_debug("Session closed successfully.")

discord/intents.py

@@ -0,0 +1,87 @@
+from typing import TypedDict, Unpack
+
+class Intents:
+    """Gateway intent flags (bitwise).  
+        For an exhaustive list what intents let your bot listen to what events, see <a href="https://discord.com/developers/docs/events/gateway#list-of-intents" target="_blank" rel="noopener">list of intents</a>.
+
+    !!! note
+        Not all intents are listed. Intents not listed are not yet supported.
+    """
+
+    GUILDS = 1 << 0
+    """Receive events related to guilds."""
+
+    GUILD_MEMBERS = 1 << 1
+    """
+    !!! warning "Privileged Intent"
+        Requires the app setting `Server Members Intent` to be toggled.
+    Receive events related to guild members.
+    """
+
+    GUILD_EMOJIS_AND_STICKERS = 1 << 3
+    """Receive events related to custom emojis and stickers."""
+
+    GUILD_INTEGRATIONS = 1 << 4
+    """Receive events related to integrations within a guild."""
+
+    GUILD_WEBHOOKS = 1 << 5
+    """Track webhook events within a guild."""
+
+    GUILD_MESSAGES = 1 << 9
+    """Receive events about messages within a guild."""
+
+    GUILD_MESSAGE_REACTIONS = 1 << 10
+    """Track changes in reactions on messages."""
+
+    MESSAGE_CONTENT = 1 << 15
+    """
+    !!! warning "Privileged Intent"
+        Requires the app setting `Message Content Intent` to be toggled.
+    Access content of messages.
+    """
+
+    DEFAULT = GUILDS | GUILD_MESSAGES
+
+class IntentFlagParams(TypedDict, total=False):
+    """Gateway intent selection parameters."""
+    guilds: bool
+    guild_members: bool
+    guild_emojis_and_stickers: bool
+    guild_integrations: bool
+    guild_webhooks: bool
+    guild_messages: bool
+    guild_message_reactions: bool
+    message_content: bool
+
+def set_intents(**flags: Unpack[IntentFlagParams]):
+    """Set bot intents using [`IntentFlagParams`][discord.intents.IntentFlagParams].  
+    `Intents.DEFAULT` = (GUILDS | GUILD_MESSAGES) will also be set.
+
+    Args:
+        flags (Unpack[IntentFlagParams]): intents to set. (set respective flag to True to toggle.)
+
+    Raises:
+        (ValueError): invalid flag
+
+    Returns:
+        (int): combined intents field
+    """
+    _flag_map = {
+        'guilds': Intents.GUILDS,
+        'guild_members': Intents.GUILD_MEMBERS,
+        'guild_emojis_and_stickers': Intents.GUILD_EMOJIS_AND_STICKERS,
+        'guild_integrations': Intents.GUILD_INTEGRATIONS,
+        'guild_webhooks': Intents.GUILD_WEBHOOKS,
+        'guild_messages': Intents.GUILD_MESSAGES,
+        'guild_message_reactions': Intents.GUILD_MESSAGE_REACTIONS,
+        'message_content': Intents.MESSAGE_CONTENT
+    }
+
+    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]
+    
+    return intents

discord/logger.py

@@ -0,0 +1,147 @@
+from datetime import datetime
+import copy
+
+class Logger:
+    """A utility class for logging messages, supporting log levels, color-coded console output, 
+        optional file logging, and redaction of sensitive information. 
+    """
+    DEBUG = '\033[36m'
+    """Debug color: CYCAN"""
+
+    INFO = '\033[32m'
+    """Info color: GREEN"""
+
+    WARNING = '\033[33m'
+    """Warning color: YELLOW"""
+
+    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):
+        """Initializes logger. Opens log file 'bot.log' for writing.
+
+        Args:
+            dev_mode (bool, optional): toggle debug messages. Defaults to False.
+            quiet: (bool, optional): supress low-priority logs (INFO, DEBUG, WARN). Defaults to False.
+        """
+        try:
+            self.fp = open('bot.log', 'w', encoding="utf-8")
+            """Log file for writing."""
+        except Exception as e:
+            self.log_error(f"Error {type(e)}: {e}")
+
+        self.dev_mode = dev_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
+        """
+        return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    
+    def _log(self, level: str, color: str, message: str):
+        """Internal helper that writes formatted log to both file and console.
+
+        Args:
+            level (str): DEBUG, INFO, WARN, CRITICAL, ERROR
+            color (str): color specified by Logger properties
+            message (str): descriptive message to log
+        """
+        if self.quiet and level not in ('ERROR', 'CRITICAL', 'HIGH'):
+            return # suppress lower-level logs in quiet mode
+        
+        date = self.now()
+        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.
+
+        Args:
+            message (str): descriptive message to log
+        """
+        self._log("INFO", self.INFO, message)
+    
+    def log_warn(self, message: str):
+        """Logs a warn-level message.
+
+        Args:
+            message (str): descriptive message to log
+        """
+        self._log("WARN", self.WARNING, message)
+    
+    def log_error(self, message: str):
+        """Logs a error-level message.
+
+        Args:
+            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)
+
+    def log_high_priority(self, message: str):
+        """Always log this, regardless of quiet/dev_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
+
+        return _redact(copy.deepcopy(data))
+    
+    def close(self):
+        """Closes the log file."""
+        self.fp.close()

discord/model.py

@@ -0,0 +1,88 @@
+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
+        """
+        kwargs = {}
+
+        def unwrap_optional(typ):
+            """Remove NoneType from Optional or leave Union as-is."""
+            if get_origin(typ) is Union:
+                args = tuple(a for a in get_args(typ) if a is not type(None))
+                if len(args) == 1:
+                    return args[0]  # single type left
+                else:
+                    return Union[args]  # multi-type union remains
+            return typ
+        
+        for field in fields(cls):
+            # property must be in given json!
+            value = data.get(field.name)
+            
+            inner_type = unwrap_optional(field.type)
+
+            # Handle None
+            if value is None:
+                kwargs[field.name] = None
+            # Integers stored as strings
+            elif isinstance(value, str) and value.isdigit():
+                kwargs[field.name] = int(value)
+            # Nested dataclass
+            elif is_dataclass(inner_type):
+                kwargs[field.name] = inner_type.from_dict(value, http)
+            # List type
+            elif get_origin(inner_type) is list:
+                list_type = get_args(inner_type)[0]
+                kwargs[field.name] = [
+                    list_type.from_dict(v, http) if is_dataclass(list_type) else v
+                    for v in value
+                ]
+            # Everything else (primitive, Union of primitives)
+            else:
+                kwargs[field.name] = value
+            
+        instance = cls(**kwargs)
+
+        # attach HTTP if given
+        if http:
+            instance._http = http
+
+        return instance
+
+    def _to_dict(self):
+        """Recursively turns the dataclass into a dictionary and drops empty fields.
+
+        Returns:
+            (dict): serialized dataclasss
+        """
+        def serialize(value):
+            if isinstance(value, list):
+                return [serialize(v) for v in value]
+            if isinstance(value, DataModel):
+                return value._to_dict()
+            return value
+    
+        result = {}
+        for f in fields(self):
+            value = getattr(self, f.name)
+            if value not in (None, [], {}, "", 0):
+                result[f.name] = serialize(value)
+        
+        return result

discord/models/__init__.py

@@ -0,0 +1,8 @@
+# discord/models
+
+from .application import ApplicationModel
+from .emoji import EmojiModel
+from .guild import GuildModel
+from .member import MemberModel
+from .user import UserModel
+from .role import RoleModel

discord/models/application.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+from ..model import DataModel
+from .user import UserModel
+from .guild import GuildModel
+
+@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."""

discord/models/emoji.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+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}")