Merge pull request #28 from Slipstreamm/codex/add-display_name-property-on-member

Merge PR #28

disagreement/models.py

@@ -544,6 +544,12 @@ class Member(User):  # Member inherits from User
     def __repr__(self) -> str:
         return f"<Member id='{self.id}' username='{self.username}' nick='{self.nick}'>"
 
+    @property
+    def display_name(self) -> str:
+        """Return the nickname if set, otherwise the username."""
+
+        return self.nick or self.username
+
     async def kick(self, *, reason: Optional[str] = None) -> None:
         if not self.guild_id or not self._client:
             raise DisagreementException("Member.kick requires guild_id and client")

docs/caching.md

@@ -10,7 +10,7 @@ Once you have a `Guild` object you can look up its cached members. `Guild.get_me
 guild = client.get_guild(123456789012345678)
 member = guild.get_member_named("Slipstream")
 if member:
-    print(member.id)
+    print(member.display_name)
 ```
 
 The cache can be cleared manually if needed:

docs/converters.md

@@ -22,4 +22,7 @@ async def kick(ctx: CommandContext, target: Member):
     await ctx.send(f"Kicked {target.display_name}")
 ```
 
+`Member.display_name` returns the member's nickname if one is set, otherwise it
+falls back to the username.
+
 The framework will automatically convert the first argument to a `Member` using the mention or ID provided by the user.

examples/basic_bot.py

@@ -132,7 +132,7 @@ class ExampleCog(commands.Cog):  # Ensuring this uses commands.Cog
         member = ctx.guild.get_member_named(name)
         if member:
             await ctx.reply(
-                f"Found: {member.username}#{member.discriminator} (nick: {member.nick})"
+                f"Found: {member.username}#{member.discriminator} (display: {member.display_name})"
             )
         else:
             await ctx.reply("Member not found in cache.")

tests/test_member.py

@@ -0,0 +1,22 @@
+from disagreement.models import Member
+
+
+def _make_member(member_id: str, username: str, nick: str | None):
+    data = {
+        "user": {"id": member_id, "username": username, "discriminator": "0001"},
+        "joined_at": "t",
+        "roles": [],
+    }
+    if nick is not None:
+        data["nick"] = nick
+    return Member(data, client_instance=None)
+
+
+def test_display_name_prefers_nick():
+    member = _make_member("1", "u", "nickname")
+    assert member.display_name == "nickname"
+
+
+def test_display_name_falls_back_to_username():
+    member = _make_member("2", "u2", None)
+    assert member.display_name == "u2"