# mab

**mab** *(MAtrix Bot)* is a **very** simple Python package that can be used to
develop **very** simple Matrix bots. I have decided to make something like this
because I wasn't satisfied by simplicity and usage of other libraries. So
this library does not aim to be "the best matrix bot library", it only aims to
be good enough for me.

## Features

The package supports the following features:
- **Filter-based callback system**
- **Images sending**
- **Videos sending with automatic thumbnail generation (requires `ffmpeg`)**

## Installation

Use `pip` to install this package:

```bash
python -m pip install git+https://git.tyukalov.su/nikita/mab@v0.3.0
```

You should specify package version you want to use, because `main` without tags
contain unstable code.

## Basic usage

This is the most simple bot you can create. It would respond to any message
that starts with `!test`, `!hello` or `!hi`.

```python
import asyncio
from mab import MatrixBot, MatrixBotConfig
from mab import TextCommandFilter
from mab.types import RoomEventData

async def on_valid_command(data: RoomEventData) -> None:
    # do not respond to ourselves
    if event.sender == data.bot.get_client().user_id:
        return
    text = f"Your message contains {len(data.event.body)} symbols"
    await data.bot.send_text_to_room(data.room, text)

async def main() -> None:
    # create and start the bot
    cfg = MatrixBotConfig(
        matrix_homeserver_url="matrix.domain.su",
        matrix_username_localpart="nagibator666",
        storage_directory=Path("storage_nagibator666")
    )
    bot = MatrixBot(matrix_bot_config)
    bot.add_callback(
        TextCommandFilter(["test", "hello", "hi"]),
        on_valid_command
    )
    await bot.start()
    # wait for Ctrl+C
    try:
        while True:
            await asyncio.sleep(1)
    except:
        pass
    # stop the bot
    await bot.stop()

if __name__ == "__main__":
    asyncio.run(main())
```