`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, connection_options=None, consumer_token=None, consumer_secret=None, access_token=None, access_secret=None, client_certificate=None, custom_headers=None, scheme='https', reqs=None)[source]¶

A MediaWiki site identified by its hostname.

Examples

>>> import mwclient
>>> wikipedia_site = mwclient.Site('en.wikipedia.org')
>>> wikia_site = mwclient.Site('vim.wikia.com', path='/')

Parameters:

host (str) – The hostname of a MediaWiki instance. Must not include a scheme (e.g. https://) - use the scheme argument instead.
path (str) – The instances script path (where the index.php and api.php scripts are located). Must contain a trailing slash (/). Defaults to /w/.
ext (str) – The file extension used by the MediaWiki API scripts. Defaults to .php.
pool (Session | None) – A preexisting Session to be used when executing API requests.
retry_timeout (int) – The number of seconds to sleep for each past retry of a failing API request. Defaults to 30.
max_retries (int) – The maximum number of retries to perform for failing API requests. Defaults to 25.
wait_callback (Callable[[Sleeper, int, Any | None], Any]) – A callback function to be executed for each failing API request.
clients_useragent (str | None) – A prefix to be added to the default mwclient user-agent. Should follow the pattern ‘{tool_name}/{tool_version} ({contact})’. Check the User-Agent policy for more information.
max_lag (int) – A maxlag parameter to be used in index.php calls. Consult the documentation for more information. Defaults to 3.
compress (bool) – Whether to request and accept gzip compressed API responses. Defaults to True.
force_login (bool) – Whether to require authentication when editing pages. Set to False to allow unauthenticated edits. Defaults to True.
do_init (bool) – Whether to automatically initialize the Site on initialization. When set to False, the Site must be initialized manually using the site_init() method. Defaults to True.
httpauth (Tuple[str | bytes, str | bytes] | AuthBase | List[str | bytes] | None) – An authentication method to be used when making API requests. This can be either an authentication object as provided by the requests library, or a tuple in the form {username, password}. Usernames and passwords provided as text strings are encoded as UTF-8. If dealing with a server that cannot handle UTF-8, please provide the username and password already encoded with the appropriate encoding.
connection_options (MutableMapping[str, Any] | None) – Additional arguments to be passed to the requests.Session.request() method when performing API calls. If the timeout key is empty, a default timeout of 30 seconds is added.
consumer_token (str | None) – OAuth1 consumer key for owner-only consumers.
consumer_secret (str | None) – OAuth1 consumer secret for owner-only consumers.
access_token (str | None) – OAuth1 access key for owner-only consumers.
access_secret (str | None) – OAuth1 access secret for owner-only consumers.
client_certificate (str | Tuple[str, str] | None) – A client certificate to be added to the session.
custom_headers (Mapping[str, str] | None) – A dictionary of custom headers to be added to all API requests.
scheme (str) – The URI scheme to use. This should be either http or https in most cases. Defaults to https.
reqs (MutableMapping[str, Any] | None)

Raises:

RuntimeError – The authentication passed to the httpauth parameter is invalid. You must pass either a tuple or a requests.auth.AuthBase object.
errors.OAuthAuthorizationError – The OAuth authorization is invalid.
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.

allcategories(start=None, prefix=None, dir='ascending', limit=None, generator=True, end=None, max_items=None, api_chunk_size=None)[source]¶

Retrieve all categories on the wiki as a generator.

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

Parameters:

start (str | None)
prefix (str | None)
dir (str)
limit (int | None)
generator (bool)
end (str | None)
max_items (int | None)
api_chunk_size (int | None)

Return type:

List

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

Retrieve all images on the wiki as a generator.

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

Parameters:

start (str | None)
prefix (str | None)
minsize (int | None)
maxsize (int | None)
limit (int | None)
dir (str)
sha1 (str | None)
sha1base36 (str | None)
generator (bool)
end (str | None)
max_items (int | None)
api_chunk_size (int | None)

Return type:

List

alllinks(start=None, prefix=None, unique=False, prop='title', namespace='0', limit=None, generator=True, end=None, max_items=None, api_chunk_size=None)[source]¶

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

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

Parameters:

start (str | None)
prefix (str | None)
unique (bool)
prop (str)
namespace (str | int)
limit (int | None)
generator (bool)
end (str | None)
max_items (int | None)
api_chunk_size (int | None)

Return type:

List

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, max_items=None, api_chunk_size=None)[source]¶

Retrieve all pages on the wiki as a generator.

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

Parameters:

start (str | None)
prefix (str | None)
namespace (str | int)
filterredir (str)
minsize (int | None)
maxsize (int | None)
prtype (str | None)
prlevel (str | None)
limit (int | None)
dir (str)
filterlanglinks (str)
generator (bool)
end (str | None)
max_items (int | None)
api_chunk_size (int | None)

Return type:

List

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

Retrieve all users on the wiki as a generator.

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

Parameters:

start (str | None)
prefix (str | None)
group (str | None)
prop (str | None)
limit (int | None)
witheditsonly (bool)
activeusers (bool)
rights (str | None)
end (str | None)
max_items (int | None)
api_chunk_size (int | None)

Return type:

List

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

Perform a generic API call and handle errors.

All arguments will be passed on.

Parameters:

action (str) – The MediaWiki API action to be performed.
http_method (str) – The HTTP method to use.
*args (Tuple[str, Any]) – Tupled key-value pairs to be passed to the api.php script as data. In most cases, it is preferable to pass these as keyword arguments instead. This can be useful when the parameter name is a reserved Python keyword (e.g. from).
**kwargs (Any) – Arguments to be passed to the API call.

Return type:

Dict[str, Any]

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:
...         title = page['title']
...         lat = page['coordinates'][0]['lat']
...         lon = page['coordinates'][0]['lon']
...         print(f'{title} {lat} {lon}')
Oslo 59.95 10.75
Copenhagen 55.6761 12.5683

Returns:

The raw response from the API call, as a dictionary.

Parameters:

action (str)
http_method (str)
args (Tuple[str, Any])
kwargs (Any)

Return type:

Dict[str, Any]

ask(query, title=None)[source]¶

Ask a query against Semantic MediaWiki.

API doc: https://semantic-mediawiki.org/wiki/Ask_API

Parameters:

query (str) – The SMW query to be executed.
title (str | None)

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.

Return type:

Iterable[Dict[str, Any]]

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)

Retrieve blocks as a generator.

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

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

Parameters:

start (str | None)
end (str | None)
dir (str)
ids (str | None)
users (str | None)
limit (int | None)
prop (str)
max_items (int | None)
api_chunk_size (int | None)

See also

When using the users filter to search for blocked users, only one block per given user will be returned. If you want to retrieve the entire block log for a specific user, you can use the Site.logevents() method with type=block and title='User:JohnDoe'.

checkuserlog(user=None, target=None, limit=None, dir='older', start=None, end=None, max_items=None, api_chunk_size=10)[source]¶

Retrieve checkuserlog items as a generator.

Parameters:

user (str | None)
target (str | None)
limit (int | None)
dir (str)
start (str | None)
end (str | None)
max_items (int | None)
api_chunk_size (int | None)

Return type:

NestedList

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 (BinaryIO) – File object or stream to upload.
filename (str) – Destination filename.
ignorewarnings (bool) – True to upload despite any warnings.
comment (str) – Upload comment.
text (str | None) – Initial page text for new files.

Return type:

Dict[str, Any]

clientlogin(cookies=None, **kwargs)[source]¶

Login to the wiki using a username and password. The method returns True if it’s a success or the returned response if it’s a multi-steps login process you started. In case of failure it raises some Errors.

Example for classic username / password clientlogin request:

>>> try:
...     site.clientlogin(username='myusername', password='secret')
... except mwclient.errors.LoginError as e:
...     print(f'Could not login to MediaWiki: {e}' )

Parameters:

cookies (Mapping[str, str] | CookieJar | None) – Custom cookies to include with the log-in request.
**kwargs (Any) –
Custom vars used for clientlogin as: - loginmergerequestfields - loginpreservestate - loginreturnurl, - logincontinue - logintoken - *: additional params depending on the available auth requests.

to log with classic username / password, you need to add username and password

See https://www.mediawiki.org/wiki/API:Login#Method_2._clientlogin

Returns:

True if login was successful, or the response if it’s a: multi-steps login process you started.

Return type:

bool | dict

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.

deletedrevisions(start=None, end=None, dir='older', namespace=None, limit=None, prop='user|comment', max_items=None, api_chunk_size=None)[source]¶

Retrieve deleted revisions as a generator.

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

Parameters:

start (str | None)
end (str | None)
dir (str)
namespace (int | None)
limit (int | None)
prop (str)
max_items (int | None)
api_chunk_size (int | None)

Return type:

List

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

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

Parameters:

user (str) – Username 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

Return type:

Dict[str, Any]

expandtemplates(text, title=None, generatexml=False)[source]¶

Takes wikitext (text) and expands templates.

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

Parameters:

text (str) – Wikitext to convert.
title (str | None) – Title of the page.
generatexml (bool) – Generate the XML parse tree. Defaults to False.

Returns:

If generatexml is False, returns the expanded wikitext as a string. If generatexml is True, returns a tuple of (expanded wikitext, XML parse tree).

Return type:

str | Tuple[str, str]

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

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

as a generator.

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

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

Parameters:

query (str)
prop (str | None)
protocol (str)
namespace (str | int | None)
limit (int | None)
max_items (int | None)
api_chunk_size (int | None)

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.

Parameters:

action (str) – The MediaWiki API action to be performed.
*args (Tuple[str, Any]) – Tupled key-value pairs to be passed to the api.php script as data. In most cases, it is preferable to pass these as keyword arguments instead. This can be useful when the parameter name is a reserved Python keyword (e.g. from).
**kwargs (Any) – Arguments to be passed to the API call.

Returns:

The raw response from the API call, as a dictionary.

Return type:

Dict[str, Any]

get_token(type, force=False, title=None)[source]¶

Request a MediaWiki access token of the given type.

Parameters:

type (str) – The type of token to request.
force (bool) – Force the request of a new token, even if a token of that type has already been cached.
title (str | None) – The page title for which to request a token. Only used for MediaWiki versions below 1.24.

Returns:

A MediaWiki token of the requested type.

Raises:

errors.APIError – A token of the given type could not be retrieved.

Return type:

str

handle_api_result(info, kwargs=None, sleeper=None)[source]¶

Checks the given API response, raising an appropriate exception or sleeping if necessary.

Parameters:

info (Mapping[str, Any]) – The API result.
kwargs (Mapping[str, Any] | None) – Additional arguments to be passed when raising an errors.APIError.
sleeper (Sleeper | None) – A Sleeper instance to use when sleeping.

Returns:

False if the given API response contains an exception, else True.

Return type:

bool

logevents(type=None, prop=None, start=None, end=None, dir='older', user=None, title=None, limit=None, action=None, max_items=None, api_chunk_size=None)[source]¶

Retrieve logevents as a generator.

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

Parameters:

type (str | None)
prop (str | None)
start (str | None)
end (str | None)
dir (str)
user (str | None)
title (str | None)
limit (int | None)
action (str | None)
max_items (int | None)
api_chunk_size (int | None)

Return type:

List

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

Login to the wiki using a username and bot password. The method returns nothing if the login was successful, but raises and error if it was not. If you use mediawiki >= 1.27 and try to login with normal account (not botpassword account), you should use clientlogin instead, because login action is deprecated since 1.27 with normal account and will stop working in the near future. See these pages to learn more:

https://www.mediawiki.org/wiki/API:Login and

https://www.mediawiki.org/wiki/Manual:Bot_passwords

Note: at least until v1.33.1, botpasswords accounts seem to not have: “userrights” permission. If you need to update user’s groups, this permission is required so you must use client login with a user who has userrights permission (a bureaucrat for eg.).

Parameters:

username (str | None) – MediaWiki username
password (str | None) – MediaWiki password
cookies (Mapping[str, str] | CookieJar | None) – Custom cookies to include with the log-in request.
domain (str | None) – 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.

Return type:

None

parse(text=None, title=None, page=None, prop=None, redirects=False, mobileformat=False)[source]¶

Parses the given content and returns parser output.

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

Parameters:

text (str | None) – Text to parse.
title (str | None) – Title of page the text belongs to.
page (str | None) – The name of a page to parse. Cannot be used together with text and title.
prop (str | None) – Which pieces of information to get. Multiple alues should be separated using the pipe (|) character.
redirects (bool) – Resolve the redirect, if the given page is a redirect. Defaults to False.
mobileformat (bool) – Return parse output in a format suitable for mobile devices. Defaults to False.

Returns:

The parse output as generated by MediaWiki.

Return type:

Any

patrol(rcid=None, revid=None, tags=None)[source]¶

Patrol a page or a revision. Either rcid or revid (but not both) must be given. The rcid and revid arguments may be obtained using the Site.recentchanges() function.

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

Parameters:

rcid (int | None) – The recentchanges ID to patrol.
revid (int | None) – The revision ID to patrol.
tags (str | None) – Change tags to apply to the entry in the patrol log. Multiple tags can be given, by separating them with the pipe (|) character.

Returns:

The API response as a dictionary containing:

rcid (int): The recentchanges id.
nsid (int): The namespace id.
title (str): The page title.

Return type:

Dict[str, Any]

Raises:

errors.APIError – The MediaWiki API returned an error.

Notes

autopatrol rights are required in order to use this function.
revid requires at least MediaWiki 1.22.
tags requires at least MediaWiki 1.27.

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.

Parameters:

action (str) – The MediaWiki API action to be performed.
*args (Tuple[str, Any]) – Tupled key-value pairs to be passed to the api.php script as data. In most cases, it is preferable to pass these as keyword arguments instead. This can be useful when the parameter name is a reserved Python keyword (e.g. from).
**kwargs (Any) – Arguments to be passed to the API call.

Returns:

The raw response from the API call, as a dictionary.

Return type:

Dict[str, Any]

random(namespace, limit=None, max_items=None, api_chunk_size=20)[source]¶

Retrieve a generator of random pages from a particular namespace.

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

max_items specifies the number of random articles retrieved. api_chunk_size and limit (deprecated) specify the API chunk size. namespace is a namespace identifier integer.

Generator contains dictionary with namespace, page ID and title.

Parameters:

namespace (str | int)
limit (int | None)
max_items (int | None)
api_chunk_size (int | None)

Return type:

List

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

Send a call to the API.

Parameters:

action (str) – The MediaWiki API action to perform.
http_method (str) – The HTTP method to use in the request.
retry_on_error (bool) – Whether to retry API call on connection errors.
*args (Tuple[str, Any]) – Tupled key-value pairs to be passed to the api.php script as data. In most cases, it is preferable to pass these as keyword arguments instead. This can be useful when the parameter name is a reserved Python keyword (e.g. from).
**kwargs (Any) – Arguments to be passed to the api.php script as data.

Returns:

The API response.

Raises:

errors.APIDisabledError – The MediaWiki API is disabled for this instance.
errors.InvalidResponse – The API response could not be decoded from JSON.
errors.MaximumRetriesExceeded – The API request failed and the maximum number of retries was exceeded.
requests.exceptions.HTTPError – Received an invalid HTTP response, or a status code in the 4xx range.
requests.exceptions.ConnectionError – Encountered an unexpected error while performing the API request.
requests.exceptions.Timeout – The API request timed out.

Return type:

Dict[str, Any]

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 an 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 (Mapping[str, Any]) – Post data
files (Mapping[str, BinaryIO | Tuple[str, BinaryIO]] | None) – 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.

Raises:

errors.MaximumRetriesExceeded – The API request failed and the maximum number of retries was exceeded.
requests.exceptions.HTTPError – Received an invalid HTTP response, or a status code in the 4xx range.
requests.exceptions.ConnectionError – Encountered an unexpected error while performing the API request.
requests.exceptions.Timeout – The API request timed out.

Return type:

str

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

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

Parameters:

action (str) – The MediaWiki API action to perform.
http_method (str) – The HTTP method to use in the request.
*args (Tuple[str, Any]) – Tupled key-value pairs to be passed to the index.php script as data. In most cases, it is preferable to pass these as keyword arguments instead. This can be useful when the parameter name is a reserved Python keyword (e.g. from).
**kwargs (Any) – Arguments to be passed to the index.php script as data.

Returns:

The API response.

Raises:

errors.MaximumRetriesExceeded – The API request failed and the maximum number of retries was exceeded.
requests.exceptions.HTTPError – Received an invalid HTTP response, or a status code in the 4xx range.
requests.exceptions.ConnectionError – Encountered an unexpected error while performing the API request.
requests.exceptions.Timeout – The API request timed out.

Return type:

str

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

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

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

Parameters:

start (str | None)
end (str | None)
dir (str)
namespace (str | int | None)
prop (str | None)
show (str | None)
limit (int | None)
type (str | None)
toponly (bool | None)
max_items (int | None)
api_chunk_size (int | None)

Return type:

List

require(major, minor, revision=None, raise_error=True)[source]¶

Check whether the current wiki matches the required version.

Parameters:

major (int) – The required major version.
minor (int) – The required minor version.
revision (int | None) – The required revision.
raise_error (bool) – Whether to throw an error if the version of the current wiki is below the required version. Defaults to True.

Returns:

False if the version of the current wiki is below the required version, else: True. If raise_error is False and the version is below the required version, None is returned.

Raises:

errors.MediaWikiVersionError – The current wiki is below the required version and raise_error=True.
RuntimeError – It raise_error is None and the version attribute is unset This is usually done automatically on construction of the Site, unless do_init=False is passed to the constructor. After instantiation, the site_init() functon can be used to retrieve and set the version.
NotImplementedError – If the revision argument was passed. The logic for this is currently unimplemented.

Return type:

bool | None

revisions(revids, prop='ids|timestamp|flags|comment|user')[source]¶

Get data about a list of revisions.

Site¶

`Site`¶