feat: ✨ add Nameplate class and integration (#2817)

* ✨ add Nameplate class and integration in user model

* 🏷️ feat: add nameplate attribute to User class

* ✨ add NameplatePalette enum and enhance Nameplate class with asset retrieval

* 📝 add nameplate attribute to User class documentation

* 📝 CHANGELOG.md

* 📝 add versionadded directive for Nameplate class and NameplatePalette enum

* 📝 update Nameplate class documentation to include undocumented members

* ✏️ Fix typo in NameplatePalette

* 📝 standardize nameplate color attributes to lowercase and document each color in enums

* 📝 refine Nameplate class docstring for clarity

* Update discord/collectibles.py

Signed-off-by: Paillat <[email protected]>

* ♻️ remove NameplatePalette enum and change palette type to str

---------

Signed-off-by: Paillat <[email protected]>
Signed-off-by: Paillat <[email protected]>

Author: Paillat-dev

CHANGELOG.md

@@ -63,6 +63,8 @@ These changes are available on the `master` branch, but have not yet been releas
   ([#2775](https://github.com/Pycord-Development/pycord/pull/2775))
 - Added `discord.Interaction.created_at`.
   ([#2801](https://github.com/Pycord-Development/pycord/pull/2801))
+- Added `User.nameplate` property.
+  ([#2817](https://github.com/Pycord-Development/pycord/pull/2817))
 - Added role gradients support with `Role.colours` and the `RoleColours` class.
   ([#2818](https://github.com/Pycord-Development/pycord/pull/2818))
 

discord/__init__.py

@@ -35,6 +35,7 @@
 from .channel import *
 from .client import *
 from .cog import *
+from .collectibles import *
 from .colour import *
 from .commands import *
 from .components import *

discord/collectibles.py

@@ -0,0 +1,75 @@
+"""
+The MIT License (MIT)
+
+Copyright (c) 2021-present Pycord Development
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .state import ConnectionState
+
+from .asset import Asset
+from .types.collectibles import Nameplate as NameplatePayload
+
+
+class Nameplate:
+    """
+    Represents a Discord Nameplate.
+
+    .. versionadded:: 2.7
+
+    Attributes
+    ----------
+        sku_id: int
+            The SKU ID of the nameplate.
+        palette: str
+            The color palette of the nameplate.
+    """
+
+    def __init__(self, data: NameplatePayload, state: "ConnectionState") -> None:
+        self.sku_id: int = data["sku_id"]
+        self.palette: str = data["palette"]
+        self._label: str = data["label"]
+        self._asset: str = data["asset"]
+        self._state: "ConnectionState" = state
+
+    def __repr__(self) -> str:
+        return f"<Nameplate sku_id={self.sku_id} palette={self.palette}>"
+
+    def get_asset(self, animated: bool = False) -> Asset:
+        """Returns the asset of the nameplate.
+
+        Parameters
+        ----------
+        animated: :class:`bool`
+            Whether to return the animated version of the asset, in webm version. Defaults to ``False``.
+        """
+        fn = "static.png" if not animated else "asset.webm"
+        return Asset(
+            state=self._state,
+            url=f"{Asset.BASE}/assets/collectibles/{self._asset}{fn}",
+            key=self._asset.split("/")[-1],
+            animated=animated,
+        )
+
+
+__all__ = ("Nameplate",)

discord/types/collectibles.py

@@ -0,0 +1,36 @@
+"""
+The MIT License (MIT)
+
+Copyright (c) 2021-present Pycord Development
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from .snowflake import Snowflake
+
+
+class Nameplate(TypedDict):
+    sku_id: Snowflake
+    asset: str
+    label: str
+    palette: str

discord/user.py

@@ -30,6 +30,7 @@
 import discord.abc
 
 from .asset import Asset
+from .collectibles import Nameplate
 from .colour import Colour
 from .flags import PublicUserFlags
 from .iterators import EntitlementIterator
@@ -76,6 +77,7 @@ class BaseUser(_UserTag):
         "_public_flags",
         "_avatar_decoration",
         "_state",
+        "nameplate",
     )
 
     if TYPE_CHECKING:
@@ -91,6 +93,7 @@ class BaseUser(_UserTag):
         _accent_colour: int | None
         _avatar_decoration: dict | None
         _public_flags: int
+        nameplate: Nameplate | None
 
     def __init__(
         self, *, state: ConnectionState, data: UserPayload | PartialUserPayload
@@ -143,6 +146,11 @@ def _update(self, data: UserPayload) -> None:
         self._banner = data.get("banner", None)
         self._accent_colour = data.get("accent_color", None)
         self._avatar_decoration = data.get("avatar_decoration_data", None)
+        nameplate = (data.get("collectibles") or {}).get("nameplate", None)
+        if nameplate:
+            self.nameplate = Nameplate(data=nameplate, state=self._state)
+        else:
+            self.nameplate = None
         self._public_flags = data.get("public_flags", 0)
         self.bot = data.get("bot", False)
         self.system = data.get("system", False)
@@ -534,6 +542,10 @@ class User(BaseUser, discord.abc.Messageable):
         Specifies if the user is a bot account.
     system: :class:`bool`
         Specifies if the user is a system user (i.e. represents Discord officially).
+    nameplate: Optional[:class:`Nameplate`]
+        The user's nameplate, if the user has one.
+
+        .. versionadded:: 2.7
     """
 
     __slots__ = ("_stored",)

docs/api/models.rst

@@ -652,3 +652,13 @@ Webhooks
 
 .. autoclass:: PartialWebhookChannel()
     :members:
+
+
+
+Collectibles
+------------
+
+.. attributetable:: Nameplate
+
+.. autoclass:: Nameplate()
+    :undoc-members: