scurrypy 0.1.0__py3-none-any.whl

discord/resources/application.py

@@ -0,0 +1,94 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from ..http import HTTPClient
+from ..model import DataModel
+
+from ..models.user import UserModel
+from ..models.guild import GuildModel
+
+class ApplicationFlags:
+    """Application flags (bitwise constants)."""
+
+    GATEWAY_PRESENCE = 1 << 12
+    """Privileged intent to receive presence_update events."""
+
+    GATEWAY_PRESENCE_LIMITED = 1 << 13
+    """Intent to receive presence_update events."""
+
+    GATEWAY_GUILD_MEMBERS = 1 << 14
+    """Privileged intent to receive member-related events."""
+
+    GATEWAY_GUILD_MEMBERS_LIMITED = 1 << 15
+    """Intent to receive member-related events."""
+
+    VERIFICATION_PENDING_GUILD_LIMIT = 1 << 16
+    """Indicates unusual growth of an app that prevents verification."""
+
+    GATEWAY_MESSAGE_CONTENT = 1 << 18
+    """Privileged intent to receive message content."""
+
+    GATEWAY_MESSAGE_CONTENT_LIMITED = 1 << 19
+    """Intent to receive message content."""
+
+@dataclass
+class Application(DataModel):
+    """Represents a Discord application."""
+
+    id: int
+    """ID of the application."""
+
+    _http: HTTPClient
+    """HTTP session for requests."""
+
+    name: str = None
+    """Name of the application."""
+
+    icon: Optional[str] = None
+    """Icon hash of the application."""
+
+    description: Optional[str] = None
+    """Description of the application."""
+
+    bot_public: Optional[bool] = None
+    """If the application is public."""
+
+    bot_require_code_grant: Optional[bool] = None
+    """If full OAuth2 code grant is required."""
+
+    bot: Optional[UserModel] = None
+    """Partial bot user object of the application."""
+
+    terms_of_service_url: Optional[str] = None
+    """Terms of Service URL of the application"""
+
+    privacy_policy: Optional[str] = None
+    """Privacy Policy URL of the application."""
+
+    owner: Optional[UserModel] = None
+    """Partial user object of the owner of the application."""
+
+    guild_id: Optional[int] = None
+    """Guild ID associated with the application."""
+
+    guild: Optional[GuildModel] = None
+    """Partial guild object of the associated guild."""
+
+    cover_image: Optional[str] = None
+    """Image hash of rich presence invite cover."""
+
+    flags: Optional[int] = None
+    """Public flags of the application."""
+
+    approximate_guild_count: Optional[int] = None
+    """Approximate guild count of the guilds that installed the application."""
+    
+    def fetch(self):
+        """Fetch this application's data.
+
+        Returns:
+            (Application): the Application data
+        """
+        data = self._http.request('GET', '/applications/@me')
+
+        return Application.from_dict(data, self._http)

discord/resources/bot_emojis.py

@@ -0,0 +1,49 @@
+from ..http import HTTPClient
+from ..models.emoji import EmojiModel
+
+class BotEmojis:
+    """Represents a collection of the bot's emojis."""
+
+    def __init__(self, _http: HTTPClient, application_id: int):
+
+        self._http = _http
+        """HTTP session for requests."""
+
+        self.application_id = application_id
+        """Bot's application ID."""
+        
+        self._cache: dict[int, EmojiModel] = {}
+        """Cache of bot's repository emojis mapped by id."""
+
+    async def fetch_all(self):
+        """Fetches all the bot's emojis from its repository."""
+        data = await self._http.request('GET', f'/applications/{self.application_id}/emojis')
+        items = data.get('items', [])
+        for e in items:
+            emoji = EmojiModel.from_dict(e)
+            self._cache[emoji.name] = emoji
+
+    async def fetch(self, emoji_id: int):
+        """Fetches a single emoji from the bot's repository.
+
+        Args:
+            emoji_id (int): the emoji's id
+
+        Returns:
+            (EmojiModel):  the new EmojiModel object with all fields populated
+        """
+        data = await self._http.request("GET", f"/applications/{self.application_id}/emojis/{emoji_id}")
+        emoji = EmojiModel.from_dict(data)
+        self._cache[emoji.id] = emoji # also add it to the cache
+        return emoji
+
+    def get_emoji(self, name: str) -> EmojiModel:
+        """Get an emoji from this resource's cache by name.
+
+        Args:
+            name (str): name of the emoji
+
+        Returns:
+            (EmojiModel): the new EmojiModel object with all fields populated
+        """
+        return self._cache.get(name, EmojiModel('❓'))

discord/resources/channel.py

@@ -0,0 +1,192 @@
+from dataclasses import dataclass
+from typing import TypedDict, Unpack, Optional
+
+from ..http import HTTPClient
+from ..model import DataModel
+from .message import Message
+
+from ..parts.channel import GuildChannel
+from ..parts.message import MessageBuilder
+
+class MessagesFetchParams(TypedDict, total=False):
+    """Params when fetching guild channel messages."""
+
+    limit: int
+    """Max number of messages to return. Range 1 - 100. Default 50."""
+
+    before: int
+    """Get messages before this message ID."""
+
+    after: int
+    """Get messages after this message ID."""
+
+    around: int
+    """Get messages around this message ID."""
+
+class PinsFetchParams(TypedDict, total=False):
+    """Params when fetching pinned messages."""
+
+    before: str
+    """Get pinned messages before this ISO8601 timestamp."""
+
+    limit: int
+    """Max number of pinned messages to return. Range 1 - 50. Default 50."""
+
+@dataclass
+class PinnedMessage(DataModel):
+    """Pinned message data."""
+
+    message: Message
+    """Message resource of the pinned message."""
+
+    pinned_at: Optional[str] = None
+    """ISO8601 timestamp of when the message was pinned."""
+
+@dataclass
+class Channel(DataModel):
+    """Represents a Discord guild channel."""
+
+    id: int
+    """ID of the channel."""
+
+    _http: HTTPClient
+    """HTTP session for requests."""
+
+    type: Optional[int] = None
+    """Type of channel."""
+
+    guild_id: Optional[int] = None
+    """Guild ID of the channel."""
+
+    parent_id: Optional[int] = None
+    """Category ID of the channel."""
+
+    position: Optional[int] = None
+    """Position of the channel."""
+
+    name: Optional[str] = None
+    """Name of the channel."""
+
+    topic: Optional[str] = None
+    """Topic of the channel."""
+
+    nsfw: Optional[bool] = None
+    """If the channel is flagged NSFW."""
+
+    last_message_id: Optional[int] = None
+    """ID of the last message sent in the channel."""
+
+    last_pin_timestamp: Optional[str] = None
+    """ISO8601 timestamp of the last pinned messsage in the channel."""
+
+    rate_limit_per_user: Optional[int] = None
+    """Seconds user must wait between sending messages in the channel."""
+
+    def _update(self, data: dict):
+        """Update this channel in place.
+
+        Args:
+            data (dict): channel data as a dict
+        """
+        self.__dict__.update(Channel.from_dict(data, self._http).__dict__)
+
+    async def fetch(self):
+        """Fetch the full channel data from Discord.
+
+        Returns:
+            (Channel): A new Channel object with all fields populated
+        """
+        data = await self._http.request("GET", f"/channels/{self.id}")
+
+        # Hydrate a new Channel object with HTTP client    
+        return Channel.from_dict(data, self._http)
+    
+    async def fetch_messages(self, **kwargs: Unpack[MessagesFetchParams]):
+        """Fetches this channel's messages.
+
+        Permissions:
+            * VIEW_CHANNEL → required to access channel messages
+            * READ_MESSAGE_HISTORY → required for user, otherwise no messages are returned
+
+        Args:
+            **kwargs: field-specific data
+                !!! note
+                    if no kwargs are provided, default to 50 fetched messages limit.
+
+        Returns:
+            (list[Message]): queried messages
+        """
+        # Set default limit if user didn't supply one
+        params = {"limit": 50, **kwargs}
+
+        data = await self._http.request('GET', f'/channels/{self.id}/messages', params=params)
+
+        return [Message.from_dict(msg, self._http) for msg in data]
+    
+    async def send(self, message: str | MessageBuilder):
+        """
+        Send a message to this channel.
+
+        Permissions:
+            * SEND_MESSAGES → required to create a message in this channel
+
+        Args:
+            message (str | MessageBuilder): can be just text or the MessageBuilder for dynamic messages
+
+        Returns:
+            (Message): The created Message object
+        """
+        if isinstance(message, str):
+            message = MessageBuilder(content=message)
+
+        data = await self._http.request("POST", f"/channels/{self.id}/messages", message._to_dict())
+
+        return Message.from_dict(data, self._http)
+
+    async def edit(self, channel: GuildChannel):
+        """Edit this channel's settings.
+
+        Permissions:
+            * MANAGE_CHANNELS → required to edit this channel
+
+        Args:
+            channel (GuildChannel): channel changes
+
+        Returns:
+            (Channel): The updated channel object
+        """
+        data = await self._http.request("PATCH", f"/channels/{self.id}", data=channel._to_dict())
+        self._update(data)
+
+        return self
+    
+    async def fetch_pins(self, **kwargs: Unpack[PinsFetchParams]):
+        """Get this channel's pinned messages.
+
+        Permissions:
+            * VIEW_CHANNEL → required to access pinned messages
+            * READ_MESSAGE_HISTORY → required for reading pinned messages
+
+        Args:
+            kwargs: field-specific data
+                !!! note
+                    If no kwargs are provided, default to 50 fetched messages limit.
+            
+        Returns:
+            (list[PinnedMessage]): list of pinned messages
+        """
+        # Set default limit if user didn't supply one
+        params = {"limit": 50, **kwargs}
+
+        data = await self._http.request('GET', f'/channels/{self.id}/pins', params=params)
+
+        pins = [Message.from_dict(item, self._http) for item in data]
+        return pins
+
+    async def delete(self):
+        """Deletes this channel from the server.
+
+        Permissions:
+            * MANAGE_CHANNELS → required to delete this channel
+        """
+        await self._http.request("DELETE", f"/channels/{self.id}")

discord/resources/guild.py

@@ -0,0 +1,265 @@
+from dataclasses import dataclass
+from typing import Optional, TypedDict, Unpack
+
+from ..http import HTTPClient
+from ..model import DataModel
+
+from .channel import Channel
+
+from ..parts.channel import GuildChannel
+from ..parts.role import Role
+
+from ..models.emoji import EmojiModel
+from ..models.member import MemberModel
+from ..models.role import RoleModel
+
+class FetchGuildMembersParams(TypedDict, total=False):
+    """Params when fetching guild members."""
+
+    limit: int
+    """Max number of members to return Range 1 - 1000. Default 1."""
+
+    after: int
+    """Highest user id in previous page."""
+
+class FetchGuildParams(TypedDict, total=False):
+    """Params when fetching a guild."""
+
+    with_counts: Optional[bool]
+    """If True, return the approximate member and presence counts for the guild."""
+
+@dataclass
+class Guild(DataModel):
+    """Represents a Discord guild."""
+    id: int
+    """ID of the guild."""
+
+    _http: HTTPClient
+    """HTTP session for requests."""
+
+    name: str = None
+    """Name of the guild."""
+
+    icon: str = None
+    """Image hash of the guild's icon."""
+
+    splash: str = None
+    """Image hash of the guild's splash."""
+
+    owner: Optional[bool] = None
+    """If the member is the owner. (Get Current User Guilds)"""
+
+    owner_id: int = None
+    """OD of the owner of the guild."""
+
+    roles: list[int] = None
+    """List of IDs registered in the guild."""
+
+    emojis: list[EmojiModel] = None
+    """List of emojis registered in the guild."""
+
+    mfa_level: int = None
+    """Required MFA level of the guild."""
+
+    application_id: int = None
+    """ID of the application if the guild is created by a bot."""
+
+    system_channel_id: int = None
+    """Channel ID where system messages go (e.g., welcome messages, boost events)."""
+
+    system_channel_flags: int = None
+    """System channel flags."""
+
+    rules_channel_id: int = None
+    """Channel ID where rules are posted."""
+
+    max_members: Optional[int] = None
+    """Maximum member capacity for the guild."""
+
+    description: str = None
+    """Description of the guild."""
+
+    banner: str = None
+    """Image hash of the guild's banner."""
+
+    preferred_locale: str = None
+    """Preferred locale of the guild."""
+
+    public_updates_channel_id: int = None
+    """Channel ID of announcement or public updates."""
+
+    approximate_member_count: int = None
+    """Approximate number of members in the guild."""
+
+    nsfw_level: int = None
+    """NSFW level of the guild."""
+
+    safety_alerts_channel_id: int = None
+    """Channel ID for safety alerts."""
+
+    async def fetch(self, **kwargs: Unpack[FetchGuildParams]):
+        """Fetch the Guild object by the given ID.
+
+        Args:
+            kwargs: field-specific data
+                !!! note
+                    If no kwargs are provided, default to with_counts = False
+            
+        Returns:
+            (Guild): the Guild object
+        """
+        params = {'with_counts': False, **kwargs}
+
+        data = await self._http.request('GET', f'/guilds/{self.id}', params=params)
+
+        return Guild.from_dict(data, self._http)
+
+    async def fetch_channels(self):
+        """Fetch this guild's channels.
+
+        Returns:
+            (list[Channel]): list of the guild's channels
+        """
+        data = await self._http.request('GET', f'guilds/{self.id}/channels')
+
+        return [Channel.from_dict(channel, self._http) for channel in data]
+
+    async def create_channel(self, channel: GuildChannel):
+        """Create a channel in this guild.
+
+        Permissions:
+            * MANAGE_CHANNELS → required to create a channel
+
+        Args:
+            channel (GuildChannel): the buildable guild channel
+
+        Returns:
+            (Channel): the created channel
+        """
+        data = await self._http.request('POST', f'/guilds/{self.id}/channels', channel._to_dict())
+
+        return Channel.from_dict(data, self._http)
+
+    async def fetch_guild_member(self, user_id: int):
+        """Fetch a member in this guild.
+        !!! warning "Important"
+            Requires the GUILD_MEMBERS privileged intent!
+
+        Args:
+            user_id (int): user id of the member to fetch
+
+        Returns:
+            (MemberModel): member's data
+        """
+        data = await self._http.request('GET', f'/guilds/{self.id}/members/{user_id}')
+
+        return MemberModel.from_dict(data)
+    
+    async def fetch_guild_members(self, **kwargs: Unpack[FetchGuildMembersParams]):
+        """Fetch guild members in this guild.
+        !!! warning "Important"
+            Requires the GUILD_MEMBERS privileged intent!
+
+        Args:
+            **kwargs: field-specific data
+                !!! note
+                    If no kwargs are provided, default to 1 guild member limit.
+
+        Returns:
+            (list[MemberModel]): list of member data
+        """
+        params = {"limit": 1, **kwargs}
+
+        data = await self._http.request('GET', f'/guilds/{self.id}/members', params=params)
+
+        return [MemberModel.from_dict(member) for member in data]
+
+    async def add_guild_member_role(self, user_id: int, role_id: int):
+        """Append a role to a guild member of this guild.
+
+        Permissions:
+            * MANAGE_ROLES → required to add a role to the user
+        
+        Args:
+            user_id (int): id of the member for the role
+            role_id (int): id of the role to append
+        """
+        await self._http.request('PUT', f'/guilds/{self.id}/members/{user_id}/roles/{role_id}')
+    
+    async def remove_guild_member_role(self, user_id: int, role_id: int):
+        """Remove a role from a guild member of this guild.
+
+        Permissions:
+            * MANAGE_ROLES → required to remove a role from the user
+
+        Args:
+            user_id (int): id of the member with the role
+            role_id (int): id of the role to remove
+        """
+        await self._http.request('DELETE', f'/guilds/{self.id}/members/{user_id}/roles/{role_id}')
+
+    async def fetch_guild_role(self, role_id: int):
+        """Fetch a role in this guild.
+
+        Args:
+            role_id (int): id of the role to fetch
+
+        Returns:
+            (RoleModel): fetched role's data
+        """
+        data = await self._http.request('GET', f'/guilds/{self.id}/roles/{role_id}')
+        
+        return RoleModel.from_dict(data)
+
+    async def fetch_guild_roles(self):
+        """Fetch all roles in this guild.
+
+        Returns:
+            (list[RoleModel]): list of fetched roles' data
+        """
+        data = await self._http.request('GET', f'/guilds/{self.id}/roles')
+        
+        return [RoleModel.from_dict(role) for role in data]
+
+    async def create_guild_role(self, role: Role):
+        """Create a role in this guild.
+
+        Permissions:
+            * MANAGE_ROLES → required to add a role to the guild
+
+        Args:
+            role (Role): role to create
+
+        Returns:
+            (RoleModel): new role data
+        """
+        data = await self._http.request('POST', f'/guilds/{self.id}/roles', role._to_dict())
+
+        return RoleModel.from_dict(data)
+
+    async def modify_guild_role(self, role_id: int, role: Role):
+        """Modify a role in this guild.
+
+        Permissions:
+            * MANAGE_ROLES → required to modify a role in the guild
+
+        Args:
+            role (Role): role with changes
+
+        Returns:
+            (RoleModel): role with changes
+        """
+        data = await self._http.request('PATCH', f'/guilds/{self.id}/roles/{role_id}', role._to_dict())
+
+        return RoleModel.from_dict(data)
+    
+    async def delete_guild_role(self, role_id: int):
+        """Delete a role in this guild.
+
+        Permissions:
+            * MANAGE_ROLES → required to delete a role in the guild
+
+        Args:
+            role_id (int): id of role to delete
+        """
+        await self._http.request('DELETE', f'/guilds/{self.id}/roles/{role_id}')