func

Author: NeloBlivion

discord/abc.py

@@ -48,7 +48,7 @@
 from .file import File, VoiceMessage
 from .flags import ChannelFlags, MessageFlags
 from .invite import Invite
-from .iterators import HistoryIterator
+from .iterators import HistoryIterator, MessagePinIterator
 from .mentions import AllowedMentions
 from .partial_emoji import PartialEmoji, _EmojiTag
 from .permissions import PermissionOverwrite, Permissions
@@ -1765,6 +1765,10 @@ async def pins(self) -> list[Message]:
             objects returned by this method do not contain complete
             :attr:`.Message.reactions` data.
 
+        .. warning::
+
+            Starting from version 3.0, this will return a :class:`discord.MessagePinIterator`. See :func:`fetch_pins` for the new behavior.
+
         Returns
         -------
         List[:class:`~discord.Message`]
@@ -1775,12 +1779,72 @@ async def pins(self) -> list[Message]:
         ~discord.HTTPException
             Retrieving the pinned messages failed.
         """
-
+        utils.warn_deprecated(
+            f"Messageable.pins() returning a list of Message",
+            since="2.7",
+            removed="3.0",
+            reference="The behavior of fetch_pins"
+        )
         channel = await self._get_channel()
         state = self._state
         data = await state.http.legacy_pins_from(channel.id)
         return [state.create_message(channel=channel, data=m) for m in data]
 
+    def fetch_pins(
+        self,
+        *,
+        limit: int | None = 50,
+        before: SnowflakeTime | None = None,
+    ) -> MessagePinIterator:
+        """Returns a :class:`~discord.MessagePinIterator` that enables receiving the destination's pinned messages.
+
+        You must have :attr:`~discord.Permissions.read_message_history` permissions to use this.
+
+        Parameters
+        ----------
+        limit: Optional[:class:`int`]
+            The number of pinned messages to retrieve.
+            If ``None``, retrieves every pinned message in the channel.
+        before: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]]
+            Retrieve messages pinned before this datetime.
+            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.
+
+        Yields
+        ------
+        :class:`~discord.MessagePin`
+            The pinned message.
+
+        Raises
+        ------
+        ~discord.Forbidden
+            You do not have permissions to get pinned messages.
+        ~discord.HTTPException
+            The request to get pinned messages failed.
+
+        Examples
+        --------
+
+        Usage ::
+
+            counter = 0
+            async for pin in channel.fetch_pins(limit=250):
+                if pin.message.author == client.user:
+                    counter += 1
+
+        Flattening into a list: ::
+
+            pins = await channel.fetch_pins(limit=None).flatten()
+            # pins is now a list of MessagePin...
+
+        All parameters are optional.
+        """
+        return MessagePinIterator(
+            self,
+            limit=limit,
+            before=before,
+        )
+
     def can_send(self, *objects) -> bool:
         """Returns a :class:`bool` indicating whether you have the permissions to send the object(s).
 

discord/iterators.py

@@ -59,7 +59,7 @@
     from .channel import MessageableChannel
     from .guild import BanEntry, Guild
     from .member import Member
-    from .message import Message
+    from .message import Message, MessagePin
     from .monetization import Entitlement, Subscription
     from .scheduled_events import ScheduledEvent
     from .threads import Thread
@@ -1209,7 +1209,7 @@ def __init__(
         limit: int | None,
         before: Snowflake | datetime.datetime | None = None,
     ):
-        self.channel = channel
+        self._channel = channel
         self.limit = limit
         self.http = channel._state.http
 
@@ -1245,8 +1245,12 @@ async def fill_queue(self) -> None:
         if not self.has_more:
             raise NoMoreItems()
 
+        if not hasattr(self, "channel"):
+            channel = await self._channel._get_channel()
+            self.channel = channel
+
         limit = 50 if self.limit is None else max(self.limit, 50)
-        data = await self.endpoint(self.channel_id, before=self.before, limit=limit)
+        data = await self.endpoint(self.channel.id, before=self.before, limit=limit)
 
         pins: list[MessagePinPayload] = data.get("items", [])
         for d in pins:

discord/message.py

@@ -822,6 +822,9 @@ def pinned_at(self) -> datetime.datetime:
         """An aware timestamp of when the message was pinned."""
         return self._pinned_at
 
+    def __repr__(self) -> str:
+        return f"<MessagePin pinned_at={self.pinned_at!r} message={self.message!r}>"
+
 
 @flatten_handlers
 class Message(Hashable):