123 lines
4.6 KiB
Markdown
123 lines
4.6 KiB
Markdown
# 🤖 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:
|
|
|
|
```bash
|
|
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/image_bot.py),
|
|
[`examples/echo_bot.py`](examples/echo_bot.py) or open [`examples/`](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:
|
|
```python
|
|
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:
|
|
```python
|
|
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:
|
|
```python
|
|
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](src/mab/context.py). Filters are implemented in
|
|
[files of this directory](src/mab/filters/).
|
|
|
|
## 🏷️ 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`.
|
|
```bash
|
|
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 .
|
|
``` |