feat: update the message pin endpoints

changelog/1305.deprecate.rst

@@ -0,0 +1 @@
+Deprecate awaiting :meth:`.Messageable.pins` in favour of ``async for msg in channel.pins()``.

changelog/1305.feature.rst

@@ -0,0 +1 @@
+Update the :meth:`.Messageable.pins`, :meth:`Message.pin` and :meth:`Message.unpin` methods to use the new API endpoints. :meth:`.Messageable.pins` returns now an asynchronous iterator to yield all pinned messages.

disnake/abc.py

@@ -70,7 +70,7 @@
     from .enums import InviteTarget
     from .guild import Guild, GuildChannel as AnyGuildChannel, GuildMessageable
     from .guild_scheduled_event import GuildScheduledEvent
-    from .iterators import HistoryIterator
+    from .iterators import ChannelPinsIterator, HistoryIterator
     from .member import Member
     from .message import Message, MessageReference, PartialMessage
     from .poll import Poll
@@ -1863,31 +1863,64 @@ 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|
+    def pins(
+        self, *, limit: Optional[int] = 50, before: Optional[SnowflakeTime] = None
+    ) -> ChannelPinsIterator:
+        """Returns an :class:`.AsyncIterator` that enables receiving the destination's pinned messages.
 
-        Retrieves all messages that are currently pinned in the channel.
+        You must have the :attr:`.Permissions.read_message_history` and :attr:`.Permissions.view_channel` permissions to use this.
 
         .. note::
 
             Due to a limitation with the Discord API, the :class:`.Message`
             objects returned by this method do not contain complete
             :attr:`.Message.reactions` data.
 
+        .. versionchanged:: 2.11
+            Now returns an :class:`.AsyncIterator` to support changes in Discord's API.
+            ``await``\\ing the result of this method remains supported, but only returns the
+            last 50 pins and is deprecated in favor of ``async for msg in channel.pins()``.
+
+        Examples
+        --------
+        Usage ::
+
+            counter = 0
+            async for message in channel.pins(limit=100):
+                if message.author == client.user:
+                    counter += 1
+
+        Flattening to a list ::
+
+            pinned_messages = await channel.pins(limit=100).flatten()
+            # pinned_messages is now a list of Message...
+
+        All parameters are optional.
+
+        Parameters
+        ----------
+        limit: Optional[:class:`int`]
+            The number of pinned messages to retrieve.
+            If ``None``, retrieves every pinned message in the channel. Note, however,
+            that this would make it a slow operation.
+        before: Optional[Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]]
+            Retrieve messages pinned before this date or message.
+            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.
+
         Raises
         ------
         HTTPException
             Retrieving the pinned messages failed.
 
-        Returns
-        -------
-        List[:class:`.Message`]
-            The messages that are currently pinned.
+        Yields
+        ------
+        :class:`.Message`
+            The pinned message from the parsed message data.
         """
-        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]
+        from .iterators import ChannelPinsIterator  # due to cyclic imports
+
+        return ChannelPinsIterator(self, limit=limit, before=before)
 
     def history(
         self,

disnake/http.py

@@ -876,7 +876,7 @@ def pin_message(
     ) -> 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,
         )
@@ -887,14 +887,29 @@ def unpin_message(
     ) -> 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]]:
-        return self.request(Route("GET", "/channels/{channel_id}/pins", channel_id=channel_id))
+    def get_pins(
+        self,
+        channel_id: Snowflake,
+        limit: int,
+        before: Optional[Snowflake] = None,
+    ) -> Response[channel.ChannelPins]:
+        r = Route(
+            "GET",
+            "/channels/{channel_id}/messages/pins",
+            channel_id=channel_id,
+        )
+        params: Dict[str, Any] = {"limit": limit}
+
+        if before is not None:
+            params["before"] = before
+
+        return self.request(r, params=params)
 
     # Member management
 

disnake/iterators.py

@@ -11,6 +11,7 @@
     Awaitable,
     Callable,
     Dict,
+    Generator,
     List,
     Optional,
     TypeVar,
@@ -29,7 +30,7 @@
 from .object import Object
 from .subscription import Subscription
 from .threads import Thread
-from .utils import maybe_coroutine, snowflake_time, time_snowflake
+from .utils import deprecated, maybe_coroutine, parse_time, snowflake_time, time_snowflake
 
 __all__ = (
     "ReactionIterator",
@@ -1308,3 +1309,76 @@ async def fill_users(self) -> None:
                 if not (self.guild is None or isinstance(self.guild, Object)):
                     member = self.guild.get_member(int(element["id"]))
                 await self.users.put(member or self.state.create_user(data=element))
+
+
+class ChannelPinsIterator(_AsyncIterator["Message"]):
+    def __init__(
+        self,
+        messageable: Messageable,
+        *,
+        limit: Optional[int],
+        before: Optional[Union[Snowflake, datetime.datetime]] = None,
+    ) -> None:
+        before_ = None
+        if before is not None:
+            if isinstance(before, datetime.datetime):
+                before_ = before.isoformat()
+            elif isinstance(before, Object):
+                before_ = snowflake_time(before.id).isoformat()
+            else:
+                raise TypeError(
+                    f"Expected either `disnake.Snowflake` or `datetime.datetime` for `before`. Got `{before.__class__.__name__!r}`."
+                )
+
+        self.messageable = messageable
+        self._state = messageable._state
+        self.limit = limit
+        self.before: Optional[str] = before_
+
+        self.getter = self._state.http.get_pins
+        self.messages: asyncio.Queue[Message] = asyncio.Queue()
+
+    # defined to maintain backward compatibility with the old `pins` method
+    @deprecated("async for msg in channel.pins()")
+    def __await__(self) -> Generator[None, None, List[Message]]:
+        return self.flatten().__await__()
+
+    async def next(self) -> Message:
+        if self.messages.empty():
+            await self.fill_messages()
+
+        try:
+            return self.messages.get_nowait()
+        except asyncio.QueueEmpty:
+            raise NoMoreItems from None
+
+    def _get_retrieve(self) -> bool:
+        self.retrieve = min(self.limit, 50) if self.limit is not None else 50
+        return self.retrieve > 0
+
+    async def fill_messages(self) -> None:
+        if not hasattr(self, "channel"):
+            channel = await self.messageable._get_channel()
+            self.channel = channel
+
+        if self._get_retrieve():
+            data = await self.getter(
+                channel_id=self.channel.id,
+                before=self.before,
+                limit=self.retrieve,
+            )
+
+            if len(data):
+                if self.limit is not None:
+                    self.limit -= self.retrieve
+
+                if data["items"]:
+                    self.before = data["items"][-1]["pinned_at"]
+
+            if not data["has_more"]:
+                self.limit = 0  # terminate loop
+
+            for element in data["items"]:
+                message = self._state.create_message(channel=self.channel, data=element["message"])
+                message._pinned_at = parse_time(element["pinned_at"])
+                await self.messages.put(message)

disnake/message.py

@@ -1157,6 +1157,7 @@ class Message(Hashable):
         "poll",
         "_edited_timestamp",
         "_role_subscription_data",
+        "_pinned_at",
     )
 
     if TYPE_CHECKING:
@@ -1197,6 +1198,7 @@ def __init__(
         )
         self.type: MessageType = try_enum(MessageType, data["type"])
         self.pinned: bool = data["pinned"]
+        self._pinned_at: Optional[datetime.datetime] = None
         self.flags: MessageFlags = MessageFlags._from_value(data.get("flags", 0))
         self.mention_everyone: bool = data["mention_everyone"]
         self.tts: bool = data["tts"]
@@ -1556,6 +1558,17 @@ def edited_at(self) -> Optional[datetime.datetime]:
         """Optional[:class:`datetime.datetime`]: An aware UTC datetime object containing the edited time of the message."""
         return self._edited_timestamp
 
+    @property
+    def pinned_at(self) -> Optional[datetime.datetime]:
+        """Optional[:class:`datetime.datetime`]: An aware UTC datetime object containing the pin time of the message.
+
+        .. note::
+            This is only set on messages retrieved using :meth:`abc.Messageable.pins`.
+
+        .. versionadded:: 2.11
+        """
+        return self._pinned_at
+
     @property
     def jump_url(self) -> str:
         """:class:`str`: Returns a URL that allows the client to jump to this message."""
@@ -2137,7 +2150,7 @@ async def pin(self, *, reason: Optional[str] = None) -> None:
 
         Pins the message.
 
-        You must have the :attr:`~Permissions.manage_messages` permission to do
+        You must have the :attr:`~Permissions.pin_messages` permission to do
         this in a non-private channel context.
 
         This does not work with messages sent in a :class:`VoiceChannel` or :class:`StageChannel`.
@@ -2167,7 +2180,7 @@ async def unpin(self, *, reason: Optional[str] = None) -> None:
 
         Unpins the message.
 
-        You must have the :attr:`~Permissions.manage_messages` permission to do
+        You must have the :attr:`~Permissions.pin_messages` permission to do
         this in a non-private channel context.
 
         Parameters

disnake/permissions.py

@@ -760,7 +760,7 @@ def send_tts_messages(self) -> int:
 
     @flag_value
     def manage_messages(self) -> int:
-        """:class:`bool`: Returns ``True`` if a user can delete or pin messages in a text channel.
+        """:class:`bool`: Returns ``True`` if a user can delete messages in a text channel.
 
         .. note::
 

disnake/types/channel.py

@@ -4,6 +4,7 @@
 
 from typing_extensions import NotRequired
 
+from .message import MessagePin
 from .snowflake import Snowflake
 from .threads import ForumTag, ThreadArchiveDurationLiteral, ThreadMember, ThreadMetadata
 from .user import PartialUser
@@ -196,3 +197,8 @@ class CreateGuildChannel(TypedDict):
     rtc_region: NotRequired[Optional[str]]
     video_quality_mode: NotRequired[Optional[VideoQualityMode]]
     default_auto_archive_duration: NotRequired[Optional[ThreadArchiveDurationLiteral]]
+
+
+class ChannelPins(TypedDict):
+    items: List[MessagePin]
+    has_more: bool

disnake/types/message.py

@@ -159,3 +159,8 @@ class AllowedMentions(TypedDict):
     roles: SnowflakeList
     users: SnowflakeList
     replied_user: bool
+
+
+class MessagePin(TypedDict):
+    pinned_at: str
+    message: Message