nikita
fa97e4b098
- Improved README.md - Added examples - Added `session_storage/` to .gitignore so that examples do not introduce leftover files after execution
61 lines
2.4 KiB
Markdown
61 lines
2.4 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**
|
|
- **Sending images**
|
|
- **Sending videos with automatic thumbnail generation (requires `ffmpeg`)**
|
|
|
|
## 🚀 Usage
|
|
|
|
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.4.0
|
|
```
|
|
|
|
`libmagic1-dev` is needed for automatic file MIME type detection, `libolm-dev`
|
|
is needed for E2EE to work.
|
|
|
|
Please inspect [`examples/shell_bot.py`](examples/shell_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.
|
|
|
|
## 🏷️ 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 .
|
|
``` |