Mwclient development is coordinated at Patches are very welcome. If there’s something you want to discuss first, we have a Gitter chatroom.

Development environment

If you plan to submit a pull request, you should first fork the mwclient repo on GitHub, then check out the original repository and configure your fork as a remote:

$ git clone
$ cd mwclient
$ git remote add fork

You can then use pip to do an “editable” install so that your edits will be immediately available for (both interactive and automated) testing:

$ pip install -e .

Create a new branch for your changes:

$ git checkout -b my-branch

Test suite

mwclient ships with a test suite based on pytest. While it’s far from complete, it can sometimes alert you if you break things.

The easiest way to run the tests is:

$ python test

This will make an in-place build and download test dependencies locally if needed. Tests will run faster, however, if you do an editable install and run pytest directly:

$ pip install pytest pytest-cov flake8 responses mock
$ pip install -e .
$ py.test

If you want to test with different Python versions in isolated virtualenvs, you can use Tox. A tox.ini file is included.

$ pip install tox
$ tox

If you would like to expand the test suite by adding more tests, please go ahead!

Updating/expanding the documentation

Documentation consists of both a manually compiled user guide (under docs/user) and a reference guide generated from the docstrings, using Sphinx autodoc with the napoleon extension. Documentation is built automatically on ReadTheDocs after each commit. To build the documentation locally for testing:

$ pip install Sphinx sphinx-rtd-theme
$ cd docs
$ make html

When writing docstrings, try to adhere to the Google style.

Making a pull request

Make sure to run tests before committing. When it comes to the commit message, there’s no specific requirements for the format, but try to explain your changes in a clear and concise manner.

If it’s been some time since you forked, please consider rebasing your branch on the main master branch to ease merging:

$ git rebase master

When it is ready, push your branch to your remote:

$ git push -u fork my-branch

Then you can open a pull request on GitHub. You should see a URL to do this when you push your branch.

Making a release

These instructions are for maintainers of the project. To cut a release, ensure is updated, then use bump-my-version:

$ pip install bump-my-version
$ bump-my-version bump major|minor|patch

Then check the commit looks correct and is tagged vX.Y.Z, and push. The .github/workflows/release.yml action will publish to PyPI.