Site

class mwclient.client.Site(host, path='/w/', ext='.php', pool=None, retry_timeout=30, max_retries=25, wait_callback=<function Site.<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, scheme='https')[source]

A MediaWiki site identified by its hostname.

>>> import mwclient
>>> site = mwclient.Site('en.wikipedia.org')

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('vim.wikia.com', path='/')
>>> site = mwclient.Site('sourceforge.net', 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.

Example

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

>>> site = Site('en.wikipedia.org')
>>> 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: https://semantic-mediawiki.org/wiki/Ask_API

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.

Examples

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

Returns:
Generator yielding dicts, each dict 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.
Return type:mwclient.listings.List
checkuserlog(user=None, target=None, limit=10, dir='older', start=None, end=None)[source]

Retrieve checkuserlog items as a generator.

chunk_upload(file, filename, ignorewarnings, comment, text)[source]

Upload a file to the site in chunks.

This method is called by Site.upload if you are connecting to a newer MediaWiki installation, so it’s normally not necessary to call this method directly.

Parameters:
  • file (file-like object) – File object or stream to upload.
  • params (dict) – Dict containing upload parameters.
email(user, text, subject, cc=False)[source]

Send email to a specified user on the wiki.

>>> try:
...     site.email('SomeUser', 'Some message', 'Some subject')
... except mwclient.errors.NoSpecifiedEmail:
...     print('User does not accept email, or has no email address.')
Parameters:
  • 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)
Returns:

Dictionary of the JSON response

Raises:
  • NoSpecifiedEmail (mwclient.errors.NoSpecifiedEmail) – User doesn’t accept email
  • EmailError (mwclient.errors.EmailError) – Other email errors
expandtemplates(text, title=None, generatexml=False)[source]

Takes wikitext (text) and expands templates.

API doc: https://www.mediawiki.org/wiki/API:Expandtemplates

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 ‘bbc.co.uk’. Wildcards can be used, e.g. ‘*.bbc.co.uk’. Alternatively, a query can contain a full domain name and some or all of a URL: e.g. ‘*.wikipedia.org/wiki/*’

See <https://meta.wikimedia.org/wiki/Help:Linksearch> for details.

Returns:
Generator yielding dicts, each dict containing:
  • url: The URL linked to.
  • ns: Namespace of the wiki page
  • pageid: The ID of the wiki page
  • title: The page title.
Return type:mwclient.listings.List
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 using a username and password. The method returns nothing if the login was successful, but raises and error if it was not.

Parameters:
  • username (str) – MediaWiki username
  • password (str) – MediaWiki password
  • cookies (dict) – Custom cookies to include with the log-in request.
  • domain (str) – Sends domain name for authentication; used by some MediaWiki plug-ins like the ‘LDAP Authentication’ extension.
Raises:
  • LoginError (mwclient.errors.LoginError) – Login failed, the reason can be obtained from e.code and e.info (where e is the exception object) and will be one of the API:Login errors. The most common error code is “Failed”, indicating a wrong username or password.
  • MaximumRetriesExceeded – API call to log in failed and was retried until all retries were exhausted. This will not occur if the credentials are merely incorrect. See MaximumRetriesExceeded for possible reasons.
  • APIError – An API error occurred. Rare, usually indicates an internal server error.
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.

Parameters:
  • script (str) – Script name, usually ‘api’.
  • data (dict) – Post data
  • files (dict) – Files to upload
  • retry_on_error (bool) – Retry on connection error
  • http_method (str) – The HTTP method, defaults to ‘POST’
Returns:

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')[source]

Get data about a list of revisions.

See also the Page.revisions() method.

API doc: https://www.mediawiki.org/wiki/API:Revisions

Example: Get revision text for two revisions:

>>> for revision in site.revisions([689697696, 689816909], prop='content'):
...     print revision['*']
Parameters:
  • revids (list) – A list of (max 50) revisions.
  • prop (str) – Which properties to get for each revision.
Returns:

A list of revisions

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

Perform a full text search.

API doc: https://www.mediawiki.org/wiki/API:Search

Example

>>> for result in site.search('prefix:Template:Citation/'):
...     print(result.get('title'))
Parameters:
  • 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).
Returns:

Search results iterator

Return type:

mwclient.listings.List

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.

Parameters:
  • 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.

Example

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

JSON result from the API.

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

List the contributions made by a given user to the wiki.

API doc: https://www.mediawiki.org/wiki/API:Usercontribs

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

Get information about a list of users.

API doc: https://www.mediawiki.org/wiki/API:Users

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

Return a version tuple from a MediaWiki Generator string.

Example

“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: https://www.mediawiki.org/wiki/API:Watchlist