feat: Add support for user.primary_guild

Introduces the PrimaryGuild class and its type definition, adds the primary_guild attribute to the User model, and implements asset support for primary guild badges. Updates the changelog to document these additions.

Author: Lulalaby

CHANGELOG.md

@@ -69,6 +69,8 @@ These changes are available on the `master` branch, but have not yet been releas
   ([#2818](https://github.com/Pycord-Development/pycord/pull/2818))
 - Added `Interaction.attachment_size_limit`.
   ([#2854](https://github.com/Pycord-Development/pycord/pull/2854))
+- Added `discord.User.primary_guild` and the `PrimaryGuild` class.
+  ([#2876](https://github.com/Pycord-Development/pycord/pull/2876))
 
 ### Fixed
 

discord/asset.py

@@ -201,6 +201,31 @@ def _from_avatar_decoration(
             animated=animated,
         )
 
+    @classmethod
+    def _from_user_primary_guild_tag(cls, state, identity_guild_id: int, badge_id: str) -> Asset:
+        """Creates an Asset for a user's primary guild (tag) badge.
+
+        Parameters
+        ----------
+        state: ConnectionState
+            The connection state.
+        identity_guild_id: int
+            The ID of the guild.
+        badge_id: str
+            The badge hash/id.
+
+        Returns
+        -------
+        :class:`Asset`
+            The primary guild badge asset.
+        """
+        return cls(
+            state,
+            url=f"{Asset.BASE}/guild-tag-badges/{identity_guild_id}/{badge_id}.png?size=256",
+            key=badge_id,
+            animated=False,
+        )
+
     @classmethod
     def _from_guild_avatar(
         cls, state, guild_id: int, member_id: int, avatar: str

discord/primary_guild.py

@@ -0,0 +1,74 @@
+"""
+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.primary_guild import PrimaryGuild as PrimaryGuildPayload
+
+
+class PrimaryGuild:
+    """
+    Represents a Discord Primary Guild.
+
+    .. versionadded:: 2.7
+
+    Attributes
+    ----------
+        identity_guild_id: int
+            The ID of the guild.
+        identity_enabled: :class:`bool`
+            Whether the primary guild is enabled.
+        tag: str
+            The tag of the primary guild.
+    """
+
+    def __init__(self, data: PrimaryGuildPayload, state: "ConnectionState") -> None:
+        self.identity_guild_id: int = data["identity_guild_id"]
+        self.identity_enabled: bool | None = data.get("identity_enabled", None)
+        self.tag: str = data["tag"]
+        self._badge: str = data["badge"]
+        self._state: "ConnectionState" = state
+
+    def __repr__(self) -> str:
+        return f"<PrimaryGuild identity_guild_id={self.identity_guild_id} identity_enabled={self.identity_enabled} tag={self.tag}>"
+        
+    @property
+    def badge(self) -> Asset | None:
+        """Returns the badge asset, if available.
+
+        .. versionadded:: 2.7
+
+        .. note::
+            This information is only available via :meth:`Client.fetch_user`.
+        """
+        if self._badge is None:
+            return None
+        return Asset._from_user_primary_guild_tag(self._state, self.identity_guild_id, self._badge)
+
+
+__all__ = ("PrimaryGuild",)

discord/types/primary_guild.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 PrimaryGuild(TypedDict):
+    identity_guild_id: Snowflake
+    identity_enabled: bool | None
+    tag: str
+    badge: str

discord/user.py

@@ -29,6 +29,7 @@
 
 import discord.abc
 
+from .primary_guild import PrimaryGuild
 from .asset import Asset
 from .collectibles import Nameplate
 from .colour import Colour
@@ -78,6 +79,7 @@ class BaseUser(_UserTag):
         "_avatar_decoration",
         "_state",
         "nameplate",
+        "primary_guild",
     )
 
     if TYPE_CHECKING:
@@ -94,6 +96,7 @@ class BaseUser(_UserTag):
         _avatar_decoration: dict | None
         _public_flags: int
         nameplate: Nameplate | None
+        primary_guild: PrimaryGuild | None
 
     def __init__(
         self, *, state: ConnectionState, data: UserPayload | PartialUserPayload
@@ -151,6 +154,7 @@ def _update(self, data: UserPayload) -> None:
             self.nameplate = Nameplate(data=nameplate, state=self._state)
         else:
             self.nameplate = None
+        self.primary_guild = data.get("primary_guild", None)
         self._public_flags = data.get("public_flags", 0)
         self.bot = data.get("bot", False)
         self.system = data.get("system", False)
@@ -170,6 +174,7 @@ def _copy(cls: type[BU], user: BU) -> BU:
         self.bot = user.bot
         self._state = user._state
         self._public_flags = user._public_flags
+        self.primary_guild = user.primary_guild
 
         return self