Updated README.
This commit is contained in:
parent
4da3a5ce30
commit
25a5eca313
144
README.md
144
README.md
@ -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! π
|
||||
|
||||
|
Loadingβ¦
Reference in New Issue
Block a user