mwclient: lightweight MediaWiki client
======================================

.. image:: logo.png
   :align: right
   :width: 30%

Mwclient is an :ref:`MIT licensed <license>` client library for the `MediaWiki API`_
that works well with both Wikimedia wikis and other wikis running
MediaWiki 1.21 or above. It is compatible with Python 3.6 and above.

.. _install:

Installation
------------

Installing Mwclient is simple with `pip <https://pip.pypa.io>`_, just run
this in your terminal:

.. code:: bash

    pip install mwclient

Quickstart
----------

.. code-block:: python

    >>> user_agent = 'MyCoolTool/0.2 (xyz@example.org)'
    >>> site = mwclient.Site('en.wikipedia.org', clients_useragent=user_agent)
    >>> page = site.pages['Leipäjuusto']
    >>> page.text()
    '{{Unreferenced|date=September 2009}}\n[[Image:Leip\xe4juusto cheese with cloudberry jam.jpg|thumb|Leip\xe4juusto with [[cloudberry]] jam]]\n\'\'\'Leip\xe4juusto\'\'\' (bread cheese) or \'\'juustoleip\xe4\'\', which is also known in English as \'\'\'Finnish squeaky cheese\'\'\', is a fresh [[cheese]] traditionally made from cow\'s [[beestings]], rich milk from a cow that has recently calved.'
    >>> [x for x in page.categories()]
    [<Category object 'Category:Finnish cheeses' for <Site object '('https', 'en.wikipedia.org')/w/'>>,
     <Category object 'Category:Articles lacking sources from September 2009' for <Site object '('https', 'en.wikipedia.org')/w/'>>,
     <Category object 'Category:Cow's-milk cheeses' for <Site object '('https', 'en.wikipedia.org')/w/'>>,
     <Category object 'Category:All articles lacking sources' for <Site object '('https', 'en.wikipedia.org')/w/'>>]


User guide
----------

This guide is intended as an introductory overview, and
explains how to make use of the most important features of
mwclient.

.. toctree::
   :maxdepth: 2

   user/index


Reference guide
---------------

If you are looking for information on a specific function, class or method,
this part of the documentation is for you. It's autogenerated
from the source code.

.. toctree::
   :maxdepth: 3

   reference/index


Development
-----------

Looking for information on contributing to mwclient development?

.. toctree::
   :maxdepth: 3

   development/index


.. _license:

MIT License
-----------

This project is licensed under the MIT License. The full text of the license
is reproduced below:

    .. literalinclude:: ../../LICENSE.md
        :language: text

Versioning
----------

Mwclient uses `Semantic Versioning 2.0.0 <http://semver.org>`_. Versions are
numbered ``MAJOR.MINOR.PATCH``. The version will be incremented based on the
following:

* `MAJOR` version is incremented when backwards incompatible changes are made.
* `MINOR` version is incremented when functionality is added in a backwards
  compatible manner.
* `PATCH` version is incremented when backwards compatible bug fixes are made.

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. _`MediaWiki API`: https://www.mediawiki.org/wiki/API