Metadata-Version: 2.4
Name: cordslite
Version: 0.2.2
Author-email: Nathan Cooper <nathanacooper@proton.me>
License: Apache-2.0
Project-URL: Repository, https://github.com/AnswerDotAI/cordslite
Project-URL: Documentation, https://AnswerDotAI.github.io/cordslite/
Keywords: nbdev
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore>=1.12.11
Requires-Dist: httpx2
Requires-Dist: websockets
Provides-Extra: dev
Requires-Dist: numpy; extra == "dev"
Provides-Extra: voice
Requires-Dist: davey; extra == "voice"
Requires-Dist: ffmpeg-python>=0.2.0; extra == "voice"
Requires-Dist: opuslib-next>=1.1.5; extra == "voice"
Requires-Dist: pynacl>=1.6.2; extra == "voice"
Dynamic: license-file

# cordslite 🍺


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## 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 [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 add a bot under “Bot”.
3.  Copy the token and set it as an environment variable:

``` bash
export DISCORD_BOT_TOKEN='your_token_here'
```

4.  Under “OAuth2”, generate an invite URL with the `bot` scope and the permissions you need, and open it to invite the bot to your server.

Then create the client:

``` python
from cordslite import *
```

``` python
dc = DiscordClient()
```

### Guilds and Channels

Fetch a guild (server) and explore its channels:

``` python
gid = '1493461895615873044'
gld = await dc.guild(gid)
gld
```

``` python
Guild(id=1493461895615873044, name='AAI-test-dev')
```

``` python
chs = await gld.channels()
chs
```

| ID                  | Name           | Type |
|---------------------|----------------|------|
| 1493461896139903026 | Text Channels  | 4    |
| 1493461896139903027 | Voice Channels | 4    |
| 1493461896139903028 | general        | 0    |
| 1493461896139903029 | General        | 2    |

### Messages

Fetch recent messages from a channel and send one:

``` python
ch = chs[2]
msgs = await ch.messages(5)
msgs
```

| ID                  | Author     | Content                  | Date       |
|---------------------|------------|--------------------------|------------|
| 1545126723224600577 | share2self | Watch this ma!           | 2026-09-03 |
| 1545127267020054540 | share2self | Hello from cordslite! 🍺 | 2026-09-03 |
| 1545127273374552074 | share2self | Watch this ma!           | 2026-09-03 |
| 1545127676359082054 | share2self | Hello from cordslite! 🍺 | 2026-09-03 |
| 1545127678238003282 | share2self | Watch this ma!           | 2026-09-03 |

``` python
msg = await ch.send('Hello from cordslite! 🍺')
msg
```

``` python
Message(id=1545128287922159727, author='share2self', content='Hello from cordslite! 🍺')
```

### Gateway (Real-time Events)

Connect, then register handlers for events such as `MESSAGE_CREATE`:

``` python
intents = Intent.GUILDS | Intent.GUILD_VOICE_STATES | Intent.GUILD_MESSAGES | Intent.MESSAGE_CONTENT
gc = GatewayClient(intents, dc)
await gc.start()
```

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

``` python
Message(id=1545128289734107176, author='share2self', content='Watch this ma!')
```

``` python
await gc.stop()
```

### Bot

[`Bot`](https://AnswerDotAI.github.io/cordslite/bot.html#bot) ties REST and Gateway together with a decorator-based command router. It lives in `cordslite.bot`, alongside the voice support, and needs the `voice` extra: `pip install cordslite[voice]`. The function name becomes the command name, prefixed with `!` in Discord:

``` python
from cordslite.bot import *
```

``` python
bot = Bot(intents)
await bot.start()
```

``` python
@bot.cmd
async def echo(msg, args): await (await msg.channel).send(f'You said: {args}')

bot
```

    Bot(cmds=['echo'])

The router catches errors in command handlers and stores them in `bot.errors`. You can also register a handler that runs as they happen:

``` python
@bot.on_error
async def handle_err(msg, e): print(f'Error: {e}')
```

``` python
import asyncio
```

### Voice

Join a voice channel, record audio, and leave:

``` python
vch = next(c for c in await gld.channels() if c.type == 2)
vc = await bot.join_voice(vch)
await asyncio.wait_for(vc.sess.wait(), 15)
vc.start_recording(path='/tmp/recording.mp3')
```

    voice json 15 {'any': 100}

    '/tmp/recording.mp3'

``` python
await asyncio.sleep(5)
res = await vc.stop_recording()
await bot.leave_voice()
await bot.stop()
res
```

    {'speakers': {}, 'mixed': None}

``` python
from IPython.display import Audio
```

``` python
Audio(res['mixed'])
```
