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

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

Mwclient is a :ref:`MIT licensed <license>` client library to the `MediaWiki API`_
that should work well with both Wikimedia wikis and other wikis running
MediaWiki 1.16 or above. It works with Python 2.7 and 3.3+.

.. _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[u'Leipäjuusto']
    >>> page.text()
    u'{{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
-----------

    .. include:: ../../LICENSE.md

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

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

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