Home

Welcome to the matrix.py wiki!

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.

Key Features

• Minimal setup, easy to extend
• Event-driven API using async/await
• Clean command registration
• Automatic event handler registration
• Built on matrix-nio

Getting Started

Requirements

• Python 3.10+

pip install git+ssh://[email protected]:Code-Society-Lab/matrixpy.git

Note: It is recommended to use a virtual environment when installing python packages.

from matrix import Bot, Context

bot = Bot(username="@gracehopper:matrix.org", password="grace1234")


@bot.command("ping")
async def ping(ctx: Context):
    print(f"{ctx.sender} invoked {ctx.body} in room {ctx.room_name}.")
    await ctx.send("Pong!")


bot.start()

Warning

Bots does not support encrypted rooms yet.

Resources

Here's a list of resources that might be useful when working with matrix.py:

• Python's Doc
• matrix-nio
• Matrix Protocol

Contributing

We welcome everyone to contribute!

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.