Merge remote-tracking branch 'upstream/master' into akiko

Author: Soheab

discord/__init__.py

@@ -73,6 +73,8 @@
 from .soundboard import *
 from .subscription import *
 from .presences import *
+from .primary_guild import *
+from .onboarding import *
 
 
 class VersionInfo(NamedTuple):

discord/abc.py

@@ -34,8 +34,10 @@
     AsyncIterator,
     Callable,
     Dict,
+    Generator,
     Iterable,
     List,
+    Literal,
     Optional,
     TYPE_CHECKING,
     Protocol,
@@ -61,6 +63,7 @@
 from .sticker import GuildSticker, StickerItem
 from . import utils
 from .flags import InviteFlags
+import warnings
 
 __all__ = (
     'Snowflake',
@@ -114,6 +117,11 @@
     MessageableChannel = Union[PartialMessageableChannel, GroupChannel]
     SnowflakeTime = Union["Snowflake", datetime]
 
+    class PinnedMessage(Message):
+        pinned_at: datetime
+        pinned: Literal[True]
+
+
 MISSING = utils.MISSING
 
 
@@ -125,6 +133,26 @@ def __repr__(self) -> str:
 _undefined: Any = _Undefined()
 
 
+class _PinsIterator:
+    def __init__(self, iterator: AsyncIterator[PinnedMessage]) -> None:
+        self.__iterator: AsyncIterator[PinnedMessage] = iterator
+
+    def __await__(self) -> Generator[Any, None, List[PinnedMessage]]:
+        warnings.warn(
+            "`await <channel>.pins()` is deprecated; use `async for message in <channel>.pins()` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        async def gather() -> List[PinnedMessage]:
+            return [msg async for msg in self.__iterator]
+
+        return gather().__await__()
+
+    def __aiter__(self) -> AsyncIterator[PinnedMessage]:
+        return self.__iterator
+
+
 async def _single_delete_strategy(messages: Iterable[Message], *, reason: Optional[str] = None):
     for m in messages:
         try:
@@ -1756,34 +1784,132 @@ async def fetch_message(self, id: int, /) -> Message:
         data = await self._state.http.get_message(channel.id, id)
         return self._state.create_message(channel=channel, data=data)
 
-    async def pins(self) -> List[Message]:
-        """|coro|
+    async def __pins(
+        self,
+        *,
+        limit: Optional[int] = 50,
+        before: Optional[SnowflakeTime] = None,
+        oldest_first: bool = False,
+    ) -> AsyncIterator[PinnedMessage]:
+        channel = await self._get_channel()
+        state = self._state
+        max_limit: int = 50
+
+        time: Optional[str] = (
+            (before if isinstance(before, datetime) else utils.snowflake_time(before.id)).isoformat()
+            if before is not None
+            else None
+        )
+
+        while True:
+            retrieve = max_limit if limit is None else min(limit, max_limit)
+            if retrieve < 1:
+                break
+
+            data = await self._state.http.pins_from(
+                channel_id=channel.id,
+                limit=retrieve,
+                before=time,
+            )
+
+            items = data and data['items']
+            if items:
+                if limit is not None:
+                    limit -= len(items)
+
+                time = items[-1]['pinned_at']
+
+            # Terminate loop on next iteration; there's no data left after this
+            if len(items) < max_limit or not data['has_more']:
+                limit = 0
+
+            if oldest_first:
+                items = reversed(items)
+
+            count = 0
+            for count, m in enumerate(items, start=1):
+                message: Message = state.create_message(channel=channel, data=m['message'])
+                message._pinned_at = utils.parse_time(m['pinned_at'])
+                yield message  # pyright: ignore[reportReturnType]
+
+            if count < max_limit:
+                break
+
+    def pins(
+        self,
+        *,
+        limit: Optional[int] = 50,
+        before: Optional[SnowflakeTime] = None,
+        oldest_first: bool = False,
+    ) -> _PinsIterator:
+        """Retrieves an :term:`asynchronous iterator` of the pinned messages in the channel.
 
-        Retrieves all messages that are currently pinned in the channel.
+        You must have :attr:`~discord.Permissions.view_channel` and
+        :attr:`~discord.Permissions.read_message_history` in order to use this.
+
+        .. versionchanged:: 2.6
+
+            Due to a change in Discord's API, this now returns a paginated iterator instead of a list.
+
+            For backwards compatibility, you can still retrieve a list of pinned messages by
+            using ``await`` on the returned object. This is however deprecated.
 
         .. note::
 
             Due to a limitation with the Discord API, the :class:`.Message`
-            objects returned by this method do not contain complete
+            object returned by this method does not contain complete
             :attr:`.Message.reactions` data.
 
+        Examples
+        ---------
+
+        Usage ::
+
+            counter = 0
+            async for message in channel.pins(limit=250):
+                counter += 1
+
+        Flattening into a list: ::
+
+            messages = [message async for message in channel.pins(limit=50)]
+            # messages is now a list of Message...
+
+        All parameters are optional.
+
+        Parameters
+        -----------
+        limit: Optional[int]
+            The number of pinned messages to retrieve. If ``None``, it retrieves
+            every pinned message in the channel. Note, however, that this would
+            make it a slow operation.
+            Defaults to ``50``.
+
+            .. versionadded:: 2.6
+        before: Optional[Union[:class:`datetime.datetime`, :class:`.abc.Snowflake`]]
+            Retrieve pinned messages before this time or snowflake.
+            If a datetime is provided, it is recommended to use a UTC aware datetime.
+            If the datetime is naive, it is assumed to be local time.
+
+            .. versionadded:: 2.6
+        oldest_first: :class:`bool`
+            If set to ``True``, return messages in oldest pin->newest pin order.
+            Defaults to ``False``.
+
+            .. versionadded:: 2.6
+
         Raises
         -------
         ~discord.Forbidden
             You do not have the permission to retrieve pinned messages.
         ~discord.HTTPException
             Retrieving the pinned messages failed.
 
-        Returns
-        --------
-        List[:class:`~discord.Message`]
-            The messages that are currently pinned.
+        Yields
+        -------
+        :class:`~discord.Message`
+            The pinned message with :attr:`.Message.pinned_at` set.
         """
-
-        channel = await self._get_channel()
-        state = self._state
-        data = await state.http.pins_from(channel.id)
-        return [state.create_message(channel=channel, data=m) for m in data]
+        return _PinsIterator(self.__pins(limit=limit, before=before, oldest_first=oldest_first))
 
     async def history(
         self,

discord/activity.py

@@ -28,7 +28,7 @@
 from typing import Any, Dict, List, Optional, TYPE_CHECKING, Union, overload
 
 from .asset import Asset
-from .enums import ActivityType, try_enum
+from .enums import ActivityType, StatusDisplayType, try_enum
 from .colour import Colour
 from .partial_emoji import PartialEmoji
 from .utils import _get_as_snowflake
@@ -180,8 +180,10 @@ class Activity(BaseActivity):
 
         - ``large_image``: A string representing the ID for the large image asset.
         - ``large_text``: A string representing the text when hovering over the large image asset.
+        - ``large_url``: A string representing the URL of the large image asset.
         - ``small_image``: A string representing the ID for the small image asset.
         - ``small_text``: A string representing the text when hovering over the small image asset.
+        - ``small_url``: A string representing the URL of the small image asset.
 
     party: :class:`dict`
         A dictionary representing the activity party. It contains the following optional keys:
@@ -195,6 +197,19 @@ class Activity(BaseActivity):
 
     emoji: Optional[:class:`PartialEmoji`]
         The emoji that belongs to this activity.
+    details_url: Optional[:class:`str`]
+        A URL that is linked to when clicking on the details text of the activity.
+
+        .. versionadded:: 2.6
+    state_url: Optional[:class:`str`]
+        A URL that is linked to when clicking on the state text of the activity.
+
+        .. versionadded:: 2.6
+    status_display_type: Optional[:class:`StatusDisplayType`]
+        Determines which field from the user's status text is displayed
+        in the members list.
+
+        .. versionadded:: 2.6
     """
 
     __slots__ = (
@@ -213,6 +228,9 @@ class Activity(BaseActivity):
         'application_id',
         'emoji',
         'buttons',
+        'state_url',
+        'details_url',
+        'status_display_type',
     )
 
     def __init__(self, **kwargs: Any) -> None:
@@ -239,6 +257,18 @@ def __init__(self, **kwargs: Any) -> None:
         emoji = kwargs.pop('emoji', None)
         self.emoji: Optional[PartialEmoji] = PartialEmoji.from_dict(emoji) if emoji is not None else None
 
+        self.state_url: Optional[str] = kwargs.pop('state_url', None)
+        self.details_url: Optional[str] = kwargs.pop('details_url', None)
+
+        status_display_type = kwargs.pop('status_display_type', None)
+        self.status_display_type: Optional[StatusDisplayType] = (
+            status_display_type
+            if isinstance(status_display_type, StatusDisplayType)
+            else try_enum(StatusDisplayType, status_display_type)
+            if status_display_type is not None
+            else None
+        )
+
     def __repr__(self) -> str:
         attrs = (
             ('type', self.type),
@@ -267,6 +297,8 @@ def to_dict(self) -> Dict[str, Any]:
         ret['type'] = int(self.type)
         if self.emoji:
             ret['emoji'] = self.emoji.to_dict()
+        if self.status_display_type:
+            ret['status_display_type'] = int(self.status_display_type.value)
         return ret
 
     @property

discord/app_commands/commands.py

@@ -2524,7 +2524,10 @@ def inner(f: T) -> T:
             allowed_contexts = getattr(f, '__discord_app_commands_contexts__', None) or AppCommandContext()
             f.__discord_app_commands_contexts__ = allowed_contexts  # type: ignore # Runtime attribute assignment
 
-        allowed_contexts.guild = True
+        # Ensure that only Guild context is allowed
+        allowed_contexts.guild = True  # Enable guild context
+        allowed_contexts.private_channel = False  # Disable private channel context
+        allowed_contexts.dm_channel = False  # Disable DM context
 
         return f
 
@@ -2578,7 +2581,10 @@ def inner(f: T) -> T:
             allowed_contexts = getattr(f, '__discord_app_commands_contexts__', None) or AppCommandContext()
             f.__discord_app_commands_contexts__ = allowed_contexts  # type: ignore # Runtime attribute assignment
 
-        allowed_contexts.private_channel = True
+        # Ensure that only Private Channel context is allowed
+        allowed_contexts.guild = False  # Disable guild context
+        allowed_contexts.private_channel = True  # Enable private channel context
+        allowed_contexts.dm_channel = False  # Disable DM context
 
         return f
 
@@ -2630,7 +2636,11 @@ def inner(f: T) -> T:
             allowed_contexts = getattr(f, '__discord_app_commands_contexts__', None) or AppCommandContext()
             f.__discord_app_commands_contexts__ = allowed_contexts  # type: ignore # Runtime attribute assignment
 
-        allowed_contexts.dm_channel = True
+        # Ensure that only DM context is allowed
+        allowed_contexts.guild = False  # Disable guild context
+        allowed_contexts.private_channel = False  # Disable private channel context
+        allowed_contexts.dm_channel = True  # Enable DM context
+
         return f
 
     # Check if called with parentheses or not
@@ -2724,6 +2734,7 @@ def inner(f: T) -> T:
             f.__discord_app_commands_installation_types__ = allowed_installs  # type: ignore # Runtime attribute assignment
 
         allowed_installs.guild = True
+        allowed_installs.user = False
 
         return f
 
@@ -2774,6 +2785,7 @@ def inner(f: T) -> T:
             f.__discord_app_commands_installation_types__ = allowed_installs  # type: ignore # Runtime attribute assignment
 
         allowed_installs.user = True
+        allowed_installs.guild = False
 
         return f