feat: support new username system

changelog/1025.feature.rst

@@ -0,0 +1,7 @@
+Add support for new username system - see the official :ddocs:`changelog <change-log#unique-usernames-on-discord>` for details. Existing functionality is kept backwards-compatible while the migration is still ongoing.
+- Add :attr:`User.global_name`, and update attributes/methods to account for it:
+    - :attr:`User.display_name` and :attr:`Member.display_name`
+    - :meth:`Guild.get_member_named`
+    - |commands| :class:`~ext.commands.UserConverter` and :class:`~ext.commands.MemberConverter`, now largely matching the behavior of :meth:`Guild.get_member_named`
+- Update ``str(user)`` and ``str(member)`` to not include ``#0`` discriminator of migrated users.
+- Adjust :attr:`User.default_avatar` to account for new default avatar handling.

disnake/abc.py

@@ -132,6 +132,19 @@ class User(Snowflake, Protocol):
         The user's username.
     discriminator: :class:`str`
         The user's discriminator.
+
+        .. deprecated:: 2.9
+            This is being phased out by Discord; the username system is moving away from ``username#discriminator``
+            to users having a globally unique ``@username``.
+            The value of a single zero (``"0"``) indicates that the user has been migrated to the new system.
+            See the :ddocs:`changelog <change-log#unique-usernames-on-discord>` for details.
+    global_name: Optional[:class:`str`]
+        The user's global display name, if set.
+        This takes precedence over :attr:`.name` when shown.
+
+        For bots, this is the application name.
+
+        .. versionadded:: 2.9
     avatar: :class:`~disnake.Asset`
         The avatar asset the user has.
     bot: :class:`bool`
@@ -142,6 +155,7 @@ class User(Snowflake, Protocol):
 
     name: str
     discriminator: str
+    global_name: Optional[str]
     avatar: Asset
     bot: bool
 

disnake/ext/commands/converter.py

@@ -188,29 +188,40 @@ class MemberConverter(IDConverter[disnake.Member]):
 
     1. Lookup by ID.
     2. Lookup by mention.
-    3. Lookup by name#discrim
-    4. Lookup by name
-    5. Lookup by nickname
+    3. Lookup by name#discrim.
+    4. Lookup by nickname.
+    5. Lookup by global name.
+    6. Lookup by name.
+
+    The name resolution order matches the one used by :meth:`.Guild.get_member_named`.
 
     .. versionchanged:: 1.5
         Raise :exc:`.MemberNotFound` instead of generic :exc:`.BadArgument`
 
     .. versionchanged:: 1.5.1
         This converter now lazily fetches members from the gateway and HTTP APIs,
         optionally caching the result if :attr:`.MemberCacheFlags.joined` is enabled.
+
+    .. versionchanged:: 2.9
+        Name resolution order changed from ``name > nick`` to ``nick > global_name > name``
+        to account for the username migration.
     """
 
     async def query_member_named(
         self, guild: disnake.Guild, argument: str
     ) -> Optional[disnake.Member]:
         cache = guild._state.member_cache_flags.joined
         if len(argument) > 5 and argument[-5] == "#":
+            # legacy behavior for non-migrated users
             username, _, discriminator = argument.rpartition("#")
             members = await guild.query_members(username, limit=100, cache=cache)
             return _utils_get(members, name=username, discriminator=discriminator)
         else:
             members = await guild.query_members(argument, limit=100, cache=cache)
-            return disnake.utils.find(lambda m: m.name == argument or m.nick == argument, members)
+            return disnake.utils.find(
+                lambda m: m.nick == argument or m.global_name == argument or m.name == argument,
+                members,
+            )
 
     async def query_member_by_id(
         self, bot: disnake.Client, guild: disnake.Guild, user_id: int
@@ -286,15 +297,19 @@ class UserConverter(IDConverter[disnake.User]):
 
     1. Lookup by ID.
     2. Lookup by mention.
-    3. Lookup by name#discrim
-    4. Lookup by name
+    3. Lookup by name#discrim.
+    4. Lookup by global name.
+    5. Lookup by name.
 
     .. versionchanged:: 1.5
         Raise :exc:`.UserNotFound` instead of generic :exc:`.BadArgument`
 
     .. versionchanged:: 1.6
         This converter now lazily fetches users from the HTTP APIs if an ID is passed
         and it's not available in cache.
+
+    .. versionchanged:: 2.9
+        Now takes :attr:`~disnake.User.global_name` into account.
     """
 
     async def convert(self, ctx: AnyContext, argument: str) -> disnake.User:
@@ -332,6 +347,7 @@ async def convert(self, ctx: AnyContext, argument: str) -> disnake.User:
 
         # check for discriminator if it exists,
         if len(arg) > 5 and arg[-5] == "#":
+            # legacy behavior for non-migrated users
             discrim = arg[-4:]
             name = arg[:-5]
             result = disnake.utils.find(
@@ -340,7 +356,10 @@ async def convert(self, ctx: AnyContext, argument: str) -> disnake.User:
             if result is not None:
                 return result
 
-        result = disnake.utils.find(lambda u: u.name == arg, state._users.values())
+        result = disnake.utils.find(
+            lambda u: u.global_name == arg or u.name == arg,
+            state._users.values(),
+        )
 
         if result is None:
             raise UserNotFound(argument)
@@ -1000,7 +1019,8 @@ class clean_content(Converter[str]):
     fix_channel_mentions: :class:`bool`
         Whether to clean channel mentions.
     use_nicknames: :class:`bool`
-        Whether to use nicknames when transforming mentions.
+        Whether to use :attr:`nicknames <.Member.nick>` and
+        :attr:`global names <.Member.global_name>` when transforming mentions.
     escape_markdown: :class:`bool`
         Whether to also escape special markdown characters.
     remove_markdown: :class:`bool`
@@ -1030,6 +1050,7 @@ def resolve_user(id: int) -> str:
             m = (msg and _utils_get(msg.mentions, id=id)) or bot.get_user(id)
             if m is None and ctx.guild:
                 m = ctx.guild.get_member(id)
+            # TODO: add a separate option for `global_name`s?
             return f"@{m.display_name if self.use_nicknames else m.name}" if m else "@deleted-user"
 
         def resolve_role(id: int) -> str:

disnake/flags.py

@@ -1136,6 +1136,7 @@ def members(self):
         - :attr:`User.name`
         - :attr:`User.avatar`
         - :attr:`User.discriminator`
+        - :attr:`User.global_name`
 
         For more information go to the :ref:`member intent documentation <need_members_intent>`.
 

disnake/guild.py

@@ -1117,31 +1117,36 @@ def created_at(self) -> datetime.datetime:
     def get_member_named(self, name: str, /) -> Optional[Member]:
         """Returns the first member found that matches the name provided.
 
-        The name can have an optional discriminator argument, e.g. "Jake#0001"
-        or "Jake" will both do the lookup. However the former will give a more
-        precise result. Note that the discriminator must have all 4 digits
-        for this to work.
+        The lookup strategy is as follows (in order):
 
-        If a nickname is passed, then it is looked up via the nickname. Note
-        however, that a nickname + discriminator combo will not lookup the nickname
-        but rather the username + discriminator combo due to nickname + discriminator
-        not being unique.
+        1. Lookup by nickname.
+        2. Lookup by global name.
+        3. Lookup by name.
+
+        While the migration away from discriminators is still ongoing,
+        the name can have an optional discriminator argument, e.g. "Jake#0001",
+        in which case it will be treated as a username + discriminator combo
+        (note: this only works with usernames, not nicknames).
 
         If no member is found, ``None`` is returned.
 
+        .. versionchanged:: 2.9
+            Now takes :attr:`User.global_name` into account.
+
         Parameters
         ----------
         name: :class:`str`
-            The name of the member to lookup with an optional discriminator.
+            The name of the member to lookup (with an optional discriminator).
 
         Returns
         -------
         Optional[:class:`Member`]
             The member in this guild with the associated name. If not found
             then ``None`` is returned.
         """
-        result = None
         members = self.members
+
+        # legacy behavior for non-migrated users
         if len(name) > 5 and name[-5] == "#":
             # The 5 length is checking to see if #0000 is in the string,
             # as a#0000 has a length of 6, the minimum for a potential
@@ -1155,7 +1160,7 @@ def get_member_named(self, name: str, /) -> Optional[Member]:
                 return result
 
         def pred(m: Member) -> bool:
-            return m.nick == name or m.name == name
+            return m.nick == name or m.global_name == name or m.name == name
 
         return utils.find(pred, members)
 

disnake/member.py

@@ -230,7 +230,7 @@ class Member(disnake.abc.Messageable, _UserTag):
 
         .. describe:: str(x)
 
-            Returns the member's name with the discriminator.
+            Returns the member's username (with discriminator, if not migrated to new system yet), or global name if set.
 
     Attributes
     ----------
@@ -249,6 +249,7 @@ class Member(disnake.abc.Messageable, _UserTag):
         The guild that the member belongs to.
     nick: Optional[:class:`str`]
         The guild specific nickname of the user.
+        This takes precedence over :attr:`.global_name` and :attr:`.name` when shown.
     pending: :class:`bool`
         Whether the member is pending member verification.
 
@@ -278,6 +279,7 @@ class Member(disnake.abc.Messageable, _UserTag):
     if TYPE_CHECKING:
         name: str
         id: int
+        global_name: Optional[str]
         bot: bool
         system: bool
         created_at: datetime.datetime
@@ -345,7 +347,7 @@ def __str__(self) -> str:
 
     def __repr__(self) -> str:
         return (
-            f"<Member id={self._user.id} name={self._user.name!r} discriminator={self._user.discriminator!r}"
+            f"<Member id={self._user.id} name={self._user.name!r} global_name={self._user.global_name!r} discriminator={self._user.discriminator!r}"
             f" bot={self._user.bot} nick={self.nick!r} guild={self.guild!r}>"
         )
 
@@ -449,17 +451,18 @@ def _presence_update(
 
     def _update_inner_user(self, user: UserPayload) -> Optional[Tuple[User, User]]:
         u = self._user
-        original = (u.name, u._avatar, u.discriminator, u._public_flags)
+        original = (u.name, u._avatar, u.discriminator, u.global_name, u._public_flags)
         # These keys seem to always be available
         modified = (
             user["username"],
             user["avatar"],
             user["discriminator"],
+            user.get("global_name"),
             user.get("public_flags", 0),
         )
         if original != modified:
             to_return = User._copy(self._user)
-            u.name, u._avatar, u.discriminator, u._public_flags = modified
+            u.name, u._avatar, u.discriminator, u.global_name, u._public_flags = modified
             # Signal to dispatch on_user_update
             return to_return, u
 
@@ -483,10 +486,23 @@ def status(self, value: Status) -> None:
 
     @property
     def tag(self) -> str:
+        """:class:`str`: An alias of :attr:`.discriminator`.
+
+        .. deprecated:: 2.9
+            See :attr:`.discriminator`.
+        """
         return self._user.discriminator
 
     @property
     def discriminator(self) -> str:
+        """:class:`str`:The user's discriminator.
+
+        .. deprecated:: 2.9
+            This is being phased out by Discord; the username system is moving away from ``username#discriminator``
+            to users having a globally unique ``@username``.
+            The value of a single zero (``"0"``) indicates that the user has been migrated to the new system.
+            See the :ddocs:`changelog <change-log#unique-usernames-on-discord>` for details.
+        """
         return self._user.discriminator
 
     @property
@@ -566,11 +582,11 @@ def mention(self) -> str:
     def display_name(self) -> str:
         """:class:`str`: Returns the user's display name.
 
-        For regular users this is just their username, but
-        if they have a guild specific nickname then that
-        is returned instead.
+        If they have a guild-specific :attr:`nickname <.nick>`, then
+        that is returned. If not, this is their :attr:`global name <.global_name>`
+        if set, or their :attr:`username <.name>` otherwise.
         """
-        return self.nick or self.name
+        return self.nick or self.global_name or self.name
 
     @property
     def display_avatar(self) -> Asset:

disnake/team.py

@@ -84,7 +84,7 @@ class TeamMember(BaseUser):
 
         .. describe:: str(x)
 
-            Returns the team member's name with discriminator.
+            Returns the team member's username (with discriminator, if not migrated to new system yet), or global name if set.
 
     .. versionadded:: 1.3
 
@@ -95,7 +95,18 @@ class TeamMember(BaseUser):
     id: :class:`int`
         The team member's unique ID.
     discriminator: :class:`str`
-        The team member's discriminator. This is given when the username has conflicts.
+        The team member's discriminator.
+
+        .. deprecated:: 2.9
+            This is being phased out by Discord; the username system is moving away from ``username#discriminator``
+            to users having a globally unique ``@username``.
+            The value of a single zero (``"0"``) indicates that the user has been migrated to the new system.
+            See the :ddocs:`changelog <change-log#unique-usernames-on-discord>` for details.
+    global_name: Optional[:class:`str`]
+        The team members's global display name, if set.
+        This takes precedence over :attr:`.name` when shown.
+
+        .. versionadded:: 2.9
     avatar: Optional[:class:`str`]
         The avatar hash the team member has. Could be None.
     bot: :class:`bool`
@@ -118,6 +129,6 @@ def __init__(self, team: Team, state: ConnectionState, data: TeamMemberPayload)
 
     def __repr__(self) -> str:
         return (
-            f"<{self.__class__.__name__} id={self.id} name={self.name!r} "
-            f"discriminator={self.discriminator!r} membership_state={self.membership_state!r}>"
+            f"<{self.__class__.__name__} id={self.id} name={self.name!r} global_name={self.global_name!r}"
+            f" discriminator={self.discriminator!r} membership_state={self.membership_state!r}>"
         )

disnake/types/user.py

@@ -2,13 +2,16 @@
 
 from typing import Literal, Optional, TypedDict
 
+from typing_extensions import NotRequired
+
 from .snowflake import Snowflake
 
 
 class PartialUser(TypedDict):
     id: Snowflake
     username: str
-    discriminator: str
+    discriminator: str  # may be removed in future API versions
+    global_name: NotRequired[Optional[str]]
     avatar: Optional[str]