Skip to main content

A basic bot for Matrix

Project description

python-matrixbot

A Python module meant to act as a base class for a Matrix bot.

Compatibility

Python 3.6+

Installation

pip install python-matrixbot

Usage

The MatrixBot class will connect to the Matrix server, start a listener on each joined room, and listen for room invites from other users. It also includes helper methods you can use to extend the functionality. It is built on the Matrix Python SDK which can be directly accessed via MatrixBot.client

from matrixbot import MatrixBot

# create a new bot
bot = MatrixBot(
    host="example.com",
    display_name="Example Bot",
    token=access_token,
    user_id="@bot:example.com"
)
# run forever
bot.start()

Get a list of joined rooms:

room_ids = bot.rooms.keys()
room_objects = bot.rooms.values()

Leave abandoned 1-on-1 rooms

for room in bot.rooms.values():
    bot.leave_if_empty(room)

Cache results from external API calls

To prevent abuse of commands that rely on external API calls, MatrixBot includes a very basic caching mechanism. Wrap all API calls in MatrixBot.fetch() to return cached results and automatically refresh stale data.

def get_url(url):
  return response.get(url)

result = bot.fetch(
    "cache_key", lambda: get_url("https://example.com"), timeout=900
)

By default the module uses an in-memory cache which is lost between restarts. To create a persistent cache provide the constructor with the path to a sqlite database:

bot = MatrixBot(
    ...
    cache_db="/path/to/sqlite_database"
)

Sub-classing

Create a subclass to extend and override default features

class MyBot(MatrixBot):
    # override `process_message()` to filter/parse/react to room events:
    def process_message(self, room, event):
        # say hello when a user joins the room
        if event["type"] == "m.room.member":
            if event["content"]["membership"] == "join":
                self.say(room, "Hello!", mention=event["sender"])

    # override `accept_invite()` to disable auto-join:
    def accept_invite(self, room_id):
        pass

bot = MyBot(...)

License

MIT

Maintainer

Brian Ó blacksam@gibberfish.org

Contributions welcome.

About Gibberfish

Gibberfish, Inc is a volunteer nonprofit that develops free tools to promote online privacy for activists and regular people alike. If you like this module and decide to use it in your project, please consider donating $1 to help keep us going. Thanks!

https://gibberfish.org/donate/

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
python_matrixbot-0.0.7-py3-none-any.whl (11.2 kB) Copy SHA256 hash SHA256 Wheel py3
python-matrixbot-0.0.7.tar.gz (8.7 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page