Site
¶
-
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('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)[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.
-
alllinks
(start=None, prefix=None, unique=False, prop='title', namespace='0', limit=None, generator=True)[source]¶ 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.
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.
-
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: ... site.email('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.'
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: - 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.
-
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 ‘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.
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.
-
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_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.
Parameters: - script (str) – Script name, usually ‘api’.
- data (dict) – Post data
- files (dict) – Files to upload
- retry_on_error (bool) – Retry on connection error
Returns: The raw text response.
-
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: 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.
- 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.
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
>>> 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]¶ 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.
Example:
>>> 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.
-