matrix-python 1.0.0b0__tar.gz → 1.0.1__tar.gz

matrix_python-1.0.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: PenguinBoi12
+type: Bug
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

matrix_python-1.0.1/.github/ISSUE_TEMPLATE/feature--good-first.md

@@ -0,0 +1,29 @@
+---
+name: 'Feature: Good First'
+about: 'This template is for good first issues '
+title: ''
+labels: good first issue
+assignees: ''
+type: Feature
+
+---
+
+Explain clearly what we want to add and why it's useful to add it. Give context when necessary.
+
+### Proposed API
+This is a proposed API. It does not necessarily mean it's the final API but it's a good place to start.
+
+```python
+Some code here
+```
+
+**Example**
+```python
+An example of usage of the feature
+```
+
+### Before opening a PR
+- Write unit tests
+- Run `mypy matrix/`
+- Run `pytest tests/`
+- Run `black .`

matrix_python-1.0.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+type: Feature
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

matrix_python-1.0.1/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"

matrix_python-1.0.1/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Description
+Brief description of what this PR does and why.
+
+### Type of Change
+- [ ] Feature
+- [ ] Refactor
+- [ ] Bug fix
+- [ ] Documentation
+- [ ] Other: ___
+
+### Pre-merge Checklist
+- [ ] Run tests: `pytest`
+- [ ] Run type check: `mypy`
+- [ ] Run formatting: `black .

matrix_python-1.0.1/.github/workflows/CODEOWNERS

@@ -0,0 +1 @@
+* @PenguinBoi12

{matrix_python-1.0.0b0 → matrix_python-1.0.1}/.github/workflows/codeql.yml

@@ -96,4 +96,4 @@ jobs:
     - name: Perform CodeQL Analysis
       uses: github/codeql-action/analyze@v4
       with:
-        category: "/language:${{matrix.language}}"
+        category: "/language:${{matrix.language}}"

matrix_python-1.0.1/.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Deploy Docs
+
+on:
+  release:
+    types: [ published ]
+
+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: cd docs && mkdocs build
+
+      - 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.0.0b0 → matrix_python-1.0.1}/.github/workflows/publish.yml

@@ -43,7 +43,7 @@ jobs:
     environment:
       name: release
       url: https://pypi.org/project/matrix-python/${{ github.event.release.tag_name }}
-    
+
     steps:
       - name: Retrieve release distributions
         uses: actions/download-artifact@v4
@@ -52,4 +52,4 @@ jobs:
           path: dist/
 
       - name: Publish release distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v1

{matrix_python-1.0.0b0 → matrix_python-1.0.1}/.github/workflows/scorecard.yml

@@ -49,4 +49,4 @@ jobs:
       - name: "Upload to code-scanning"
         uses: github/codeql-action/upload-sarif@3599b3baa15b485a2e49ef411a7a4bb2452e7f93 # v3.29.5
         with:
-          sarif_file: results.sarif
+          sarif_file: results.sarif

matrix_python-1.0.1/.github/workflows/tests.yml

@@ -0,0 +1,44 @@
+name: Tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+      - name: Lint with Black
+        id: black
+        continue-on-error: true
+        run: |
+          black --check matrix/ tests/ examples/
+      - name: Check typing with mypy
+        id: mypy
+        continue-on-error: true
+        run: |
+          mypy matrix
+      - name: Test with pytest
+        id: pytest
+        continue-on-error: true
+        run: |
+          pytest -v --cov=matrix --cov-report=term-missing --cov-fail-under=90
+      - name: All checks succeeded
+        if: steps.black.outcome == 'failure' || steps.mypy.outcome == 'failure' || steps.pytest.outcome == 'failure'
+        run: exit 1

{matrix_python-1.0.0b0 → matrix_python-1.0.1}/.gitignore

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

matrix_python-1.0.1/.pre-commit-config.yaml

@@ -0,0 +1,44 @@
+default_language_version:
+  python: python3
+
+default_stages: [pre-commit]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        stages: [pre-commit]
+      - id: check-toml
+        stages: [pre-commit]
+      - id: check-yaml
+        exclude: ^docs/mkdocs\.yml$
+        stages: [pre-commit]
+      - id: end-of-file-fixer
+        stages: [pre-commit]
+      - id: trailing-whitespace
+        stages: [pre-commit]
+
+  - repo: local
+    hooks:
+      - id: black
+        name: black
+        entry: python -m black
+        language: system
+        stages: [pre-commit]
+        types_or: [python, pyi]
+
+      - id: mypy
+        name: mypy
+        entry: python -m mypy matrix
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+        types_or: [python, pyi]
+
+      - id: pytest
+        name: pytest
+        entry: python -m pytest
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]

{matrix_python-1.0.0b0 → matrix_python-1.0.1}/CONTRIBUTING.md

@@ -2,7 +2,7 @@
 Thank you for your interest in contributing to the matrix.py! As an open source project, many kinds of contributions are welcome.
 
 ## How can you contribute?
-You can contribute to this project in the follwing ways
+You can contribute to this project in the following ways
 
 - Report Bugs
 - Add new features
@@ -12,9 +12,27 @@ You can contribute to this project in the follwing ways
 **Warning:** Non-trivial pull requests must have an [issue](https://github.com/Code-Society-Lab/matrixpy/issues) proposing the changes.
 
 ## Setup
-1. Clone the Textual repository
-2. Create a virtual enviroment
-3. Install the dependencies
+1. Clone the matrix.py repository
+2. Create and activate a virtual environment
+3. Install the development dependencies and enable the Git hooks.
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+```
+
+
+After installation, the Git hooks run automatically before each commit to check formatting, typing, and tests.
+The hooks include running:
+- black
+- mypy
+- pytest
+
+Run the full hook suite manually with:
+
+```bash
+pre-commit run --all-files
+```
 
 ## Guidelines
 Read any issue instructions carefully. Feel free to ask for clarification if any details are missing.
@@ -22,8 +40,8 @@ Read any issue instructions carefully. Feel free to ask for clarification if any
 Add docstrings to all of your code (functions, methods, classes, ...). The codebase should have enough examples for you to copy from.
 
 Write tests for your code.
-    If you are fixing a bug, make sure to add regression tests that link to the original issue.
-    If you are implementing new features, make sure to add tests
+- If you are fixing a bug, add a regression test that references the original issue.
+- If you are implementing a new feature, add tests covering the new functionality.
 
 ## Before opening a PR
 

matrix_python-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Code Society Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

matrix_python-1.0.1/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: matrix-python
+Version: 1.0.1
+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>
+License: The MIT License (MIT)
+        
+        Copyright (c) 2025 Code Society Lab
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in
+        all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+        THE SOFTWARE.
+        
+Project-URL: Homepage, https://codesociety.xyz
+Project-URL: Source, https://github.com/Code-Society-Lab/matrixpy
+Project-URL: Issues, https://github.com/Code-Society-Lab/matrixpy/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: matrix-nio==0.26.0
+Requires-Dist: logger
+Requires-Dist: PyYAML==6.0.3
+Requires-Dist: markdown==3.10.2
+Requires-Dist: APScheduler==3.11.3
+Requires-Dist: envyaml==1.10.211231
+Provides-Extra: dev
+Requires-Dist: pytest==9.1.1; extra == "dev"
+Requires-Dist: pytest-cov==7.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
+Requires-Dist: black==26.5.1; extra == "dev"
+Requires-Dist: mypy==2.1.0; extra == "dev"
+Requires-Dist: pre-commit==4.6.1; extra == "dev"
+Requires-Dist: types-PyYAML==6.0.12.20260724; extra == "dev"
+Requires-Dist: types-Markdown==3.10.2.20260518; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: mkdocs==1.6.1; extra == "doc"
+Requires-Dist: mkdocs-material==9.7.7; extra == "doc"
+Requires-Dist: mkdocstrings[python]==1.0.6; extra == "doc"
+
+<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.codesociety.xyz/guides/introduction/)
+[<img src="https://img.shields.io/badge/Reference-555555?style=for-the-badge" />](https://matrixpy.codesociety.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)
+[![PyPI](https://img.shields.io/pypi/v/matrix-python)](https://pypi.org/project/matrix-python/)
+[![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.0.1/README.md

@@ -0,0 +1,100 @@
+<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.codesociety.xyz/guides/introduction/)
+[<img src="https://img.shields.io/badge/Reference-555555?style=for-the-badge" />](https://matrixpy.codesociety.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)
+[![PyPI](https://img.shields.io/pypi/v/matrix-python)](https://pypi.org/project/matrix-python/)
+[![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.0.1/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.0.1/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.0.1/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.