Newer
Older
<div align="center"><img src="docs/source/logo.svg" width="300"/></div>
# mwclient
[![Build status][build-status-img]](https://travis-ci.org/mwclient/mwclient)
[![Test coverage][test-coverage-img]](https://coveralls.io/r/mwclient/mwclient)
[![Code health][code-health-img]](https://landscape.io/github/mwclient/mwclient/master)
[![Latest version][latest-version-img]](https://pypi.python.org/pypi/mwclient)
[![MIT license][mit-license-img]](http://opensource.org/licenses/MIT)
[![Documentation status][documentation-status-img]](http://mwclient.readthedocs.io/en/latest/)
[![Issue statistics][issue-statistics-img]](http://isitmaintained.com/project/tldr-pages/tldr)
[![Gitter chat][gitter-chat-img]](https://gitter.im/mwclient/mwclient)
[build-status-img]: https://img.shields.io/travis/mwclient/mwclient.svg
[test-coverage-img]: https://img.shields.io/coveralls/mwclient/mwclient.svg
[code-health-img]: https://landscape.io/github/mwclient/mwclient/master/landscape.svg?style=flat
[latest-version-img]: https://img.shields.io/pypi/v/mwclient.svg
[mit-license-img]: https://img.shields.io/github/license/mwclient/mwclient.svg
[documentation-status-img]: https://readthedocs.org/projects/mwclient/badge/?version=master
[issue-statistics-img]: http://isitmaintained.com/badge/resolution/tldr-pages/tldr.svg
[gitter-chat-img]: https://img.shields.io/gitter/room/mwclient/mwclient.svg
mwclient is a lightweight Python client library to the
[MediaWiki API](https://mediawiki.org/wiki/API)
which provides access to most API functionality.
It works with Python 2.7 as well as 3.4 and above,
and supports MediaWiki 1.16 and above.
For functions not available in the current MediaWiki,
a `MediaWikiVersionError` is raised.
The current stable
[version 0.9.3](https://github.com/mwclient/mwclient/archive/v0.9.3.zip)
is [available through PyPI](https://pypi.python.org/pypi/mwclient):
```
$ pip install mwclient
```
The current [development version](https://github.com/mwclient/mwclient)
can be installed from GitHub:
```
$ pip install git+git://github.com/mwclient/mwclient.git
```
Please see the [changelog
document](https://github.com/mwclient/mwclient/blob/master/CHANGELOG.md)
for a list of changes.
Up-to-date documentation is hosted [at Read the Docs](http://mwclient.readthedocs.io/en/latest/).
It includes a user guide to get started using mwclient, a reference guide,
implementation and development notes.
There is also some documentation on the [GitHub wiki](https://github.com/mwclient/mwclient/wiki)
that hasn't been ported yet.
If you want to help, you're welcome!
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
## Contributing
mwclient ships with a test suite based on [pytest](https://pytest.org).
Only a small part of mwclient is currently tested,
but hopefully coverage will improve in the future.
The easiest way to run the tests is:
```
$ python setup.py test
```
This will make an in-place build
and download test dependencies locally if needed.
To make tests run faster, you can use pip to do an
["editable" install](https://pip.readthedocs.org/en/latest/reference/pip_install.html#editable-installs):
```
$ pip install pytest pytest-pep8 responses
$ pip install -e .
$ py.test
```
To run tests with different Python versions in isolated virtualenvs,
you can use [Tox](https://testrun.org/tox/latest/):
```
$ pip install tox
$ tox
```
*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](https://mwclient.readthedocs.io/)
after each commit.
To build the documentation locally for testing, do:
```
$ cd docs
$ make html
```
When writing docstrings, try to adhere to the
[Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).