matrix-python 1.4.8a0__tar.gz → 1.4.10a0__tar.gz

matrix_python-1.4.10a0/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: pip install .[doc]
+
+      - name: Build docs
+        run: mkdocs build --config-file docs/mkdocs.yml
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{matrix_python-1.4.8a0 → matrix_python-1.4.10a0}/.gitignore

@@ -176,4 +176,5 @@ cython_debug/
 .DS_Store
 
 .vscode
-matrix/_version.py
+matrix/_version.py
+site/

{matrix_python-1.4.8a0/matrix_python.egg-info → matrix_python-1.4.10a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrix-python
-Version: 1.4.8a0
+Version: 1.4.10a0
 Summary: An easy-to-use Matrix bot framework designed for quick development and minimal setup
 Author: Simon Roy,  Chris Dedman Rollet 
 Maintainer-email: Code Society Lab <admin@codesociety.xyz>
@@ -40,57 +40,72 @@ Provides-Extra: dev
 Requires-Dist: pytest==9.0.3; extra == "dev"
 Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
 Requires-Dist: black==26.3.1; extra == "dev"
-Requires-Dist: mypy==1.20.0; extra == "dev"
+Requires-Dist: mypy==1.20.1; extra == "dev"
 Requires-Dist: types-PyYAML==6.0.12.20260408; extra == "dev"
 Requires-Dist: types-Markdown==3.10.2.20260408; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: mkdocs==1.6.1; extra == "doc"
+Requires-Dist: mkdocs-material==9.7.6; extra == "doc"
+Requires-Dist: mkdocstrings[python]==1.0.4; extra == "doc"
 
 <div align="center">
   <em>A simple, developer-friendly library to create powerful <a href="https://matrix.org">Matrix</a> bots.</em>
 </div>
 
-<img alt="image" src="https://github.com/user-attachments/assets/d9140a9e-27fa-44e4-a5ca-87ee7bbf868f" />
+<div align="center">
+  <img alt="matrix.py" src="https://github.com/user-attachments/assets/d9140a9e-27fa-44e4-a5ca-87ee7bbf868f" />
+</div>
+
+<div align="center">
 
-<hr />
+[<img src="https://img.shields.io/badge/Get%20Started-black?style=for-the-badge" />](https://matrixpy.code-society.xyz/guides/introduction/)
+[<img src="https://img.shields.io/badge/Reference-555555?style=for-the-badge" />](https://matrixpy.code-society.xyz/reference/bot/)
+
+</div>
+
+<div align="center">
 
-[![Static Badge](https://img.shields.io/badge/%F0%9F%93%9A-Documentation-%235c5c5c)](https://github.com/Code-Society-Lab/matrixpy/wiki)
 [![Join Discord](https://discordapp.com/api/guilds/823178343943897088/widget.png?style=shield)](https://discord.gg/code-society-823178343943897088)
-[![Join Matrix](https://img.shields.io/matrix/codesociety%3Amatrix.org?logo=matrix&label=%20&labelColor=%23202020&color=%23202020)](https://matrix.to/#/%23codesociety:matrix.org )
+[![Join Matrix](https://img.shields.io/matrix/codesociety%3Amatrix.org?logo=matrix&label=%20&labelColor=%23202020&color=%23202020)](https://matrix.to/#/%23codesociety:matrix.org)
 [![Tests](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/tests.yml/badge.svg)](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/tests.yml)
 [![CodeQL Advanced](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/codeql.yml/badge.svg)](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/codeql.yml)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Code-Society-Lab/matrixpy/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Code-Society-Lab/matrixpy)
 
-Matrix.py is a lightweight and intuitive Python library to build bots on
-the [Matrix protocol](https://matrix.org). It provides a clean,
-decorator-based API similar to popular event-driven frameworks, allowing
-developers to focus on behavior rather than boilerplate.
+</div>
 
-#### Key Features
+---
 
-- Minimal setup, easy to extend
-- Event-driven API using async/await
-- Clean command registration
-- Automatic event handler registration
-- Built on [matrix-nio](https://github.com/matrix-nio/matrix-nio)
+Matrix.py is a lightweight and intuitive Python library to build bots on the [Matrix protocol](https://matrix.org). It
+provides a clean, decorator-based API similar to popular event-driven frameworks, allowing developers to focus on
+behavior rather than boilerplate.
 
-# Quickstart
+- **Minimal setup** — install and have a working bot running in minutes
+- **Event-driven** — async/await API reacting to any Matrix room event
+- **Command system** — decorator-based commands with automatic argument parsing
+- **Extensions** — split your bot into modules as it grows
 
-**Requirements**
+## Quickstart
 
-- Python 3.10+
+**Requirements:** Python 3.10+
 
-```
+```bash
 pip install matrix-python
 ```
 
-If you plan on contributing to matrix.py, we recommend to install the development libraries:
+Using a virtual environment is strongly recommended:
 
-```
-pip install -e .[dev]
+```bash
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install matrix-python
 ```
 
-*Note*: It is recommended to use
-a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
-when installing python packages.
+Create a `config.yml`:
+
+```yaml
+USERNAME: "@yourbot:matrix.org"
+PASSWORD: "your_password"
+```
 
 ```python
 from matrix import Bot, Context
@@ -106,23 +121,29 @@ async def ping(ctx: Context):
 bot.start(config="config.yml")
 ```
 
-[Documentation](https://github.com/Code-Society-Lab/matrixpy/wiki) - [Examples](https://github.com/Code-Society-Lab/matrixpy/tree/main/examples)
+Send `!ping` in any room the bot is in, it will reply `Pong!`.
+
+## Where to go next
 
-# Contributing
+- [**Guides**](https://matrixpy.codesociety.xyz/guides/introduction/) — step-by-step tutorials covering commands,
+  events, checks, extensions, and more
+- [**Reference**](https://matrixpy.codesociety.xyz/reference/bot/) — complete API documentation for every class and
+  function
+- [**Examples**](https://matrixpy.codesociety.xyz/examples/) — ready-to-run example bots
+  demonstrating common patterns
 
-We welcome everyone to contribute!
+## Contributing
 
-Whether it's fixing bugs, suggesting features, or improving the docs - every bit helps.
+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 just hop into our [Matrix](https://matrix.to/#/%23codesociety:matrix.org)
-  or [Discord](https://discord.gg/code-society-823178343943897088) server and say hi!
+- [Submit an issue](https://github.com/Code-Society-Lab/matrixpy/issues)
+- [Open a pull request](https://github.com/Code-Society-Lab/matrixpy/blob/main/CONTRIBUTING.md)
+- Hop into our [Matrix](https://matrix.to/#/%23codesociety:matrix.org)
+  or [Discord](https://discord.gg/code-society-823178343943897088) and say hi!
 
-If you intend to contribute, please read the [CONTRIBUTING.md](./CONTRIBUTING.md) first. Additionally, **every
-contributor** is expected to follow the [code of conduct](./CODE_OF_CONDUCT.md).
+Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) and follow the [code of conduct](./CODE_OF_CONDUCT.md).
 
-# License
+## License
 
-This project is licensed under the terms
-of [MIT license](https://github.com/Code-Society-Lab/matrixpy/blob/main/LICENSE).
+Released under the [MIT License](https://github.com/Code-Society-Lab/matrixpy/blob/main/LICENSE).

matrix_python-1.4.10a0/README.md

@@ -0,0 +1,99 @@
+<div align="center">
+  <em>A simple, developer-friendly library to create powerful <a href="https://matrix.org">Matrix</a> bots.</em>
+</div>
+
+<div align="center">
+  <img alt="matrix.py" src="https://github.com/user-attachments/assets/d9140a9e-27fa-44e4-a5ca-87ee7bbf868f" />
+</div>
+
+<div align="center">
+
+[<img src="https://img.shields.io/badge/Get%20Started-black?style=for-the-badge" />](https://matrixpy.code-society.xyz/guides/introduction/)
+[<img src="https://img.shields.io/badge/Reference-555555?style=for-the-badge" />](https://matrixpy.code-society.xyz/reference/bot/)
+
+</div>
+
+<div align="center">
+
+[![Join Discord](https://discordapp.com/api/guilds/823178343943897088/widget.png?style=shield)](https://discord.gg/code-society-823178343943897088)
+[![Join Matrix](https://img.shields.io/matrix/codesociety%3Amatrix.org?logo=matrix&label=%20&labelColor=%23202020&color=%23202020)](https://matrix.to/#/%23codesociety:matrix.org)
+[![Tests](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/tests.yml/badge.svg)](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/tests.yml)
+[![CodeQL Advanced](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/codeql.yml/badge.svg)](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Code-Society-Lab/matrixpy/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Code-Society-Lab/matrixpy)
+
+</div>
+
+---
+
+Matrix.py is a lightweight and intuitive Python library to build bots on the [Matrix protocol](https://matrix.org). It
+provides a clean, decorator-based API similar to popular event-driven frameworks, allowing developers to focus on
+behavior rather than boilerplate.
+
+- **Minimal setup** — install and have a working bot running in minutes
+- **Event-driven** — async/await API reacting to any Matrix room event
+- **Command system** — decorator-based commands with automatic argument parsing
+- **Extensions** — split your bot into modules as it grows
+
+## Quickstart
+
+**Requirements:** Python 3.10+
+
+```bash
+pip install matrix-python
+```
+
+Using a virtual environment is strongly recommended:
+
+```bash
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install matrix-python
+```
+
+Create a `config.yml`:
+
+```yaml
+USERNAME: "@yourbot:matrix.org"
+PASSWORD: "your_password"
+```
+
+```python
+from matrix import Bot, Context
+
+bot = Bot()
+
+
+@bot.command("ping")
+async def ping(ctx: Context):
+    await ctx.reply("Pong!")
+
+
+bot.start(config="config.yml")
+```
+
+Send `!ping` in any room the bot is in, it will reply `Pong!`.
+
+## Where to go next
+
+- [**Guides**](https://matrixpy.codesociety.xyz/guides/introduction/) — step-by-step tutorials covering commands,
+  events, checks, extensions, and more
+- [**Reference**](https://matrixpy.codesociety.xyz/reference/bot/) — complete API documentation for every class and
+  function
+- [**Examples**](https://matrixpy.codesociety.xyz/examples/) — ready-to-run example bots
+  demonstrating common patterns
+
+## Contributing
+
+We welcome everyone to contribute! Whether it's fixing bugs, suggesting features, or improving the docs. Every bit
+helps.
+
+- [Submit an issue](https://github.com/Code-Society-Lab/matrixpy/issues)
+- [Open a pull request](https://github.com/Code-Society-Lab/matrixpy/blob/main/CONTRIBUTING.md)
+- Hop into our [Matrix](https://matrix.to/#/%23codesociety:matrix.org)
+  or [Discord](https://discord.gg/code-society-823178343943897088) and say hi!
+
+Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) and follow the [code of conduct](./CODE_OF_CONDUCT.md).
+
+## License
+
+Released under the [MIT License](https://github.com/Code-Society-Lab/matrixpy/blob/main/LICENSE).

matrix_python-1.4.10a0/docs/docs/examples/checks.md

@@ -0,0 +1,15 @@
+# Checks
+
+Shows how to restrict a command to a specific set of users using a [check](../reference/checks.md). The `!secret` command is only accessible to users in the `allowed_users` set — anyone else receives an "Access denied" reply.
+
+```python
+--8<-- "examples/checks.py"
+```
+
+Key points:
+
+- `@secret_command.check` decorates an async function that returns `True` (allow) or `False` (deny). Returning `False` raises a [`CheckError`](../reference/errors.md).
+- `@secret_command.error(CheckError)` handles the denial and sends a friendly reply instead of silently failing.
+- `ctx.sender` is the full Matrix ID of the user who sent the command (e.g. `@alice:matrix.org`).
+
+See the [Checks guide](../guides/checks.md) for built-in checks like `@is_owner` and how to compose multiple checks.

matrix_python-1.4.10a0/docs/docs/examples/cooldown.md

@@ -0,0 +1,14 @@
+# Cooldowns
+
+Demonstrates two ways to apply a rate limit to a command, and how to handle the [`CooldownError`](../reference/errors.md) when the limit is exceeded.
+
+```python
+--8<-- "examples/cooldown.py"
+```
+
+There are two ways to set a cooldown:
+
+- **`@cooldown(rate, period)` decorator** — applied before `@bot.command`. `rate=2, period=10` means 2 uses per 10 seconds per user.
+- **`cooldown=(rate, period)` argument** — passed directly to `@bot.command` for a more compact one-liner.
+
+Both produce a `CooldownError` when the limit is exceeded. The error object exposes `error.retry` — the number of seconds until the user can try again — which you can surface in the reply.

matrix_python-1.4.10a0/docs/docs/examples/error-handling.md

@@ -0,0 +1,17 @@
+# Error Handling
+
+Shows both per-command error handlers and a global error handler, covering argument validation, runtime errors, and unknown commands.
+
+```python
+--8<-- "examples/error_handling.py"
+```
+
+Three layers of error handling are demonstrated:
+
+- **Global handler** — `@bot.error(CommandNotFoundError)` catches any command the bot doesn't recognise, across the whole bot. No `ctx` is available here since no command was matched.
+- **Per-command handlers** — `@division.error(ZeroDivisionError)` and `@division.error(ValueError)` handle errors raised inside the `division` function itself.
+- **Argument handler** — `@division.error(MissingArgumentError)` fires when the user doesn't supply enough arguments.
+
+Handlers are matched by exception type. If no handler is registered for a raised exception, it propagates normally.
+
+See the [Error Handling guide](../guides/error-handling.md) for the full picture.

matrix_python-1.4.10a0/docs/docs/examples/extension.md

@@ -0,0 +1,26 @@
+# Extension
+
+Demonstrates how to split a bot into modules using [`Extension`](../reference/extension.md) and how to organise related commands into a [`Group`](../reference/group.md).
+
+```python
+--8<-- "examples/extension.py"
+```
+
+Key points:
+
+- `Extension("math")` creates a standalone module. It supports commands, groups, events, checks, and error handlers — everything `Bot` supports.
+- `@extension.group("math")` creates a command group. Sub-commands are registered with `@math_group.command()` and invoked as `!math add`, `!math subtract`, etc.
+- Per-command error handlers work the same as on `Bot`: `@divide.error(ZeroDivisionError)` handles division by zero inside the group.
+
+To load this extension in your bot:
+
+```python
+from matrix import Bot
+from math_extension import extension as math_extension
+
+bot = Bot()
+bot.load_extension(math_extension)
+bot.start(config="config.yaml")
+```
+
+See the [Bigger Bot guide](../guides/bigger-bot.md) for a full project layout using multiple extensions.

matrix_python-1.4.10a0/docs/docs/examples/index.md

@@ -0,0 +1,20 @@
+# Examples
+
+Ready-to-run bots demonstrating common patterns. Each example is a complete, working bot you can copy and adapt.
+
+All examples expect a `config.yaml` file in the same directory:
+
+```yaml
+USERNAME: "@yourbot:matrix.org"
+PASSWORD: "your_password"
+```
+
+| Example | What it shows |
+|---------|--------------|
+| [Ping Bot](ping.md) | Minimal bot with a single command |
+| [Reactions](reaction.md) | Listening to events and reacting to messages |
+| [Checks](checks.md) | Restricting commands to specific users |
+| [Cooldowns](cooldown.md) | Rate-limiting commands per user |
+| [Error Handling](error-handling.md) | Per-command and global error handlers |
+| [Extension](extension.md) | Splitting a bot into modules with command groups |
+| [Scheduler](scheduler.md) | Running tasks on a cron schedule |

matrix_python-1.4.10a0/docs/docs/examples/ping.md

@@ -0,0 +1,9 @@
+# Ping Bot
+
+The simplest possible bot — one command that replies to `!ping` with `Pong!`. Start here if you're new to matrix.py.
+
+```python
+--8<-- "examples/ping.py"
+```
+
+`ctx.reply()` sends a message back to the same room the command was received in. Swap `"Pong!"` for any string, including formatted text.

matrix_python-1.4.10a0/docs/docs/examples/reaction.md

@@ -0,0 +1,14 @@
+# Reactions
+
+Demonstrates event listeners and the [`Message.react()`](../reference/message.md) API. The bot watches for incoming messages and reactions, and responds with emoji reactions of its own.
+
+```python
+--8<-- "examples/reaction.py"
+```
+
+Two event handlers are registered here:
+
+- `on_message` — fires on every `RoomMessageText` event. It fetches the full message object and reacts based on the message body.
+- `on_react` — fires on every `ReactionEvent`. It fetches the original message that was reacted to and chains a follow-up reaction.
+
+`room.fetch_message()` returns a [`Message`](../reference/message.md) object. You can react with an emoji string or any short text.

matrix_python-1.4.10a0/docs/docs/examples/scheduler.md

@@ -0,0 +1,19 @@
+# Scheduler
+
+Shows how to run tasks on a cron schedule using `@bot.schedule`. Tasks run independently of commands — they fire at the specified time whether or not anyone sends a message.
+
+```python
+--8<-- "examples/scheduler.py"
+```
+
+`@bot.schedule` accepts a standard 5-field cron expression:
+
+| Expression | Meaning |
+|---|---|
+| `* * * * *` | Every minute |
+| `0 * * * *` | Every hour (on the hour) |
+| `0 9 * * 1-5` | 9 AM every weekday |
+
+The scheduled function receives no arguments. To send a message you need a [`Room`](../reference/room.md) object — get one with `bot.get_room(room_id)` before the bot starts, then call `room.send()` inside the task.
+
+See the [`Scheduler` reference](../reference/scheduler.md) for the full API.

matrix_python-1.4.10a0/docs/docs/guides/bigger-bot.md

@@ -0,0 +1,95 @@
+# Bigger Bot - Extension
+
+As your bot grows, keeping everything in a single file becomes harder to manage. That's where [`Extension`](../reference/extension.md) comes in, it lets you split your code into separate modules.
+
+Here's an example file structure for a larger bot:
+```
+.
+├─ bot
+│  ├─ __init__.py
+│  ├─ helpers.py
+│  ├─ my_bot.py
+│  └─ extensions
+│     ├─ __init__.py
+│     ├─ dev.py
+│     ├─ moderation.py
+│     └─ weather.py
+```
+
+The `bot` package contains everything related to your bot, with `my_bot.py` as its entry point. It's responsible for importing and registering all extensions. This is just one way to structure your project, extensions are flexible enough to fit whatever organization works best for you.
+
+## What is an `Extension`?
+
+An `Extension` is a mechanism that lets you split your bot's functionality across multiple modules. Extensions support everything a [`Bot`](../reference/bot.md) supports, including:
+
+- Event handlers
+- Error handlers
+- Commands
+- Groups
+- Checks
+- Cron tasks
+
+...and more.
+
+## How to Create an Extension
+
+Below is a basic definition of a `moderation` extension. It registers two commands, `ban` and `kick`, and an event handler for `on_member_ban`:
+
+```python
+from nio import RoomMemberEvent
+from matrix import Extension, Context
+from bot.helpers import is_admin
+
+extension = Extension("moderation")
+
+
+@is_admin
+@extension.command(description="Ban a member")
+async def ban(ctx: Context, username: str) -> None:
+    ...
+
+
+@is_admin
+@extension.command(description="Kick a member")
+async def kick(ctx: Context, username: str) -> None:
+    ...
+
+
+@extension.event
+def on_member_ban(event: RoomMemberEvent) -> None:
+    # Triggered when a user is banned
+    ...
+```
+
+## How to Register Extensions
+
+To use an extension, import it and pass it to `bot.load_extension()`:
+
+```python
+from matrix import Bot, Context
+from bot.extensions.moderation import extension as moderation_extension
+from bot.extensions.weather import extension as weather_extension
+from bot.extensions.dev import extension as dev_extension
+
+bot = Bot()
+
+
+@bot.command(description="Respond with 'Pong!'")
+async def ping(ctx: Context):
+    await ctx.reply("Pong!")
+
+
+bot.load_extension(moderation_extension)
+bot.load_extension(weather_extension)
+
+# Load the dev extension only in development environments
+if in_dev:
+    bot.load_extension(dev_extension)
+
+
+bot.start(config="config.yml")
+```
+
+Your bot now has three extensions registered: `moderation`, `weather`, and `dev` (the last one only in development).
+
+You can also unload an extension using `bot.unload_extension()`.

matrix_python-1.4.10a0/docs/docs/guides/checks.md

@@ -0,0 +1,114 @@
+# What is a Check?
+A check is a function that runs _before_ your command. It returns:
+- `True` - Allow the command to run
+- `False` - Block the command and raise [`CheckError`](../reference/errors.md)
+
+See also the [`checks`](../reference/checks.md) reference for built-in check decorators.
+
+# Add a Check
+Let's create an admin-only command:
+```python
+@bot.command()
+async def restricted(ctx):
+    await ctx.reply("You passed all checks!")
+
+
+@restricted.check
+async def is_admin(ctx):
+    admins = ["@alice:example.com", "@bob:example.com"]
+    return ctx.sender in admins
+```
+
+# Multiple Checks
+You can add multiple checks to one command. ALL checks must pass:
+
+```python
+@bot.command()
+async def restricted(ctx):
+    await ctx.reply("You passed all checks!")
+
+@restricted.check
+async def check_one(ctx):
+    # Must be from a specific room
+    allowed_rooms = ["!room1:example.com", "!room2:example.com"]
+    return ctx.room_id in allowed_rooms
+
+@restricted.check
+async def check_two(ctx):
+    # Must not be banned
+    banned = ["@troublemaker:example.com"]
+    return ctx.sender not in banned
+```
+
+Both checks must return `True` for the command to run.
+
+# Global Checks (Bot-Level)
+You can apply a check to _all_ commands with `@bot.check`:
+```python
+@bot.check
+async def not_banned(ctx):
+    """No banned users can run ANY commands"""
+    banned_users = ["@spammer:example.com", "@troll:example.com"]
+    return ctx.sender not in banned_users
+```
+Now this check runs before _every_ command on your bot.
+
+# What is a Cooldown?
+A cooldown prevents users from running a command too frequently. It's like a check, but specifically for rate limiting. When exceeded it raises a [`CooldownError`](../reference/errors.md).
+
+### Adding a Cooldown
+```python
+@bot.command(
+    description="Searches for something",
+    cooldown=(3, 60.0)  # 3 calls per 60 seconds
+)
+async def search(ctx, query: str):
+    # Simulate expensive operation
+    await ctx.reply(f"Searching for: {query}")
+```
+
+**Cooldown format:** `(rate, period)`
+- `rate` (int): Number of times the command can be called
+- `period` (float): Time window in seconds
+
+**Example interpretations:**
+- `(1, 10.0)` - Once every 10 seconds
+- `(5, 60.0)` - 5 times per minute
+- `(10, 3600.0)` - 10 times per hour
+
+
+### Setting Cooldowns Programmatically
+```python
+@bot.command()
+async def limited(ctx):
+    await ctx.reply("This command is rate-limited")
+
+# Set cooldown after command creation
+limited.set_cooldown(rate=2, period=30.0)  # 2 times per 30 seconds
+```
+
+### Handling Cooldown Errors
+When a user hits the cooldown limit, you can tell them how long to wait:
+
+```python
+from matrix.errors import CooldownError
+
+@bot.error(CooldownError)
+async def handle_cooldown(error):
+    # error.retry tells you how many seconds until they can retry
+    wait_time = int(error.retry)
+    # You can send a message here if you have access to context
+    print(f"Cooldown hit! Wait {wait_time} seconds")
+```
+
+
+# Hooks
+```python
+@command.before_invoke
+async def before(ctx):
+    # Runs before command
+
+@command.after_invoke
+async def after(ctx):
+    # Runs after command succeeds
+```