-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Matrix.py is a lightweight and intuitive Python library for building bots on the Matrix protocol. It provides a clean, decorator-based API similar to popular event-driven frameworks, allowing developers to focus on behavior rather than boilerplate.
- Minimal setup, easy to extend
- Event-driven API using async/await
- Clean command registration
- Automatic event handler registration
- Built on matrix-nio
Here’s a minimal example to get your bot running. For a more detailed guide, see the Introduction
Install Matrix.py:
pip install matrix-python
Create a config.yaml:
USERNAME: "@yourbot:matrix.org"
PASSWORD: "your_password"from matrix import Bot, Context, Config
bot = Bot(config="config.yaml")React to all messages in rooms:
@bot.event
async def on_message(room, event):
print(f"[{room.room_id}] {event.sender}: {event.body}")This will log every message to the console.
Commands are triggered by messages starting with your prefix (default "!"):
# Respond to !ping
@bot.command()
async def ping(ctx: Context):
await ctx.send("Pong!")
# Respond to !say <text>
@bot.command()
async def say(ctx: Context, *, text: str):
await ctx.send(text)- Commands automatically parse arguments from messages.
- The command name defaults to the function name but can be customized.
bot.run()- Now your bot will:
- Log all messages
- Reply to
!pingwithPong! - Echo messages with
!say <text>
Here's a list of resources that might be useful when working with matrix.py:
We any contributions, whether it's fixing bugs, suggesting features, or improving the docs, every bit helps:
- Submit an issue
- Open a pull request
- Or hop into our Matrix or Discord community and say hi!
If you intend to contribute, please read the CONTRIBUTING.md first. Additionally, every contributor is expected to follow the code of conduct.