docs: add .gitignore, LICENSE, Makefile, README tutorial, example bot, pyproject.toml, and core snekbot modules

2025-02-01 14:58:18 +00:00
commit 6654901f37
15 changed files with 441 additions and 0 deletions
@@ -0,0 +1,89 @@
+# Snekbot API
+
+This is the Snekbot API. This document describes how to create a bot responding to "hey", "hello", "bye" and "@username-of-bot".
+
+## 5 minute tutorial
+
+Literally.
+
+### 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.
+
+For Debian (Ubuntu): `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 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)
+
+#### Create a file 
+Open a file ending with the `.py` extension and pase this content.
+
+```python
+
+import asyncio 
+from snekbot.bot import Bot
+
+
+class ExampleBot(Bot):
+
+    async def on_join(self, data):
+        print(f"I joined f{data.channel_uid}!")
+
+    async def on_leave(self, data):
+        print(f"I left f{data.channel_uid}!")
+
+    async def on_ping(self, data):
+        print(f"Ping from f{data.user_nick}")
+        await self.send_message(
+            data.channel_uid,
+            "I should respond with Bong according to BordedDev. So here, bong!",
+        )
+
+    async def on_own_message(self, data):
+        print(f"Received my own message: {data.message}")
+
+    async def on_mention(self, data):
+        message = data.message[len(self.username) + 2 :]
+        print(f"Mention from f{data.user_nick}: {message}")
+
+        result = f'Hey {data.user_nick}, Thanks for mentioning me "{message}".'
+        await self.send_message(data.channel_uid, result)
+
+    async def on_message(self, data):
+        print(f"Message from f{data.user_nick}: {data.message}")
+        
+        message = data.message.lower()
+        result = None
+        
+        if "hey" in message or "hello" in message:
+            result = f"Hi {data.user_nick}"
+        elif "bye" in message:
+            result = f"Bye {data.user_nick}"
+
+        if result:
+            await self.send_message(data.channel_uid, result)
+
+
+bot = ExampleBot(username="Your username", password="Your password",url="wss://your-snek-instance.com/rpc.ws")
+asyncio.run(bot.run())
+```
+
+#### Run the bot
+Make sure you have (still) activated your virtual env.
+```bash
+python bot.py
+```
+If you get the error 'python not found' or 'aiohttp not found', run `source .venv/bin/activate` again and run `python bot.py` again.