class mwclient.client.Site(host, path='/w/', ext='.php', pool=None, retry_timeout=30, max_retries=25, wait_callback=<function <lambda>>, clients_useragent=None, max_lag=3, compress=True, force_login=True, do_init=True, httpauth=None, reqs=None, consumer_token=None, consumer_secret=None, access_token=None, access_secret=None, client_certificate=None, custom_headers=None)[source]

A MediaWiki site identified by its hostname.

>>> import mwclient
>>> site = mwclient.Site('')

Do not include the leading “http://”.

Mwclient assumes that the script path (where index.php and api.php are located) is ‘/w/’. If the site uses a different script path, you must specify this (path must end in a ‘/’).


>>> site = mwclient.Site('', path='/')
>>> site = mwclient.Site('', path='/apps/mediawiki/mwclient/')
allcategories(start=None, prefix=None, dir='ascending', limit=None, generator=True, end=None)[source]

Retrieve all categories on the wiki as a generator.

allimages(start=None, prefix=None, minsize=None, maxsize=None, limit=None, dir='ascending', sha1=None, sha1base36=None, generator=True, end=None)[source]

Retrieve all images on the wiki as a generator.

Retrieve a list of all links on the wiki as a generator.

allpages(start=None, prefix=None, namespace='0', filterredir='all', minsize=None, maxsize=None, prtype=None, prlevel=None, limit=None, dir='ascending', filterlanglinks='all', generator=True, end=None)[source]

Retrieve all pages on the wiki as a generator.

allusers(start=None, prefix=None, group=None, prop=None, limit=None, witheditsonly=False, activeusers=False, rights=None, end=None)[source]

Retrieve all users on the wiki as a generator.

api(action, http_method='POST', *args, **kwargs)[source]

Perform a generic API call and handle errors.

All arguments will be passed on.


To get coordinates from the GeoData MediaWiki extension at English Wikipedia:

>>> site = Site('')
>>> result = site.api('query', prop='coordinates', titles='Oslo|Copenhagen')
>>> for page in result['query']['pages'].values():
...     if 'coordinates' in page:
...         print '{} {} {}'.format(page['title'],
...             page['coordinates'][0]['lat'],
...             page['coordinates'][0]['lon'])
Oslo 59.95 10.75
Copenhagen 55.6761 12.5683
Returns:The raw response from the API call, as a dictionary.
ask(query, title=None)[source]

Ask a query against Semantic MediaWiki.

API doc:

Returns:Generator for retrieving all search results, with each answer as a dictionary. If the query is invalid, an APIError is raised. A valid query with zero results will not raise any error.


>>> query = "[[Category:my cat]]|[[Has name::a name]]|?Has property"
>>> for answer in site.ask(query):
>>>     for title, data in answer.items()
>>>         print(title)
>>>         print(data)
blocks(start=None, end=None, dir='older', ids=None, users=None, limit=None, prop='id|user|by|timestamp|expiry|reason|flags')[source]

Retrieve blocks as a generator.

Each block is a dictionary containing:

  • user: the username or IP address of the user
  • id: the ID of the block
  • timestamp: when the block was added
  • expiry: when the block runs out (infinity for indefinite blocks)
  • reason: the reason they are blocked
  • allowusertalk: key is present (empty string) if the user is allowed to edit their user talk page
  • by: the administrator who blocked the user
  • nocreate: key is present (empty string) if the user’s ability to create accounts has been disabled.
checkuserlog(user=None, target=None, limit=10, dir='older', start=None, end=None)[source]

Retrieve checkuserlog items as a generator.

email(user, text, subject, cc=False)[source]

Send email to a specified user on the wiki.

>>> try:
...'SomeUser', 'Some message', 'Some subject')
... except mwclient.errors.NoSpecifiedEmailError as e:
...     print 'The user does not accept email, or has not specified an email address.'
  • user (str) – User name of the recipient
  • text (str) – Body of the email
  • subject (str) – Subject of the email
  • cc (bool) – True to send a copy of the email to yourself (default is False)

Dictionary of the JSON response

  • NoSpecifiedEmailError (mwclient.errors.NoSpecifiedEmailError) – if recipient does not accept email
  • EmailError (mwclient.errors.EmailError) – on other errors
expandtemplates(text, title=None, generatexml=False)[source]

Takes wikitext (text) and expands templates.

API doc:

exturlusage(query, prop=None, protocol='http', namespace=None, limit=None)[source]

Retrieve the list of pages that link to a particular domain or URL, as a generator.

This API call mirrors the Special:LinkSearch function on-wiki.

Query can be a domain like ‘’. Wildcards can be used, e.g. ‘*’. Alternatively, a query can contain a full domain name and some or all of a URL: e.g. ‘**’

See <> for details.

The generator returns dictionaries containing three keys: - url: the URL linked to. - ns: namespace of the wiki page - pageid: the ID of the wiki page - title: the page title.

get(action, *args, **kwargs)[source]

Perform a generic API call using GET.

This is just a shorthand for calling api() with http_method=’GET’. All arguments will be passed on.

Returns:The raw response from the API call, as a dictionary.
logevents(type=None, prop=None, start=None, end=None, dir='older', user=None, title=None, limit=None, action=None)[source]

Retrieve logevents as a generator.

login(username=None, password=None, cookies=None, domain=None)[source]

Login to the wiki.

post(action, *args, **kwargs)[source]

Perform a generic API call using POST.

This is just a shorthand for calling api() with http_method=’POST’. All arguments will be passed on.

Returns:The raw response from the API call, as a dictionary.
random(namespace, limit=20)[source]

Retrieve a generator of random pages from a particular namespace.

limit specifies the number of random articles retrieved. namespace is a namespace identifier integer.

Generator contains dictionary with namespace, page ID and title.

raw_api(action, http_method='POST', *args, **kwargs)[source]

Send a call to the API.

raw_call(script, data, files=None, retry_on_error=True, http_method='POST')[source]

Perform a generic request and return the raw text.

In the event of a network problem, or a HTTP response with status code 5XX, we’ll wait and retry the configured number of times before giving up if retry_on_error is True.

requests.exceptions.HTTPError is still raised directly for HTTP responses with status codes in the 4XX range, and invalid HTTP responses.

  • script (str) – Script name, usually ‘api’.
  • data (dict) – Post data
  • files (dict) – Files to upload
  • retry_on_error (bool) – Retry on connection error

The raw text response.

raw_index(action, http_method='POST', *args, **kwargs)[source]

Sends a call to index.php rather than the API.

recentchanges(start=None, end=None, dir='older', namespace=None, prop=None, show=None, limit=None, type=None, toponly=None)[source]

List recent changes to the wiki, à la Special:Recentchanges.

revisions(revids, prop='ids|timestamp|flags|comment|user', expandtemplates=False, diffto='prev')[source]

Get data about a list of revisions.

See also the Page.revisions() method.

API doc:

Example: Get revision text for two revisions:

>>> for revision in site.revisions([689697696, 689816909], prop='content'):
...     print revision['*']
  • revids (list) – A list of (max 50) revisions.
  • prop (str) – Which properties to get for each revision.
  • expandtemplates (bool) – Expand templates in rvprop=content output.
  • diffto (str) – Revision ID to diff each revision to. Use “prev”, “next” and “cur” for the previous, next and current revision respectively.

A list of revisions

search(search, namespace='0', what=None, redirects=False, limit=None)[source]

Perform a full text search.

API doc:


>>> for result in'prefix:Template:Citation/'):
...     print(result.get('title'))
  • search (str) – The query string
  • namespace (int) – The namespace to search (default: 0)
  • what (str) – Search scope: ‘text’ for fulltext, or ‘title’ for titles only. Depending on the search backend, both options may not be available. For instance CirrusSearch doesn’t support ‘title’, but instead provides an “intitle:” query string filter.
  • redirects (bool) – Include redirect pages in the search (option removed in MediaWiki 1.23).

Search results iterator

Return type:


upload(file=None, filename=None, description='', ignore=False, file_size=None, url=None, filekey=None, comment=None)[source]

Upload a file to the site.

Note that one of file, filekey and url must be specified, but not more than one. For normal uploads, you specify file.

  • file (str) – File object or stream to upload.
  • filename (str) – Destination filename, don’t include namespace prefix like ‘File:’
  • description (str) – Wikitext for the file description page.
  • ignore (bool) – True to upload despite any warnings.
  • file_size (int) – Deprecated in mwclient 0.7
  • url (str) – URL to fetch the file from.
  • filekey (str) – Key that identifies a previous upload that was stashed temporarily.
  • comment (str) – Upload comment. Also used as the initial page text for new files if description is not specified.


>>> client.upload(open('somefile', 'rb'), filename='somefile.jpg',
                  description='Some description')

JSON result from the API.

  • errors.InsufficientPermission
  • requests.exceptions.HTTPError
usercontributions(user, start=None, end=None, dir='older', namespace=None, prop=None, show=None, limit=None)[source]

List the contributions made by a given user to the wiki, à la Special:Contributions.

API doc:

users(users, prop='blockinfo|groups|editcount')[source]

Get information about a list of users.

API doc:

static version_tuple_from_generator(string, prefix='MediaWiki ')[source]

Return a version tuple from a MediaWiki Generator string.


“MediaWiki 1.5.1” → (1, 5, 1)

Parameters:prefix (str) – The expected prefix of the string
watchlist(allrev=False, start=None, end=None, namespace=None, dir='older', prop=None, show=None, limit=None)[source]

List the pages on the current user’s watchlist.

API doc: