Merge branch 'master' into chore/docs-cleanup

Author: Paillat-dev

.github/workflows/release.yml

@@ -215,7 +215,7 @@ jobs:
           python3 -m build --sdist
           python3 -m build --wheel
       - name: "Create GitHub Release"
-        uses: softprops/action-gh-release@v2.6.1
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
         id: gh-release
         with:
           tag_name: "v${{ inputs.version }}"

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/member.py

@@ -663,9 +663,8 @@ def display_name(self) -> str:
     def display_avatar(self) -> Asset:
         """Returns the member's display avatar.
 
-        For regular members this is just their avatar, but
-        if they have a guild specific avatar then that
-        is returned instead.
+        Returns the user's guild avatar.
+        If the user does not have a guild avatar, their global avatar is returned instead.
 
         .. versionadded:: 2.0
         """
@@ -688,9 +687,8 @@ def guild_avatar(self) -> Asset | None:
     def display_avatar_decoration(self) -> Asset | None:
         """Returns the member's displayed avatar decoration.
 
-        For regular members this is just their avatar decoration, but
-        if they have a guild specific avatar decoration then that
-        is returned instead.
+        Returns the user's guild avatar decoration.
+        If the user does not have a guild avatar decoration, their global avatar decoration is returned instead.
 
         .. versionadded:: 2.8
         """
@@ -713,9 +711,8 @@ def guild_avatar_decoration(self) -> Asset | None:
     def display_banner(self) -> Asset | None:
         """Returns the member's display banner.
 
-        For regular members this is just their banner, but
-        if they have a guild specific banner then that
-        is returned instead.
+        Returns the user's guild banner.
+        If the user does not have a guild banner, their global banner is returned instead.
 
         .. versionadded:: 2.7
         """

discord/message.py

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

discord/user.py

@@ -251,7 +251,8 @@ def default_avatar(self) -> Asset:
     def display_avatar(self) -> Asset:
         """Returns the user's display avatar.
 
-        For regular users this is just their default avatar or uploaded avatar.
+        Returns the user's uploaded avatar.
+        If the user has not uploaded any avatar, their default avatar is returned instead.
 
         .. versionadded:: 2.0
         """

docs/api/models.rst

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