https://github.com/answerdotai/cordslite
https://github.com/answerdotai/cordslite
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/answerdotai/cordslite
- Owner: AnswerDotAI
- License: apache-2.0
- Created: 2026-02-07T14:25:40.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T18:16:49.000Z (about 1 month ago)
- Last Synced: 2026-04-12T20:24:54.979Z (about 1 month ago)
- Language: Jupyter Notebook
- Homepage: https://AnswerDotAI.github.io/cordslite
- Size: 815 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# cordslite 🍺
## Usage
### Installation
Install latest from the GitHub
[repository](https://github.com/AnswerDotAI/cordslite):
``` sh
$ pip install git+https://github.com/AnswerDotAI/cordslite.git
```
or from [conda](https://anaconda.org/AnswerDotAI/cordslite)
``` sh
$ conda install -c AnswerDotAI cordslite
```
or from [pypi](https://pypi.org/project/cordslite/)
``` sh
$ pip install cordslite
```
## How to use
### Setup
**Getting a Bot Token:**
1. Go to the [Discord Developer
Portal](https://discord.com/developers/applications)
2. Create an application, then go to “Bot” and create a bot
3. Copy the token and set it as an environment variable:
``` bash
export DISCORD_BOT_TOKEN='your_token_here'
```
4. Under “OAuth2 → URL Generator”, select `bot` scope, choose
permissions, and use the generated URL to invite the bot to your
server
**Initialize the client:**
``` python
from cordslite.core import *
dc = DiscordClient()
```
### Guilds and Channels
Fetch a guild (server) and explore its channels:
``` python
gid = '1327046393453613076'
gld = await dc.get_guild('your_guild_id')
gld
```
Guild(id=1327046393453613076, name="natedog's server")
``` python
chs = await gld.channels(); chs
```
| ID | Name | Type |
|---------------------|----------------|------|
| 1327046393453613077 | Text Channels | 4 |
| 1327046393453613078 | Voice Channels | 4 |
| 1327046393453613079 | general | 0 |
| 1327046393453613080 | General | 2 |
| 1327954661960978512 | private | 0 |
### Messages
Fetch recent messages from a channel and send one:
``` python
ch = chs[2]
msgs = await ch.messages(5); msgs
```
| ID | Author | Content | Date |
|----|----|----|----|
| 1469779647867781141 | nate.dawgg | !err error! | 2026-02-07 |
| 1469788591751303282 | Search Agent | Hi, from Solveit! | 2026-02-07 |
| 1469788597153698007 | Search Agent | Testing the Gateway! 🎉 | 2026-02-07 |
| 1469788597690306633 | Search Agent | Test our event listener! Otters are awesome 🦦 | 2026-02-07 |
| 1469793925655953490 | Search Agent | Hello from cordslite! 🍺 | 2026-02-07 |
``` python
msg = await ch.send('Hello from cordslite! 🍺'); msg
```
Message(id=1469794127855222875, author='Search Agent', content='Hello from cordslite! 🍺')
### Gateway (Real-time Events)
The Gateway provides real-time events via WebSocket. Connect, then
register handlers for events like `MESSAGE_CREATE`:
``` python
intents = (1 << 0) | (1 << 9) | (1 << 15) # GUILDS | GUILD_MESSAGES | MESSAGE_CONTENT
gc = GatewayClient(intents, dc)
await gc.start()
```
Connected! Session: 8bb0098c37e6243270d0c62e90f34097, heartbeat: 41250ms
Gateway started!
Search Agent: Watch this ma!
``` python
async def on_msg(msg): print(f"{msg.author['username']}: {msg.content}")
gc.on('MESSAGE_CREATE', on_msg)
```
``` python
msg = await ch.send('Watch this ma!'); msg
```
Message(id=1469794227717275752, author='Search Agent', content='Watch this ma!')
``` python
await gc.stop()
```
Gateway stopped!
### Bot
[`Bot`](https://AnswerDotAI.github.io/cordslite/core.html#bot) ties REST
and Gateway together with a decorator-based command router. The function
name becomes the command name, prefixed with `!` in Discord:
``` python
bot = Bot(intents)
await bot.start()
```
Connected! Session: ed2a8f494e50101e6985b6792d20f082, heartbeat: 41250ms
Gateway started!
``` python
@bot.cmd
async def echo(msg, args): await (await msg.get_channel()).send(f'You said: {args}')
bot
```
Bot(cmds=['echo'])
``` python
@bot.on_error
async def handle_err(msg, e): print(f'Error: {e}')
await bot.stop()
```
Gateway stopped!
Errors in command handlers are caught and stored in `bot.errors` for
debugging. You can also register a real-time error handler:
### Voice
Join a voice channel, record audio, and leave:
``` python
bot = Bot(intents)
await bot.start()
vch = (await gld.channels())[3] # your voice channel
vc = await bot.join_voice(vch)
vc.start_recording(path='/tmp/recording.mp3')
```
Connected! Session: c20f63cc3fcb71e75d90d72e04d961c2, heartbeat: 41250ms
Gateway started!
Voice ready!
'/tmp/recording.mp3'
``` python
import time
time.sleep(5)
pth = vc.stop_recording()
await bot.leave_voice()
await bot.stop()
```
Gateway stopped!
``` python
from IPython.display import Audio
Audio(pth)
```
Your browser does not support the audio element.
## API Reference
### Objects
| Object | Key Fields |
|----|----|
| [`DiscordClient`](https://AnswerDotAI.github.io/cordslite/core.html#discordclient) | `token`, `cli`, `_req()`, `get_guild()` |
| [`Guild`](https://AnswerDotAI.github.io/cordslite/core.html#guild) | `id`, `name`, `channels()`, `members()` |
| [`Channel`](https://AnswerDotAI.github.io/cordslite/core.html#channel) | `id`, `name`, `type`, `messages()`, `send()` |
| [`Message`](https://AnswerDotAI.github.io/cordslite/core.html#message) | `id`, `content`, `author`, `timestamp`, `get_channel()` |
| [`Member`](https://AnswerDotAI.github.io/cordslite/core.html#member) | `user`, `nick`, `roles`, `joined_at` |
| [`GatewayClient`](https://AnswerDotAI.github.io/cordslite/core.html#gatewayclient) | `on()`, `start()`, `stop()`, `recv_evt()` |
| [`VoiceClient`](https://AnswerDotAI.github.io/cordslite/core.html#voiceclient) | `join()`, `leave()`, `start_recording()`, `stop_recording()` |
| [`Bot`](https://AnswerDotAI.github.io/cordslite/core.html#bot) | `cmd()`, `on_error()`, `start()`, `stop()`, `join_voice()`, `leave_voice()` |
### REST Methods
| Method | Description |
|---------------------------|---------------------------|
| `dc.get_guild(id)` | Fetch a guild |
| `guild.channels()` | List guild channels |
| `guild.members(limit)` | List guild members |
| `channel.messages(limit)` | Fetch channel messages |
| `channel.send(content)` | Send a message |
| `msg.get_channel()` | Get the message’s channel |
### Gateway Events
| Event | Description |
|-----------------------|-------------------------------------|
| `MESSAGE_CREATE` | New message sent |
| `MESSAGE_UPDATE` | Message edited |
| `MESSAGE_DELETE` | Message deleted |
| `GUILD_CREATE` | Guild data received on connect |
| `CHANNEL_CREATE` | New channel created |
| `VOICE_SERVER_UPDATE` | Voice server info (used internally) |