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
|
### Quick Installation Magic β¨
|
||||||
#### 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.
|
|
||||||
|
|
||||||
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
|
# Create your bot's magical realm
|
||||||
- `python3 -m venv venv`
|
python3 -m venv venv
|
||||||
- `source venv/bin/activate`
|
source venv/bin/activate
|
||||||
- `pip install git+https://molodetz.nl/retoor/snekbot.git`
|
```
|
||||||
|
|
||||||
#### Create account
|
#### 2. Summon SnekBot
|
||||||
Create regular user account for your bot. You need this later in your script.
|
```bash
|
||||||
Make sure you have this information right now:
|
pip install git+https://molodetz.nl/retoor/snekbot.git
|
||||||
- bot username
|
```
|
||||||
- bot password
|
|
||||||
- bot url (wss://your-snek-instance.com/rpc.ws)
|
|
||||||
|
|
||||||
#### Create a file
|
### π€ Bot Creation Wizard
|
||||||
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.
|
|
||||||
|
|
||||||
```python
|
```python
|
||||||
import asyncio
|
import asyncio
|
||||||
|
|
||||||
from snekbot.bot import Bot
|
from snekbot.bot import Bot
|
||||||
|
|
||||||
|
class CoolSnekBot(Bot):
|
||||||
class ExampleBot(Bot):
|
|
||||||
|
|
||||||
async def on_join(self, channel_uid):
|
async def on_join(self, channel_uid):
|
||||||
await super().on_join(channel_uid)
|
|
||||||
print(f"I joined!")
|
|
||||||
await self.send_message(
|
await self.send_message(
|
||||||
channel_uid,
|
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):
|
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()
|
message = message.lower()
|
||||||
result = None
|
|
||||||
if "hello" in message:
|
if "hello" in message:
|
||||||
result = f"Hi @{sender_nick}"
|
await self.send_message(channel_uid, f"Hi there, {sender_nick}! π")
|
||||||
elif "bye" in message:
|
elif "bye" in message:
|
||||||
result = f"Bye @{sender_nick}"
|
await self.send_message(channel_uid, f"Catch you later, {sender_nick}! π€")
|
||||||
|
|
||||||
if result:
|
# Launch your bot into the wild!
|
||||||
await self.send_message(channel_uid, result)
|
bot = CoolSnekBot(
|
||||||
|
url="wss://your-snek-instance.com/rpc.ws",
|
||||||
|
username="your_awesome_bot",
|
||||||
bot = ExampleBot(
|
password="super_secret_password"
|
||||||
url="ws://snek.molodetz.nl/rpc.ws", username="example", password="example"
|
|
||||||
)
|
)
|
||||||
asyncio.run(bot.run())
|
asyncio.run(bot.run())
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Run the bot
|
### π Run Your Bot
|
||||||
Make sure you have (still) activated your virtual env.
|
|
||||||
```bash
|
```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
|
### Event Handlers You Can Override
|
||||||
Add `import logging` and `logging.BasicConfig(level=logging.DEBUG)`.
|
- `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
|
### π‘ Pro Tips
|
||||||
The `ExampleBot` class inherits from a base `Bot` class and implements several event handlers:
|
- Add `logging.basicConfig(level=logging.DEBUG)` for detailed logs
|
||||||
- `on_join`: Sends a welcome message when the bot joins a channel.
|
- The bot automatically reconnects if connection drops
|
||||||
- `on_leave`: Sends a goodbye message when the bot leaves.
|
- Customize to your heart's content!
|
||||||
- `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.
|
|
||||||
|
|
||||||
|
### Contributing
|
||||||
|
Got cool ideas? PRs are welcome! π€
|
||||||
|
|
||||||
|
### License
|
||||||
|
MIT - Go wild, have fun! π
|
||||||
|
|
||||||
|
|||||||
Loadingβ¦
Reference in New Issue
Block a user