matrix-python 0.1.2a0__tar.gz → 1.0.0__tar.gz

matrix_python-1.0.0/.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.0/.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.0/.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.0/.github/dependabot.yml

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

matrix_python-1.0.0/.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.0/.github/workflows/CODEOWNERS

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

matrix_python-1.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,99 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '24 17 * * 4'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: python
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

matrix_python-1.0.0/.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-0.1.2a0 → matrix_python-1.0.0}/.github/workflows/publish.yml

@@ -13,6 +13,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-python@v5
         with:
@@ -41,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
@@ -50,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.0/.github/workflows/scorecard.yml

@@ -0,0 +1,52 @@
+name: Scorecard supply-chain security
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: '16 0 * * 4'
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+      contents: read
+      actions: read
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        with:
+          egress-policy: audit
+
+      - name: "Checkout code"
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@05b42c624433fc40578a4040d5cf5e36ddca8cde # v2.4.2
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@3599b3baa15b485a2e49ef411a7a4bb2452e7f93 # v3.29.5
+        with:
+          sarif_file: results.sarif

matrix_python-1.0.0/.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-0.1.2a0 → matrix_python-1.0.0}/.gitignore

@@ -165,7 +165,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # Ruff stuff:
 .ruff_cache/
@@ -175,4 +175,6 @@ cython_debug/
 
 .DS_Store
 
-.vscode
+.vscode
+matrix/_version.py
+site/

matrix_python-1.0.0/.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-0.1.2a0 → matrix_python-1.0.0}/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.0/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.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: matrix-python
+Version: 1.0.0
+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.25.2
+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.0; extra == "dev"
+Requires-Dist: types-PyYAML==6.0.12.20260518; 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.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>
+
+<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).