mab/README.md

🤖 mab

mab (MAtrix Bot) is a very simple Python package that can be used to develop very simple Matrix bots. It does not aim to be the best library out there, but it aims to be convenient and usable for relatively serious projects.

✨ Features

The library supports the following features:

• Completely asyncio based
• Filter-based callback system
• Downloading and transparently decrypting files
• Sending files
• Sending images
• Sending videos with automatic thumbnail generation (requires ffmpeg)

📦 Installation

Use apt to install required system packages and pip to install the package. You may need to use root privileges to use apt. It's highly recommended you use venv or another Python virtual environment. Here are the commands to install the latest version of the library:

apt install libmagic1-dev libolm-dev
python -m pip install git+https://git.tyukalov.su/nikita/mab@v0.6.1

libmagic1-dev is needed for automatic file MIME type detection, libolm-dev is needed for E2EE to work.

Please inspect examples/image_bot.py, examples/echo_bot.py or open examples/ directory to find usage examples. Examples require that you set MATRIX_HOMESERVER and MATRIX_USERNAME environment variables. Examples create session_storage directory in working directory.

🚀 Usage

If you use mab, your application will most likely be using callbacks to react to user actions. mab uses filter-based callback system to avoid exposing raw nio-matrix event objects.

This is the workflow you will most likely follow:

1. Define the callback as async function that take 1 argument of type EventContext. For example, this callback would print the caption of the message:

   from mab import *
   
   async def on_media_with_body(ctx: EventContext):
       """To be called when a message with image/video and caption is received."""
       print(ctx[CTX_BODY])
   

2. Define the conditions your callback must be called on. For example, you may want your callback to be called when the sender is not the bot and the message contains textual body and (the message is an image or the message is a video).
3. Define the conditions as filters. Most of them are pretty straightforward. For example, if you want to use the conditions from above:

   from mab import *
   
   filters = (
       ~SenderIsBotFilter()
       & MessageTypeFilter([MessageType.IMAGE, MessageType.VIDEO])
       & BodyExistsFilter()
   )
   

4. Add the callback to your MatrixBot instance. For example, if you would have used everything from above, then your code would look something like this:

   from mab import *
   
   # let's assume you create your MatrixBot as `bot` variable here
   
   async def on_media_with_body(ctx: EventContext):
       """To be called when a message with image/video and caption is received."""
       print(ctx[CTX_BODY])
   
   filters = (
       ~SenderIsBotFilter()
       & MessageTypeFilter([MessageType.IMAGE, MessageType.VIDEO])
       & BodyExistsFilter()
   )
   bot.add_callback(filters, on_media_with_body)
   
   ...
   

Filters support bitwise operators to implement complex matching logic. Some filters set context variables which can be accessed by context[CTX_KEY_NAME]-like syntax. Possible variables are defined in this file. Filters are implemented in files of this directory.

🏷️ Versioning

Releases are tagged in this repository using the vX.Y.Z format. If the commit is not tagged, it must be treated as versionless and should not be used for your application.

• X (Major): Breaking architectiral changes or complete rewrites. Existing code will break. Note that 0.Y.Z versions are considered very unstable, the API may change at any time and some features do not work as expected.
• Y (Minor): Breaking API changes, feature removals, or behavioral modifications. Existing code will likely break.
• Z (Patch): Backward-compatible feature additions, bug fixes, or internal changes. Existing code will not break.

🛠️ Development

Here's the list of commands you should execute to get started with development (including cloning the repository and installing required packages). Please note that your workflow may use something other than venv.

apt install libmagic1-dev libolm-dev
git clone https://git.tyukalov.su/nikita/mab
cd mab
python3 -m venv .venv
. .venv/bin/activate
pip install -e .