cordslite 🍺

A minimal Discord bot library. Like a Coors Lite for Discord — light, refreshing, gets the job done.

Usage

Installation

Install latest from the GitHub repository:

$ pip install git+https://github.com/AnswerDotAI/cordslite.git

or from conda

$ conda install -c AnswerDotAI cordslite

or from pypi

$ pip install cordslite

How to use

Setup

Getting a Bot Token:

  1. Go to the Discord Developer Portal
  2. Create an application, then go to “Bot” and create a bot
  3. Copy the token and set it as an environment variable:
export DISCORD_BOT_TOKEN='your_token_here'
  1. Under “OAuth2 → URL Generator”, select bot scope, choose permissions, and use the generated URL to invite the bot to your server

Initialize the client:

from cordslite.core import *

dc = DiscordClient()

Guilds and Channels

Fetch a guild (server) and explore its channels:

gid = '1327046393453613076'
gld = await dc.get_guild('your_guild_id')
gld
Guild(id=1327046393453613076, name="natedog's server")
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:

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 
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:

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!
async def on_msg(msg): print(f"{msg.author['username']}: {msg.content}")

gc.on('MESSAGE_CREATE', on_msg)
msg = await ch.send('Watch this ma!'); msg
Message(id=1469794227717275752, author='Search Agent', content='Watch this ma!')
await gc.stop()
Gateway stopped!

Bot

Bot ties REST and Gateway together with a decorator-based command router. The function name becomes the command name, prefixed with ! in Discord:

bot = Bot(intents)
await bot.start()
Connected! Session: ed2a8f494e50101e6985b6792d20f082, heartbeat: 41250ms
Gateway started!
@bot.cmd
async def echo(msg, args): await (await msg.get_channel()).send(f'You said: {args}')

bot
Bot(cmds=['echo'])
@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:

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'
import time
time.sleep(5)
pth = vc.stop_recording()
await bot.leave_voice()
await bot.stop()
Gateway stopped!
from IPython.display import Audio
Audio(pth[0])

API Reference

Objects

Object Key Fields
DiscordClient token, cli, _req(), get_guild()
Guild id, name, channels(), members()
Channel id, name, type, messages(), send()
Message id, content, author, timestamp, get_channel()
Member user, nick, roles, joined_at
GatewayClient on(), start(), stop(), recv_evt()
VoiceClient join(), leave(), start_recording(), stop_recording()
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)