Merge 98a0fe2354 into a00510988a

discord/abc.py

@@ -1722,10 +1722,20 @@ class Messageable:
         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]:
+    async def pins(
-        """|coro|
+        self,
+        *,
+        limit: Optional[int] = None,
+        before: SnowflakeTime = MISSING,
+        oldest_first: bool = False,
+    ) -> AsyncIterator[Message]:
+        """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 the following permissions to get these:
+        :attr:`~discord.Permissions.view_channel`, :attr:`~discord.Permissions.read_message_history`.
+
+        .. versionchanged:: 2.6
+            Due to a change in Discord's API, this now returns a paginated iterator instead of a list.
 
         .. note::
 
@@ -1733,6 +1743,27 @@ class Messageable:
             objects returned by this method do not contain complete
             :attr:`.Message.reactions` data.
 
+        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: 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->newest order.
+            Defaults to ``False``.
+
+            .. versionadded:: 2.6
+
         Raises
         -------
         ~discord.Forbidden
@@ -1742,14 +1773,48 @@ class Messageable:
 
         Returns
         --------
-        List[:class:`~discord.Message`]
+        :class:`~discord.Message`
-            The messages that are currently pinned.
+            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)
+        max_limit: int = 50
-        return [state.create_message(channel=channel, data=m) for m in data]
+
+        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:
+                return
+
+            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:
+                reversed(items)
+
+            for m in items:
+                message = state.create_message(channel=channel, data=m['message'])
+                message._pinned_at = utils.parse_time(m['pinned_at'])
+                yield message
 
     async def history(
         self,

discord/http.py

@@ -1040,7 +1040,7 @@ class HTTPClient:
     def pin_message(self, channel_id: Snowflake, message_id: Snowflake, reason: Optional[str] = None) -> Response[None]:
         r = Route(
             'PUT',
-            '/channels/{channel_id}/pins/{message_id}',
+            '/channels/{channel_id}/messages/pins/{message_id}',
             channel_id=channel_id,
             message_id=message_id,
         )
@@ -1049,14 +1049,25 @@ class HTTPClient:
     def unpin_message(self, channel_id: Snowflake, message_id: Snowflake, reason: Optional[str] = None) -> Response[None]:
         r = Route(
             'DELETE',
-            '/channels/{channel_id}/pins/{message_id}',
+            '/channels/{channel_id}/messages/pins/{message_id}',
             channel_id=channel_id,
             message_id=message_id,
         )
         return self.request(r, reason=reason)
 
-    def pins_from(self, channel_id: Snowflake) -> Response[List[message.Message]]:
+    def pins_from(
-        return self.request(Route('GET', '/channels/{channel_id}/pins', channel_id=channel_id))
+        self,
+        channel_id: Snowflake,
+        limit: Optional[int] = None,
+        before: Optional[str] = None,
+    ) -> Response[message.ChannelPins]:
+        params = {}
+        if before is not None:
+            params['before'] = before
+        if limit is not None:
+            params['limit'] = limit
+
+        return self.request(Route('GET', '/channels/{channel_id}/messages/pins', channel_id=channel_id), params=params)
 
     # Member management
 

discord/message.py

@@ -2174,6 +2174,7 @@ class Message(PartialMessage, Hashable):
         'call',
         'purchase_notification',
         'message_snapshots',
+        '_pinned_at',
     )
 
     if TYPE_CHECKING:
@@ -2213,6 +2214,8 @@ class Message(PartialMessage, Hashable):
         self.application_id: Optional[int] = utils._get_as_snowflake(data, 'application_id')
         self.stickers: List[StickerItem] = [StickerItem(data=d, state=state) for d in data.get('sticker_items', [])]
         self.message_snapshots: List[MessageSnapshot] = MessageSnapshot._from_value(state, data.get('message_snapshots'))
+        # Set by Messageable.pins
+        self._pinned_at: Optional[datetime.datetime] = None
 
         self.poll: Optional[Poll] = None
         try:
@@ -2633,6 +2636,18 @@ class Message(PartialMessage, Hashable):
             # Fall back to guild threads in case one was created after the message
             return self._thread or self.guild.get_thread(self.id)
 
+    @property
+    def pinned_at(self) -> Optional[datetime.datetime]:
+        """Optional[:class:`datetime.datetime`]: An aware UTC datetime object containing the time
+        when the message was pinned.
+
+        .. note::
+            This is only set for messages that are returned by :meth:`abc.Messageable.pins`.
+
+        .. versionadded:: 2.6
+        """
+        return self._pinned_at
+
     @property
     @deprecated('interaction_metadata')
     def interaction(self) -> Optional[MessageInteraction]:

discord/types/message.py

@@ -237,3 +237,13 @@ class AllowedMentions(TypedDict):
     roles: SnowflakeList
     users: SnowflakeList
     replied_user: bool
+
+
+class MessagePin(TypedDict):
+    pinned_at: str
+    message: Message
+
+
+class ChannelPins(TypedDict):
+    items: List[MessagePin]
+    has_more: bool