CONTRIBUTING.md

Contributing

Hi there! Thanks for your interest in contributing to asyncio-mqtt.

Setting up an environment

Clone the asyncio-mqtt repository.

Inside the repository, create a virtual environment:

python3 -m venv .venv

Activate the virtual environment:

source ./env/bin/activate

Upgrade pip:

pip install --upgrade pip

Install the development dependencies:

pip install -e .[tests,lint,format,docs]

Install pre-commit so that your code is formatted and checked when you are doing a commit:

pip install pre-commit
pre-commit install

Visual Studio Code

If you are using VSCode, these are the settings to activate on save:

• black to format.
• mypy to lint.
• Install the charliermarsh.ruff extension to lint, sort imports, and auto-fix lint errors (ruff is a fast equivalent to flake8)

{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  "python.formatting.provider": "black",
  "python.linting.mypyEnabled": true
}

Testing

To test the code use pytest:

pytest

To get the full test coverage report of asyncio-mqtt, run the following command:

pytest --cov=src --cov=tests --cov-report=html

You can see the coverage report in htmlcov/index.html.

Building the documentation

The documentation uses Sphinx. The source files are located in the docs folder. You can build it by running ./scripts/docs or ./scripts/docs --no-reload if you don't want to have the documentation rebuilt automatically when you change a file.

Committing

After running git commit, pre-commit will check the committed code. This check can be passed, skipped or failed.

If the check failed, it is possible that pre-commit auto-fixed the code, so you only need to re-stage and re-commit. If it did not auto-fix the code, you will need to do so manually.

pre-commit will only check the code that is staged, the unstaged code will be stashed during the checks.

Making a Pull Request

The branch to contribute is main. You can create a draft pull request as long as your contribution is not ready. Please also update the CHANGELOG.md with the changes that your pull request makes!