bf45abcbad
Asyncio IRC bot with decorator-based plugin system. Zero external dependencies, Python 3.11+. - IRC protocol: message parsing, formatting, async TCP/TLS connection - Plugin system: @command and @event decorators, file-based loading - Bot orchestrator: connect, dispatch, reconnect, nick recovery - CLI: argparse entry point with TOML config - Built-in plugins: ping, help, version, echo - 28 unit tests for parser and plugin system
76 lines
1.5 KiB
Markdown
76 lines
1.5 KiB
Markdown
# derp
|
|
|
|
Asyncio IRC bot for Python 3.11+ with a decorator-based plugin system. Zero external dependencies.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
git clone <repo> ~/git/derp && cd ~/git/derp
|
|
make install
|
|
# Edit config/derp.toml with your server details
|
|
make run
|
|
```
|
|
|
|
## Features
|
|
|
|
- Async IRC over plain TCP or TLS
|
|
- Plugin system with `@command` and `@event` decorators
|
|
- TOML configuration with sensible defaults
|
|
- Auto reconnect, nick recovery, PING/PONG handling
|
|
- Built-in commands: `!ping`, `!help`, `!version`
|
|
|
|
## Configuration
|
|
|
|
Edit `config/derp.toml`:
|
|
|
|
```toml
|
|
[server]
|
|
host = "irc.libera.chat"
|
|
port = 6697
|
|
tls = true
|
|
nick = "derp"
|
|
|
|
[bot]
|
|
prefix = "!"
|
|
channels = ["#test"]
|
|
plugins_dir = "plugins"
|
|
```
|
|
|
|
## Writing Plugins
|
|
|
|
Create a `.py` file in `plugins/`:
|
|
|
|
```python
|
|
from derp.plugin import command, event
|
|
|
|
@command("greet", help="Say hello")
|
|
async def cmd_greet(bot, message):
|
|
await bot.reply(message, f"Hello, {message.nick}!")
|
|
|
|
@event("JOIN")
|
|
async def on_join(bot, message):
|
|
if message.nick != bot.nick:
|
|
await bot.send(message.target, f"Welcome, {message.nick}")
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `make install` | Create venv and install |
|
|
| `make test` | Run test suite |
|
|
| `make lint` | Lint with ruff |
|
|
| `make run` | Start the bot |
|
|
| `make link` | Symlink to `~/.local/bin/` |
|
|
|
|
## Documentation
|
|
|
|
- [Installation](docs/INSTALL.md)
|
|
- [Usage Guide](docs/USAGE.md)
|
|
- [Cheatsheet](docs/CHEATSHEET.md)
|
|
- [Debugging](docs/DEBUG.md)
|
|
|
|
## License
|
|
|
|
MIT
|