Skip to main content

No project description provided

Project description

matrixbz

matrixbz is a library for quickly building Matrix bots. It uses matrix-nio as its Matrix client library.

Examples

XKCD Bot

import os
import pathlib
import requests
from lxml import html

import matrixbz
import matrixbz.response as response
import matrixbz.cache as cache

XKCD_PATH = pathlib.Path(__file__).parent.absolute()
CACHE_PATH = os.path.join(XKCD_PATH, 'responsecache')


@matrixbz.matrixbz_controller(bot_name='xkcdbot')
class XKCDBotController():

    AUTH = matrixbz.auth.PublicBot
    CACHE = cache.FileTextCache(CACHE_PATH)

    @cache.cache_result
    @matrixbz.matrixbz_method
    async def num(self, num, **kwargs):
        page_url = f'https://xkcd.com/{num}/'
        img_url = self._get_img_url(page_url)
        return response.Image(img_url)

    def _get_img_url(self, url):
        res = requests.get(url)
        tree = html.fromstring(res.text)
        img_url = tree.xpath('//div[@id="comic"]/img')[0].get('src')
        return f'https:{img_url}'

creds = {
    'homeserver': 'https://matrix.MYSERVER.com',
    'user': '@bot:MYSERVER.com',
    'password': 'bot_password'
}

bot = XKCDBotController.create_matrix_bot(creds)
bot.run()

Accepts all invites and responds to all users. Fetches XKCD image with:

    !xkcdbot num <xkcd_comic_number>

Images are cached in local folder.

Dice Bot

import random
import re

import matrixbz
import matrixbz.response as response
import matrixbz.cache as cache

@matrixbz.matrixbz_controller(bot_name='dicebot')
class DiceBotController():

    AUTH = matrixbz.auth.PublicBot

    @matrixbz.matrixbz_method
    async def roll(self, dstring, **kwargs):
        regex = re.compile('^([0-9]+)d([0-9]+)$')
        match = re.search(regex, dstring)
        num_dice = int(match.group(1))
        sides = int(match.group(2))
        res = []
        for d in range(num_dice):
            res.append(random.randint(1,sides))
        return response.Notice(f'rolling {dstring}: {res}')

creds = {
    'homeserver': 'https://matrix.MYSERVER.com',
    'user': '@bot:MYSERVER.com',
    'password': 'bot_password'
}

bot = DiceBotController.create_matrix_bot(creds)
bot.run()

Accepts all invites and responds to all users. Produces dice rolls in <N>d<S> format with:

!dicebot roll <number_of_dice>d<number_of_sides>

Decorators

matrixbz_controller

Requires specifying a bot_name - bots are invoked by writing !<bot_name> <method> in chat. Marks a python class as a bot controller. Adds create_matrix_bot class method that takes in creds and creates a bot. The bot's run starts the bot and blocks while the bot is running.

creds

creds is a dictionary with homeserver, user, and password credentials for a bot.

matrixbz_method

Marks a function as a bot method. Can be invoked with !<bot_name> <function_name>

cache_result

A matrixbz_method marked with this will have its result cached. If the exact invocation of the command has been called before, bot will return the result without calling the function again.

matrixbz_msg_handler

A function marked with this will be invoked upon processing all non-command messages

matrixbz_startup_method

A function marked with this will execute one time when the bot's run is invoked.

Auth

A matrix bot controller can specify it's invite acceptance and command invocation authorization by setting AUTH.

BlockAll

This is the default if AUTH is not specified. Will not accept any invites and will not respond to any commands.

PublicBot

The bot will accept all invites and respond to all commands.

UserWhitelist

The bot will only accept invites from and respond to commands from users specified in USER_WHITELIST list on the controller class.

Response

Text

TODO

Notice

TODO

Html

TODO

Image

TODO

Cache

NoCache

Default. No cacheing.

InMemoryTextCache

Stores cached command results in memory.

FileTextCache

Stores cached command results on disk.

Project details


Download files

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

Source Distribution

matrixbz-0.0.2.tar.gz (7.9 kB view details)

Uploaded Source

File details

Details for the file matrixbz-0.0.2.tar.gz.

File metadata

  • Download URL: matrixbz-0.0.2.tar.gz
  • Upload date:
  • Size: 7.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.3

File hashes

Hashes for matrixbz-0.0.2.tar.gz
Algorithm Hash digest
SHA256 154a67b307e105725b7095b16968fdc632bbed1fdda69fa2cddca61c74288d4f
MD5 d65469c7655744663217e126cd1500d3
BLAKE2b-256 3eb8a495a2b216318bc99347af34a07588344f9588496f13921e4d3d64d23019

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page