Updated README.

This commit is contained in:
retoor 2025-05-05 22:13:45 +02:00
parent 4da3a5ce30
commit 25a5eca313

144
README.md
View File

@ -1,127 +1,83 @@
# Snekbot API
# 🐍 SnekBot: Your Instant Chat Companion πŸš€
This is the Snekbot API. This document describes how to create a bot responding to "hello", "bye" and "@username-of-bot".
## πŸ”₯ Create Your Own Bot in 5 Minutes Flat!
## 5 minute tutorial
### Why SnekBot?
- πŸ’¨ Lightning-fast setup
- πŸ€– Fully async and production-ready
- 🌈 Super flexible and easy to customize
- πŸ›‘οΈ Handles network issues like a boss
Literally.
### Prerequisites
- Python 3.8+ (because we're modern like that)
- A sense of adventure πŸ΄β€β˜ οΈ
### Installation
#### Requirements:
Python:
- python3
- python3-venv
- python3-pip
Use apt or your package manager to install these packages. There is a big chance your system already has them.
### Quick Installation Magic ✨
For Debian (Ubuntu): `sudo apt install python3 python3-venv python3-pip -y`
#### 1. Prep Your Environment
```bash
# Ubuntu/Debian users, get ready!
sudo apt install python3 python3-venv python3-pip -y
#### Environment
- `python3 -m venv venv`
- `source venv/bin/activate`
- `pip install git+https://molodetz.nl/retoor/snekbot.git`
# Create your bot's magical realm
python3 -m venv venv
source venv/bin/activate
```
#### Create account
Create regular user account for your bot. You need this later in your script.
Make sure you have this information right now:
- bot username
- bot password
- bot url (wss://your-snek-instance.com/rpc.ws)
#### 2. Summon SnekBot
```bash
pip install git+https://molodetz.nl/retoor/snekbot.git
```
#### Create a file
Open a file ending with the `.py` extension and paste this content. Replace the authentication details on the bottom lines with the one of the account you just created.
### πŸ€– Bot Creation Wizard
```python
import asyncio
from snekbot.bot import Bot
class ExampleBot(Bot):
class CoolSnekBot(Bot):
async def on_join(self, channel_uid):
await super().on_join(channel_uid)
print(f"I joined!")
await self.send_message(
channel_uid,
f"Hello, i'm actively part of the conversation in channel {channel_uid} now, you don't have to mention me anymore. ",
"Yo! I'm here to make this chat awesome! πŸŽ‰"
)
async def on_leave(self, channel_uid):
await super().on_leave(channel_uid)
print(f"I left!!")
await self.send_message(
channel_uid, "I stop actively being part of the conversation now. Bye!"
)
async def on_ping(self, username, user_nick, channel_uid, message):
print(f"Ping from {user_nick} in channel {channel_uid}: {message}")
await self.send_message(channel_uid, "pong " + message)
async def on_own_message(self, channel_uid, data):
print(f"Received my own message: {data.message}")
async def on_mention(self, username, user_nick, channel_uid, message):
message = message[len(self.username) + 2 :]
print(f"Mention from {user_nick}: {message}")
if "source" in message:
with open(__file__) as f:
result = f.read()
result = result.replace(f'"{self.username}"', '"example username"')
result = result.replace(self.password, "example password")
result = (
"This is the actual source code running me now. Fresh from the bakery:\n\n```python\n"
+ result
+ "\n```"
)
await self.send_message(channel_uid, result)
else:
await self.send_message(
channel_uid, f'Hey {user_nick}, Thanks for mentioning me "{message}".'
)
async def on_message(self, sender_username, sender_nick, channel_uid, message):
print(f"Message from {sender_nick}: {message}")
if not self.has_joined(channel_uid):
print(f"Probably not for me since i'm not mentioned and not joined yet")
return
message = message.lower()
result = None
if "hello" in message:
result = f"Hi @{sender_nick}"
await self.send_message(channel_uid, f"Hi there, {sender_nick}! πŸ‘‹")
elif "bye" in message:
result = f"Bye @{sender_nick}"
await self.send_message(channel_uid, f"Catch you later, {sender_nick}! πŸ€™")
if result:
await self.send_message(channel_uid, result)
bot = ExampleBot(
url="ws://snek.molodetz.nl/rpc.ws", username="example", password="example"
# Launch your bot into the wild!
bot = CoolSnekBot(
url="wss://your-snek-instance.com/rpc.ws",
username="your_awesome_bot",
password="super_secret_password"
)
asyncio.run(bot.run())
```
#### Run the bot
Make sure you have (still) activated your virtual env.
### πŸš€ Run Your Bot
```bash
python [your-script].py
python your_awesome_bot.py
```
If you get the error 'python not found' or 'aiohttp not found', run `source .venv/bin/activate` again and run `python [your script].py` again.
#### Debugging
Add `import logging` and `logging.BasicConfig(level=logging.DEBUG)`.
### Event Handlers You Can Override
- `on_join`: When bot enters a channel
- `on_leave`: When bot exits a channel
- `on_ping`: Respond to ping messages
- `on_mention`: Handle direct mentions
- `on_message`: Catch and respond to general messages
#### Summary
The `ExampleBot` class inherits from a base `Bot` class and implements several event handlers:
- `on_join`: Sends a welcome message when the bot joins a channel.
- `on_leave`: Sends a goodbye message when the bot leaves.
- `on_ping`: Responds with "pong" when it receives a ping message.
- `on_own_message`: Logs messages sent by the bot itself.
- `on_mention`: Handles mentions; if "source" is in the message, it replies with its own source code, with sensitive data disguised.
- `on_message`: Responds to "hello" and "bye" messages if the bot has joined the channel.
The bot will be instantiated and runs asynchronously. It will survive server deploys and network outages. If such issue occurs, it will try to reconnect within a second like nothing happened. It's production ready.
### πŸ’‘ Pro Tips
- Add `logging.basicConfig(level=logging.DEBUG)` for detailed logs
- The bot automatically reconnects if connection drops
- Customize to your heart's content!
### Contributing
Got cool ideas? PRs are welcome! 🀝
### License
MIT - Go wild, have fun! 🎈