Add member search and listing methods to Guild

cordslite/_modidx.py

@@ -59,6 +59,7 @@
                                 'cordslite.core.Guild': ('core.html#guild', 'cordslite/core.py'),
                                 'cordslite.core.Guild.__repr__': ('core.html#guild.__repr__', 'cordslite/core.py'),
                                 'cordslite.core.Guild.channels': ('core.html#guild.channels', 'cordslite/core.py'),
+                                'cordslite.core.Guild.find_member': ('core.html#guild.find_member', 'cordslite/core.py'),
                                 'cordslite.core.Guild.members': ('core.html#guild.members', 'cordslite/core.py'),
                                 'cordslite.core.Guild.search': ('core.html#guild.search', 'cordslite/core.py'),
                                 'cordslite.core.Member': ('core.html#member', 'cordslite/core.py'),

cordslite/core.py

@@ -139,6 +139,21 @@ async def search(self:Guild, content=None, author_id=None, channel_id=None, ment
     r = await self.client._req('GET', f'/guilds/{self.id}/messages/search', params=params)
     return Messages(Message(m[0], self.client) for m in r.json()['messages'])
 
+# %% ../nbs/00_core.ipynb #44642992
+@patch
+async def find_member(self:Guild, name):
+    "Search guild members by name/nick, return first match's user ID or None"
+    data = (await self.client._req( 'GET', f'/guilds/{self.id}/members/search',
+                                    params={'query': name, 'limit': 1})).json()
+    return data[0]['user']['id'] if data else None
+
+# %% ../nbs/00_core.ipynb #eeaf8a6f
+@patch(as_prop=True)
+async def members(self:Guild):
+    "List all guild members' display names (nick > global_name > username)"
+    data = (await self.client._req('GET', f'/guilds/{self.id}/members', params={'limit': 1000})).json()
+    return [m.get('nick') or m['user'].get('global_name') or m['user']['username'] for m in data]
+
 # %% ../nbs/00_core.ipynb #3fd1132c
 @patch
 async def send(self:Channel, content='', files=None):

nbs/00_core.ipynb

@@ -225,7 +225,9 @@
       ]
      },
      "execution_count": null,
-     "metadata": {},
+     "metadata": {
+      "__type": "Guild"
+     },
      "output_type": "execute_result"
     }
    ],
@@ -287,18 +289,21 @@
     {
      "data": {
       "text/html": [
-       "<table class=\"prose\"><thead><tr><th>ID</th><th>Name</th><th>Type</th></tr></thead><tbody><tr><td>1327046393453613077</td><td>Text Channels</td><td>4</td></tr><tr><td>1327046393453613078</td><td>Voice Channels</td><td>4</td></tr><tr><td>1327046393453613079</td><td>general</td><td>0</td></tr><tr><td>1327046393453613080</td><td>General</td><td>2</td></tr><tr><td>1327954661960978512</td><td>private</td><td>0</td></tr></tbody></table>"
+       "<table class=\"prose\"><thead><tr><th>ID</th><th>Name</th><th>Type</th></tr></thead><tbody><tr><td>1327046393453613077</td><td>Text Channels</td><td>4</td></tr><tr><td>1327046393453613078</td><td>Voice Channels</td><td>4</td></tr><tr><td>1327046393453613079</td><td>general</td><td>0</td></tr><tr><td>1327046393453613080</td><td>General</td><td>2</td></tr><tr><td>1327954661960978512</td><td>private</td><td>0</td></tr><tr><td>1475600987627458812</td><td>forwarded</td><td>0</td></tr></tbody></table>"
       ],
       "text/plain": [
        "[Channel(id=1327046393453613077, name='Text Channels', type=4),\n",
        " Channel(id=1327046393453613078, name='Voice Channels', type=4),\n",
        " Channel(id=1327046393453613079, name='general', type=0),\n",
        " Channel(id=1327046393453613080, name='General', type=2),\n",
-       " Channel(id=1327954661960978512, name='private', type=0)]"
+       " Channel(id=1327954661960978512, name='private', type=0),\n",
+       " Channel(id=1475600987627458812, name='forwarded', type=0)]"
       ]
      },
      "execution_count": null,
-     "metadata": {},
+     "metadata": {
+      "__type": "Channels"
+     },
      "output_type": "execute_result"
     }
    ],
@@ -319,7 +324,9 @@
       ]
      },
      "execution_count": null,
-     "metadata": {},
+     "metadata": {
+      "__type": "Channel"
+     },
      "output_type": "execute_result"
     }
    ],
@@ -355,19 +362,7 @@
    "execution_count": null,
    "id": "461bcb8b",
    "metadata": {},
-   "outputs": [
-    {
-     "ename": "IndentationError",
-     "evalue": "unexpected indent (2441870440.py, line 6)",
-     "output_type": "error",
-     "traceback": [
-      "  \u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[6]\u001b[39m\u001b[32m, line 6\u001b[39m",
-      "\u001b[31m    \u001b[39m\u001b[31mself.data['content'] = re.sub( r'<@!?(\\d+)>',\u001b[39m",
-      "    ^",
-      "\u001b[31mIndentationError\u001b[39m\u001b[31m:\u001b[39m unexpected indent"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "#| export\n",
     "class Message(DiscordObject):\n",
@@ -422,18 +417,20 @@
     {
      "data": {
       "text/html": [
-       "<table class=\"prose\"><thead><tr><th>ID</th><th>Author</th><th>Content</th><th>Date</th></tr></thead><tbody><tr><td>1473455208284684320</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr><tr><td>1473468026882887823</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-17</td></tr><tr><td>1473468028950675577</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr><tr><td>1473468409684426845</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-17</td></tr><tr><td>1473468411853148376</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr></tbody></table>"
+       "<table class=\"prose\"><thead><tr><th>ID</th><th>Author</th><th>Content</th><th>Date</th></tr></thead><tbody><tr><td>1473468409684426845</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-17</td></tr><tr><td>1473468411853148376</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr><tr><td>1473720714816393372</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-18</td></tr><tr><td>1473721117276373023</td><td>nate.dawgg</td><td>@DBuddy</td><td>2026-02-18</td></tr><tr><td>1490061485593071666</td><td>DBuddy</td><td>Hi from SolveitAI! 👋</td><td>2026-04-04</td></tr></tbody></table>"
       ],
       "text/plain": [
-       "[Message(id=1473455208284684320, author='DBuddy', content='Here is a file!'),\n",
-       " Message(id=1473468026882887823, author='DBuddy', content='Hi, from Solveit!'),\n",
-       " Message(id=1473468028950675577, author='DBuddy', content='Here is a file!'),\n",
-       " Message(id=1473468409684426845, author='DBuddy', content='Hi, from Solveit!'),\n",
-       " Message(id=1473468411853148376, author='DBuddy', content='Here is a file!')]"
+       "[Message(id=1473468409684426845, author='DBuddy', content='Hi, from Solveit!'),\n",
+       " Message(id=1473468411853148376, author='DBuddy', content='Here is a file!'),\n",
+       " Message(id=1473720714816393372, author='DBuddy', content='Hi, from Solveit!'),\n",
+       " Message(id=1473721117276373023, author='nate.dawgg', content='@DBuddy'),\n",
+       " Message(id=1490061485593071666, author='DBuddy', content='Hi from SolveitAI! 👋')]"
       ]
      },
      "execution_count": null,
-     "metadata": {},
+     "metadata": {
+      "__type": "Messages"
+     },
      "output_type": "execute_result"
     }
    ],
@@ -486,10 +483,25 @@
     {
      "data": {
       "text/html": [
-       "<table class=\"prose\"><thead><tr><th>ID</th><th>Author</th><th>Content</th><th>Date</th></tr></thead><tbody><tr><td>1473468411853148376</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr><tr><td>1473468409684426845</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-17</td></tr><tr><td>1473468028950675577</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr><tr><td>1473468026882887823</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-17</td></tr><tr><td>1473455208284684320</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr><tr><td>1473455165708435556</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-17</td></tr><tr><td>1473452262922911961</td><td>nate.dawgg</td><td>howdy!</td><td>2026-02-17</td></tr></tbody></table>"
+       "<table class=\"prose\"><thead><tr><th>ID</th><th>Author</th><th>Content</th><th>Date</th></tr></thead><tbody><tr><td>1490061485593071666</td><td>DBuddy</td><td>Hi from SolveitAI! 👋</td><td>2026-04-04</td></tr><tr><td>1483815592933720094</td><td>nate.dawgg</td><td></td><td>2026-03-18</td></tr><tr><td>1483812396307976363</td><td>nate.dawgg</td><td></td><td>2026-03-18</td></tr><tr><td>1481403515963183155</td><td>nate.dawgg</td><td></td><td>2026-03-11</td></tr><tr><td>1481022276089544834</td><td>nate.dawgg</td><td></td><td>2026-03-10</td></tr><tr><td>1478064387796242443</td><td>nate.dawgg</td><td></td><td>2026-03-02</td></tr><tr><td>1477046398754099456</td><td>nate.dawgg</td><td></td><td>2026-02-27</td></tr><tr><td>1476505929750155305</td><td>nate.dawgg</td><td></td><td>2026-02-26</td></tr><tr><td>1476303849030422670</td><td>nate.dawgg</td><td></td><td>2026-02-25</td></tr><tr><td>1476195818473263165</td><td>nate.dawgg</td><td></td><td>2026-02-25</td></tr><tr><td>1475827802887553054</td><td>nate.dawgg</td><td></td><td>2026-02-24</td></tr><tr><td>1475601140518359322</td><td>nate.dawgg</td><td></td><td>2026-02-23</td></tr><tr><td>1475601048742793400</td><td>nate.dawgg</td><td></td><td>2026-02-23</td></tr><tr><td>1473721117276373023</td><td>nate.dawgg</td><td>@DBuddy</td><td>2026-02-18</td></tr><tr><td>1473720714816393372</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-18</td></tr><tr><td>1473468411853148376</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr><tr><td>1473468409684426845</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-17</td></tr><tr><td>1473468028950675577</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr><tr><td>1473468026882887823</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-17</td></tr><tr><td>1473455208284684320</td><td>DBuddy</td><td>Here is a file!</td><td>2026-02-17</td></tr><tr><td>1473455165708435556</td><td>DBuddy</td><td>Hi, from Solveit!</td><td>2026-02-17</td></tr><tr><td>1473452262922911961</td><td>nate.dawgg</td><td>howdy!</td><td>2026-02-17</td></tr></tbody></table>"
       ],
       "text/plain": [
-       "[Message(id=1473468411853148376, author='DBuddy', content='Here is a file!'),\n",
+       "[Message(id=1490061485593071666, author='DBuddy', content='Hi from SolveitAI! 👋'),\n",
+       " Message(id=1483815592933720094, author='nate.dawgg', content=''),\n",
+       " Message(id=1483812396307976363, author='nate.dawgg', content=''),\n",
+       " Message(id=1481403515963183155, author='nate.dawgg', content=''),\n",
+       " Message(id=1481022276089544834, author='nate.dawgg', content=''),\n",
+       " Message(id=1478064387796242443, author='nate.dawgg', content=''),\n",
+       " Message(id=1477046398754099456, author='nate.dawgg', content=''),\n",
+       " Message(id=1476505929750155305, author='nate.dawgg', content=''),\n",
+       " Message(id=1476303849030422670, author='nate.dawgg', content=''),\n",
+       " Message(id=1476195818473263165, author='nate.dawgg', content=''),\n",
+       " Message(id=1475827802887553054, author='nate.dawgg', content=''),\n",
+       " Message(id=1475601140518359322, author='nate.dawgg', content=''),\n",
+       " Message(id=1475601048742793400, author='nate.dawgg', content=''),\n",
+       " Message(id=1473721117276373023, author='nate.dawgg', content='@DBuddy'),\n",
+       " Message(id=1473720714816393372, author='DBuddy', content='Hi, from Solveit!'),\n",
+       " Message(id=1473468411853148376, author='DBuddy', content='Here is a file!'),\n",
        " Message(id=1473468409684426845, author='DBuddy', content='Hi, from Solveit!'),\n",
        " Message(id=1473468028950675577, author='DBuddy', content='Here is a file!'),\n",
        " Message(id=1473468026882887823, author='DBuddy', content='Hi, from Solveit!'),\n",
@@ -499,14 +511,117 @@
       ]
      },
      "execution_count": null,
-     "metadata": {},
+     "metadata": {
+      "__type": "Messages"
+     },
      "output_type": "execute_result"
     }
    ],
    "source": [
     "await gld.search(after='2026-02-16')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "cdd89759",
+   "metadata": {},
+   "source": [
+    "Sometimes you need to search by name rather than snowflake ID. `find_member` searches the guild's members by username, nickname, or display name using Discord's member search endpoint, and returns the first match's user ID. This makes it easy to chain into `search`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "44642992",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "@patch\n",
+    "async def find_member(self:Guild, name):\n",
+    "    \"Search guild members by name/nick, return first match's user ID or None\"\n",
+    "    data = (await self.client._req( 'GET', f'/guilds/{self.id}/members/search',\n",
+    "                                    params={'query': name, 'limit': 1})).json()\n",
+    "    return data[0]['user']['id'] if data else None"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "aafd6bef",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<table class=\"prose\"><thead><tr><th>ID</th><th>Author</th><th>Content</th><th>Date</th></tr></thead><tbody><tr><td>1483815592933720094</td><td>nate.dawgg</td><td></td><td>2026-03-18</td></tr><tr><td>1483812396307976363</td><td>nate.dawgg</td><td></td><td>2026-03-18</td></tr><tr><td>1481403515963183155</td><td>nate.dawgg</td><td></td><td>2026-03-11</td></tr><tr><td>1481022276089544834</td><td>nate.dawgg</td><td></td><td>2026-03-10</td></tr><tr><td>1478064387796242443</td><td>nate.dawgg</td><td></td><td>2026-03-02</td></tr></tbody></table>"
+      ],
+      "text/plain": [
+       "[Message(id=1483815592933720094, author='nate.dawgg', content=''),\n",
+       " Message(id=1483812396307976363, author='nate.dawgg', content=''),\n",
+       " Message(id=1481403515963183155, author='nate.dawgg', content=''),\n",
+       " Message(id=1481022276089544834, author='nate.dawgg', content=''),\n",
+       " Message(id=1478064387796242443, author='nate.dawgg', content='')]"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {
+      "__type": "Messages"
+     },
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "uid = await gld.find_member('nate')\n",
+    "await gld.search(author_id=uid, limit=5)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8aae2813",
+   "metadata": {},
+   "source": [
+    "The `members` property fetches all guild members and returns their display names, preferring server nickname over global display name over username. Note: this requires the **Server Members Intent** enabled in the Developer Portal (Bot → Privileged Gateway Intents)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "eeaf8a6f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "@patch(as_prop=True)\n",
+    "async def members(self:Guild):\n",
+    "    \"List all guild members' display names (nick > global_name > username)\"\n",
+    "    data = (await self.client._req('GET', f'/guilds/{self.id}/members', params={'limit': 1000})).json()\n",
+    "    return [m.get('nick') or m['user'].get('global_name') or m['user']['username'] for m in data]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cdd2e812",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "['nathan', 'SearchBuddy', 'DBuddy', 'Dizcord Util Bot', 'Search Agent']"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {
+      "__type": "list"
+     },
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "await gld.members"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "89d2bbdd",