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)[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 ‘/’). Examples:

>>> site = mwclient.Site('', path='/')
>>> site = mwclient.Site('', path='/apps/mediawiki/mwclient/')
allcategories(start=None, prefix=None, dir='ascending', limit=None, generator=True)[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, prop='timestamp|url', generator=True)[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)[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)[source]

Retrieve all users on the wiki as a generator.

api(action, *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:

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]

Retrieves 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.

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.

random(namespace, limit=20)[source]

Retrieves a generator of random page 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, *args, **kwargs)[source]

Sends a call to the API.

raw_call(script, data, files=None, retry_on_error=True)[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, *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.

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]

Uploads a file to the site. Returns JSON result from the API. Can raise errors.InsufficientPermission and requests.exceptions.HTTPError.

: Parameters :
  • file : File object or stream to upload.

  • filename : Destination filename, don’t include namespace

    prefix like ‘File:’

  • description : Wikitext for the file description page.

  • ignore : True to upload despite any warnings.

  • file_size : Deprecated in mwclient 0.7

  • url : URL to fetch the file from.

  • filekey : Key that identifies a previous upload that was

    stashed temporarily.

  • comment : Upload comment. Also used as the initial page text

    for new files if description is not specified.

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


>>> client.upload(open('somefile', 'rb'), filename='somefile.jpg',
                  description='Some description')
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:

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: