Simple-Matrix-Bot-Lib

(Version 1.4.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()

In Progress:

Add more examples
Improve Documentation

Planned:

Add more match filters
Support for Encrypted Rooms
More

Dependencies

Python:

matrix-nio >= 0.18.2

External:

Python >= 3.7

Operating System
- OS Independent
Programming Language
- Python :: 3
Topic
- Communications :: Chat
- Internet

Metadata

Operating System
- OS Independent
Programming Language
- Python :: 3
Topic
- Communications :: Chat
- Internet

Release files for simplematrixbotlib 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for simplematrixbotlib 1.4.0
File	Size	Uploaded
simplematrixbotlib-1.4.0.tar.gz	8.3 kB	Jun 14, 2021	Details

Built distribution (wheel)

Table of built distributions (wheels) for simplematrixbotlib 1.4.0
File	Interpreter	ABI	Platform	Reset
simplematrixbotlib-1.4.0-py3-none-any.whl 8.1 kB Jun 14, 2021	Python 3	none	any	Details

Total release size: 16.4 kB

Release files / simplematrixbotlib-1.4.0.tar.gz

Download URL	simplematrixbotlib-1.4.0.tar.gz
Size	8.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`8dd9daae048cf14e1d0ea191d5cad649b96469ad18d3ed05654e7c7f5d2d7a9b`
BLAKE2b-256 checksum How to use checksums	`467a821a794c6cc1c82d650e764b1c45c63df3aae556a2b617143da25761ae17`
Upload date	Jun 14, 2021
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.4.0-py3-none-any.whl

Download URL	simplematrixbotlib-1.4.0-py3-none-any.whl
Size	8.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a7296193091ccf2284c6fd6d4ce65622abc1694340bf9d59e404d54ddec05c39`
BLAKE2b-256 checksum How to use checksums	`dac5ae7ddb8ee4312c69b2dd60f438e82f28a7f3ed398d05ab65a1397071dbd7`
Upload date	Jun 14, 2021
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`