fix: Fix incorrect types on MessagePinIterator & document MessagePin

CHANGELOG.md

@@ -27,6 +27,8 @@ These changes are available on the `master` branch, but have not yet been releas
   ([#3181](https://github.com/Pycord-Development/pycord/pull/3181))
 - Fixed internal use of deprecated \_PayloadLike dict operations.
   ([#3189](https://github.com/Pycord-Development/pycord/pull/3189))
+- Fixed incorrect type hints for `MessagePinIterator`.
+  ([#3178](https://github.com/Pycord-Development/pycord/pull/3178))
 
 ### Deprecated
 

discord/abc.py

@@ -35,6 +35,7 @@
     Iterable,
     Protocol,
     Sequence,
+    TypeAlias,
     TypeVar,
     Union,
     overload,
@@ -97,10 +98,15 @@
     from .ui.view import BaseView
     from .user import ClientUser
 
-    PartialMessageableChannel = Union[
-        TextChannel, VoiceChannel, StageChannel, Thread, DMChannel, PartialMessageable
-    ]
-    MessageableChannel = Union[PartialMessageableChannel, GroupChannel]
+    PartialMessageableChannel: TypeAlias = (
+        TextChannel
+        | VoiceChannel
+        | StageChannel
+        | Thread
+        | DMChannel
+        | PartialMessageable
+    )
+    MessageableChannel: TypeAlias = PartialMessageableChannel | GroupChannel
     SnowflakeTime = Union["Snowflake", datetime]
 
     from .voice import VoiceClient, VoiceProtocol

discord/iterators.py

@@ -39,10 +39,12 @@
     Union,
 )
 
+from typing_extensions import deprecated, override
+
 from .audit_logs import AuditLogEntry
 from .errors import NoMoreItems
 from .object import Object
-from .utils import maybe_coroutine, snowflake_time, time_snowflake, warn_deprecated
+from .utils import maybe_coroutine, snowflake_time, time_snowflake
 
 __all__ = (
     "ReactionIterator",
@@ -53,12 +55,13 @@
     "ScheduledEventSubscribersIterator",
     "EntitlementIterator",
     "SubscriptionIterator",
+    "MessagePinIterator",
 )
 
 if TYPE_CHECKING:
-    from .abc import Snowflake
-    from .channel import MessageableChannel
+    from .abc import MessageableChannel, Snowflake
     from .guild import BanEntry, Guild
+    from .http import HTTPClient
     from .member import Member
     from .message import Message, MessagePin
     from .monetization import Entitlement, Subscription
@@ -1210,9 +1213,13 @@ def __init__(
         limit: int | None,
         before: Snowflake | datetime.datetime | None = None,
     ):
-        self._channel = channel
-        self.limit = limit
-        self.http = channel._state.http
+        self._channel: MessageableChannel = channel
+        self.channel: MessageableChannel | Object | None = None
+
+        self.limit: int | None = limit
+        self.http: HTTPClient = (
+            channel._state.http  # pyright: ignore[reportPrivateUsage]
+        )
 
         self.before: str | None
         if before is None:
@@ -1224,11 +1231,10 @@ def __init__(
 
         self.update_before: Callable[[MessagePinPayload], str] = self.get_last_pinned
 
-        self.endpoint = self.http.pins_from
-
         self.queue: asyncio.Queue[MessagePin] = asyncio.Queue()
         self.has_more: bool = True
 
+    @override
     async def next(self) -> MessagePin:
         if self.queue.empty():
             await self.fill_queue()
@@ -1246,12 +1252,16 @@ async def fill_queue(self) -> None:
         if not self.has_more:
             raise NoMoreItems()
 
-        if not hasattr(self, "channel"):
-            channel = await self._channel._get_channel()
+        if self.channel is None:
+            channel = (
+                await self._channel._get_channel()  # pyright: ignore[reportPrivateUsage]
+            )
             self.channel = channel
 
         limit = 50 if self.limit is None else min(self.limit, 50)
-        data = await self.endpoint(self.channel.id, before=self.before, limit=limit)
+        data = await self.http.pins_from(
+            self.channel.id, before=self.before, limit=limit
+        )
 
         pins: list[MessagePinPayload] = data.get("items", [])
         for d in pins:
@@ -1269,17 +1279,25 @@ async def fill_queue(self) -> None:
     def create_pin(self, data: MessagePinPayload) -> MessagePin:
         from .message import MessagePin
 
-        return MessagePin(state=self.channel._state, channel=self.channel, data=data)
+        if self.channel is None:
+            raise RuntimeError("Channel is None, cannot create pin")
+
+        if isinstance(self.channel, Object):
+            raise RuntimeError("Cannot create pin for Object channel")
+
+        return MessagePin(
+            state=self.channel._state,  # pyright: ignore[reportPrivateUsage]
+            channel=self.channel,
+            data=data,
+        )
 
     async def retrieve_inner(self) -> list[Message]:
         pins = await self.flatten()
         return [p.message for p in pins]
 
-    def __await__(self) -> Generator[Any, Any, MessagePin]:
-        warn_deprecated(
-            f"Messageable.pins() returning a list of Message",
-            since="2.7",
-            removed="3.0",
-            reference="The documentation of pins()",
-        )
+    @deprecated(
+        "Messageable.pins() returning a list of Message is deprecated since version 2.7 and will be removed in 2.9."
+        + " See the documentation of Messageable.pins() for more information."
+    )
+    def __await__(self) -> Generator[Any, Any, list[Message]]:
         return self.retrieve_inner().__await__()

discord/message.py

@@ -102,6 +102,7 @@
 __all__ = (
     "Attachment",
     "Message",
+    "MessagePin",
     "PartialMessage",
     "MessageReference",
     "MessageCall",

docs/api/models.rst

@@ -89,6 +89,11 @@ Messages
 .. autoclass:: Message()
     :members:
 
+.. attributetable:: MessagePin
+
+.. autoclass:: MessagePin()
+    :members:
+
 .. attributetable:: MessageSnapshot
 
 .. autoclass:: MessageSnapshot()