Metadata-Version: 2.1
Name: simplematrixbotlib
Version: 2.12.0
Summary: An easy to use bot library for the Matrix ecosystem written in Python.
Home-page: https://codeberg.org/imbev/simplematrixbotlib
License: MIT
Keywords: simple,matrix,bot,lib,simple-matrix-bot-lib
Author: imbev
Author-email: imbev@protonmail.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet
Requires-Dist: markdown (>=3.3,<4.0)
Requires-Dist: matrix-nio (>=0.24,<0.25)
Requires-Dist: pillow (>=10.0.1,<11.0.0)
Requires-Dist: python-cryptography-fernet-wrapper (>=1.0.4,<2.0.0)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Project-URL: Documentation, https://simple-matrix-bot-lib.readthedocs.io/en/latest/
Project-URL: Matrix Room, https://matrix.to/#/#simplematrixbotlib:matrix.org
Project-URL: Repository, https://codeberg.org/imbev/simplematrixbotlib
Description-Content-Type: text/markdown

# Simple-Matrix-Bot-Lib
(Version 2.12.0)

Simple-Matrix-Bot-Lib is a Python bot library for the Matrix ecosystem built on [matrix-nio](https://github.com/poljar/matrix-nio).

[View on Codeberg](https://codeberg.org/imbev/simplematrixbotlib) or [View on PyPi](https://pypi.org/project/simplematrixbotlib/) or
[View docs on readthedocs.io](https://simple-matrix-bot-lib.readthedocs.io/en/latest/)

Learn how you can contribute [here](CONTRIBUTING.md).

## Features

- [x] hands-off approach: get started with just 10 lines of code (see [example](#Example-Usage))
- [x] [end-to-end encryption support](https://simple-matrix-bot-lib.readthedocs.io/en/latest/manual.html#e2e-encryption)
- [x] limited [verification support](https://simple-matrix-bot-lib.readthedocs.io/en/latest/manual.html#verification) (device only)
- [x] easily [extensible config file](https://simple-matrix-bot-lib.readthedocs.io/en/latest/manual.html#extending-the-config-class-with-custom-settings)
- [x] [user access management](https://simple-matrix-bot-lib.readthedocs.io/en/latest/manual.html#allowlist)
- [x] access the matrix-nio library to use advanced features

## Installation

### simplematrixbotlib can be either installed from PyPi or downloaded from Codeberg.

Installation from PyPi:

```
python -m pip install simplematrixbotlib
```

[Read the docs](https://simple-matrix-bot-lib.readthedocs.io/en/latest/manual.html#e2e-encryption) to learn how to install E2E encryption support.

Download from Codeberg:

```
git clone --branch master https://codeberg.org/imbev/simplematrixbotlib.git
```



## Example Usage

```python
# echo.py
# Example:
# randomuser - "!echo example string"
# echo_bot - "example string"

import simplematrixbotlib as botlib

creds = botlib.Creds("https://home.server", "echo_bot", "pass")
bot = botlib.Bot(creds)
PREFIX = '!'

@bot.listener.on_message_event
async def echo(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX)

    if match.is_not_from_this_bot() and match.prefix() and match.command("echo"):

        await bot.api.send_text_message(
            room.room_id, " ".join(arg for arg in match.args())
            )

bot.run()
```

More information and examples can be found [here](https://simple-matrix-bot-lib.readthedocs.io/en/latest/).

