From ce93cee0f09799a6623417c470dc6cc32a7e0a64 Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 3 Jul 2026 19:51:32 -0700 Subject: [PATCH 1/4] add pre-commit configuration and update contributing guidelines --- .pre-commit-config.yaml | 67 +++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 17 +++++++++++ pyproject.toml | 3 +- 3 files changed, 86 insertions(+), 1 deletion(-) create mode 100644 .pre-commit-config.yaml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..c1e000e --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,67 @@ +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: python + additional_dependencies: + - black==26.5.1 + stages: [pre-commit] + types_or: [python, pyi] + + - id: mypy + name: mypy + entry: python -m mypy matrix tests + language: python + additional_dependencies: + - . + - matrix-nio==0.25.2 + - logger + - PyYAML==6.0.3 + - markdown==3.10.2 + - APScheduler==3.11.3 + - envyaml==1.10.211231 + - mypy==2.1.0 + - types-PyYAML==6.0.12.20260518 + - types-Markdown==3.10.2.20260518 + pass_filenames: false + stages: [pre-commit] + types_or: [python, pyi] + + - id: pytest + name: pytest + entry: python -m pytest + language: python + additional_dependencies: + - . + - matrix-nio==0.25.2 + - logger + - PyYAML==6.0.3 + - markdown==3.10.2 + - APScheduler==3.11.3 + - envyaml==1.10.211231 + - pytest==9.1.1 + - pytest-asyncio==1.4.0 + pass_filenames: false + stages: [pre-push] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4bff81a..d4d23b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,23 @@ You can contribute to this project in the follwing ways 2. Create a virtual enviroment 3. Install the dependencies +Install the development dependencies and enable the git hooks: + +```bash +pip install -e ".[dev]" +pre-commit install +pre-commit install --hook-type pre-push +``` + +After installation, the hooks run automatically when you commit or push. + +Run the full hook suite manually with: + +```bash +pre-commit run --all-files +pre-commit run --hook-stage pre-push --all-files +``` + ## Guidelines Read any issue instructions carefully. Feel free to ask for clarification if any details are missing. diff --git a/pyproject.toml b/pyproject.toml index 52d8fc9..7f86118 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,6 +31,7 @@ dev = [ "pytest-asyncio==1.4.0", "black==26.5.1", "mypy==2.1.0", + "pre-commit==4.6.0", "types-PyYAML==6.0.12.20260518", "types-Markdown==3.10.2.20260518", ] @@ -59,4 +60,4 @@ write_to = "matrix/_version.py" omit = [ "matrix/_version.py", "matrix/__init__.py", -] \ No newline at end of file +] From 9891b02cfd7e6262cae571cea891c1864882cc12 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 4 Jul 2026 16:02:33 -0700 Subject: [PATCH 2/4] update pre-commit hooks to use system language and remove additional dependencies --- .pre-commit-config.yaml | 33 +++++---------------------------- 1 file changed, 5 insertions(+), 28 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c1e000e..58ae1a9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -24,27 +24,14 @@ repos: - id: black name: black entry: python -m black - language: python - additional_dependencies: - - black==26.5.1 + language: system stages: [pre-commit] types_or: [python, pyi] - id: mypy name: mypy - entry: python -m mypy matrix tests - language: python - additional_dependencies: - - . - - matrix-nio==0.25.2 - - logger - - PyYAML==6.0.3 - - markdown==3.10.2 - - APScheduler==3.11.3 - - envyaml==1.10.211231 - - mypy==2.1.0 - - types-PyYAML==6.0.12.20260518 - - types-Markdown==3.10.2.20260518 + entry: python -m mypy matrix + language: system pass_filenames: false stages: [pre-commit] types_or: [python, pyi] @@ -52,16 +39,6 @@ repos: - id: pytest name: pytest entry: python -m pytest - language: python - additional_dependencies: - - . - - matrix-nio==0.25.2 - - logger - - PyYAML==6.0.3 - - markdown==3.10.2 - - APScheduler==3.11.3 - - envyaml==1.10.211231 - - pytest==9.1.1 - - pytest-asyncio==1.4.0 + language: system pass_filenames: false - stages: [pre-push] + stages: [pre-commit] From c0a6079a13b045646180173f3ebdc99c84a0832b Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 4 Jul 2026 16:13:29 -0700 Subject: [PATCH 3/4] updated contribution guideline and fix typo --- CONTRIBUTING.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4d23b7..ff53c82 100644 --- a/CONTRIBUTING.md +++ b/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,25 +12,26 @@ 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 - -Install the development dependencies and enable the git hooks: +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 -pre-commit install --hook-type pre-push ``` -After installation, the hooks run automatically when you commit or push. + +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 -pre-commit run --hook-stage pre-push --all-files ``` ## Guidelines @@ -39,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 From b53d5c0c9fbf614bbb1a49d5512bdab03b946cb0 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 4 Jul 2026 16:14:07 -0700 Subject: [PATCH 4/4] linter fix whitespace --- .github/workflows/codeql.yml | 2 +- .github/workflows/publish.yml | 4 ++-- .github/workflows/scorecard.yml | 2 +- .gitignore | 2 +- docs/docs/guides/commands.md | 8 ++++---- docs/docs/guides/error-handling.md | 2 +- docs/docs/guides/index.md | 2 +- docs/docs/guides/introduction.md | 4 ++-- docs/mkdocs.yml | 2 +- 9 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 217f696..83fcd56 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -96,4 +96,4 @@ jobs: - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v4 with: - category: "/language:${{matrix.language}}" \ No newline at end of file + category: "/language:${{matrix.language}}" diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index e98b6fc..e8b8558 100644 --- a/.github/workflows/publish.yml +++ b/.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 \ No newline at end of file + uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 55480e4..d35f48d 100644 --- a/.github/workflows/scorecard.yml +++ b/.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 \ No newline at end of file + sarif_file: results.sarif diff --git a/.gitignore b/.gitignore index 2265537..1e7bbf8 100644 --- a/.gitignore +++ b/.gitignore @@ -177,4 +177,4 @@ cython_debug/ .vscode matrix/_version.py -site/ \ No newline at end of file +site/ diff --git a/docs/docs/guides/commands.md b/docs/docs/guides/commands.md index 45148fb..90378cc 100644 --- a/docs/docs/guides/commands.md +++ b/docs/docs/guides/commands.md @@ -42,7 +42,7 @@ Make your command clearer by adding a description: async def ping(ctx): await ctx.reply("Pong 🏓") ``` -This description shows up in the help command when users type !help ping. +This description shows up in the help command when users type !help ping. ### Customizing the Command Name Sometimes you want the command name to be different from the function name: @@ -67,14 +67,14 @@ As you saw, every command must have a ctx (context) parameter. The [`Context`](. async def whoami(ctx): # Who sent the command? sender = ctx.sender # "@alice:example.com" - + # What room are we in? room_name = ctx.room_name # "General Chat" room_id = ctx.room_id # "!abc123:example.com" - + # What was the message? message = ctx.body # "!whoami" - + # Send all this info back await ctx.reply(f"You are {sender} in {room_name} ({room_id}) and your message was {message}") ``` diff --git a/docs/docs/guides/error-handling.md b/docs/docs/guides/error-handling.md index 90dbda7..2640eaa 100644 --- a/docs/docs/guides/error-handling.md +++ b/docs/docs/guides/error-handling.md @@ -1,5 +1,5 @@ # Handling Errors -Errors happen! A user might provide invalid input, your API might fail, or someone might misuse a command. Let's make your bot handle these gracefully through error handlers. +Errors happen! A user might provide invalid input, your API might fail, or someone might misuse a command. Let's make your bot handle these gracefully through error handlers. Error handlers can handle any type of exception, built-in by Python, from matrix.py or any other libraries. See the [`errors`](../reference/errors.md) reference for the full list of built-in error types. diff --git a/docs/docs/guides/index.md b/docs/docs/guides/index.md index ee07edf..a0bad75 100644 --- a/docs/docs/guides/index.md +++ b/docs/docs/guides/index.md @@ -69,7 +69,7 @@ bot.start(config=Config( ``` - Now your bot will: - Log all messages -- Reply to `!ping` with `Pong!` +- Reply to `!ping` with `Pong!` - Echo messages with `!say ` # Resources diff --git a/docs/docs/guides/introduction.md b/docs/docs/guides/introduction.md index e969d11..6374784 100644 --- a/docs/docs/guides/introduction.md +++ b/docs/docs/guides/introduction.md @@ -32,7 +32,7 @@ Before installing Matrix.py, it's strongly recommended to create a virtual envir ```bash source venv/bin/activate ``` - + On Windows (PowerShell): ```bash venv\Scripts\Activate @@ -87,7 +87,7 @@ Matrix.py allows you to listen to these events using the `@bot.event` decorator. For example, to react whenever a message is sent: ```python from matrix import Bot, Context -from matrix.bot import MatrixRoom, RoomMessageText +from matrix.bot import MatrixRoom, RoomMessageText bot = Bot() diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index ee15897..580780c 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -120,4 +120,4 @@ nav: - Cooldowns: examples/cooldown.md - Error Handling: examples/error-handling.md - Extension: examples/extension.md - - Scheduler: examples/scheduler.md \ No newline at end of file + - Scheduler: examples/scheduler.md