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/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..58ae1a9 --- /dev/null +++ b/.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] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4bff81a..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,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 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 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 +]