Simple-Matrix-Bot-Lib
(Version 1.5.x)
simplematrixbotlib is a Python 3 library for quickly building Matrix bots. It uses matrix-nio as its Matrix client library.
View on Github or View on PyPi or View docs on readthedocs.io
Installation
To use it, simplematrixbotlib can be either installed from pip or downloaded from github.
Installation from pip:
python -m pip install simplematrixbotlib
Download from github:
git clone --branch master https://github.com/KrazyKirby99999/simple-matrix-bot-lib.git
Example Usage
import simplematrixbotlib as botlib
import os
creds = botlib.Creds("https://home.server", "user", "pass")
bot = botlib.Bot(creds)
prefix = '!'
async def echo(room, message):
"""
Example function that "echoes" arguements.
Usage:
example_user- !echo say something
echo_bot- say something
"""
match = botlib.MessageMatch(room, message, bot)
if match.not_from_this_bot() and match.prefix(prefix) and match.command("echo"):
await bot.api.send_text_message(room.room_id, match.args)
bot.add_message_listener(echo)
bot.run()
More examples can be found here.
Features
Complete:
-
Login to homeserver - bot automatically login upon the execution of bot.run()
import simplematrixbotlib as botlib creds = botlib.Creds("home.server", "user", "pass") bot = botlib.Bot(creds) bot.run() #Logs in during the execution of this line
-
Join room on invite - bot automatically join rooms that the bot is invited to upon execution of bot.run(), or upon invite if the bot is running
-
Send message - bot can send messages in response to other messages, and can also run other code in response to messages as well as filter the messages that the bot responds to
import simplematrixbotlib as botlib creds = botlib.Creds("https://home.server", "user", "pass") bot = botlib.Bot(creds) async def say_something_to_a_message_not_from_bot(room, message): #Must be an "async" function with (room, message) arguments if not message.sender == bot.async_client.user_id: #Optional, prevents the bot from reacting to its own messages await bot.api.send_text_message(room.room_id, "something") #Send a message containing "something" to room bot.add_message_listener(say_something_to_a_message_not_from_bot) #Listen for messages, can have as many message listeners as needed, each added using bot.add_message_listener bot.run()
-
Execute action based on criteria - "match filters" can be used to specify which messages for the bot to respond to
import simplematrixbotlib as botlib import os creds = botlib.Creds("https://home.server", "user", "pass") bot = botlib.Bot(creds) prefix = '!' #Create prefix for commands async def echo(room, message): """ Example function that "echoes" arguements. Usage: example_user- !echo say something echo_bot- say something """ match = botlib.MessageMatch(room, message, bot) #Create an object of the botlib.MessageMatch class if match.not_from_this_bot() and match.prefix(prefix) and match.command("echo"): #Add match filters await bot.api.send_text_message(room.room_id, match.args)#Execute action bot.add_message_listener(echo) bot.run()
-
Preserve sessions - Sessions are now preserved between logins. The access token and device id are now saved in sessions.txt, unless specified otherwise.
import simplematrixbotlib as botlib import os creds = botlib.Creds("https://home.server", "user", "pass", None) #Disable preserved sessions bot = botlib.Bot(creds) prefix = '!' async def echo(room, message): """ Example function that "echoes" arguements. Usage: example_user- !echo say something echo_bot- say something """ match = botlib.MessageMatch(room, message, bot) if match.not_from_this_bot() and match.prefix(prefix) and match.command("echo"): await bot.api.send_text_message(room.room_id, match.args) bot.add_message_listener(echo) bot.run()
-
Add choice of actions to execute at bot login - Execute action after logging in
import simplematrixbotlib as botlib import os creds = botlib.Creds("https://home.server", "random_bot", "pass") bot = botlib.Bot(creds) prefix = '!' async def hello(room_id): #Must be an "async" function with a (room_id) argument """ Example function that says "hello" when the bot is started. Usage: (start random_bot) random_bot - hello """ message = "hello" await bot.api.send_text_message(room_id, message) #Example of sending a message bot.add_startup_action(hello) #Add "hello" action to action to execute at login bot.run()
In Progress:
Planned:
Dependencies
Python:
External:
1 maintainer
Metadata
1 maintainer
Release files for simplematrixbotlib 1.5.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| simplematrixbotlib-1.5.1.tar.gz | 8.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| simplematrixbotlib-1.5.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 17.0 kB
Release files / simplematrixbotlib-1.5.1.tar.gz
| Download URL | simplematrixbotlib-1.5.1.tar.gz |
|---|---|
| Size | 8.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ccdfba61834027fc136f0d38ab79b827cdbf53f174b9f4712528c3371d9ae2d6
|
|
BLAKE2b-256 checksum How to use checksums |
1ec72cebe1815ac9ae65348c12c829fbee0f00cfafc4e861223fd2a857fa8fec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.1 importlib_metadata/4.5.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.9.5
|
Release files / simplematrixbotlib-1.5.1-py3-none-any.whl
| Download URL | simplematrixbotlib-1.5.1-py3-none-any.whl |
|---|---|
| Size | 8.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
08c3bfa3fc42b9c144cda14e8eb445e7c6ccb867db8bc30324aa8eb8fbd1593e
|
|
BLAKE2b-256 checksum How to use checksums |
3629545969eb57c5fee53abc768ac7cfb9dcbe7ac204663246409f435b33830b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.1 importlib_metadata/4.5.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.9.5
|
