ws.client.api module

class ws.client.api.API(*args, **kwargs)

Bases: ws.client.connection.Connection

Simple interface to MediaWiki’s API.

Parameters

kwargs – any keyword arguments of the Connection object

login(username, password)

Logs into the wiki with username and password. See MediaWiki#API:Login for reference.

Parameters

  • username – username to use

  • password – password to use

Returns

True on successful login, otherwise raises LoginFailed

logout()

Logs out of the wiki. See MediaWiki#API:Logout for reference.

Returns

True

property site

A ws.client.site.Site instance for the current wiki.

property user

A ws.client.user.User instance for the current wiki.

property tags

A ws.client.tags.Tags instance for the current wiki.

property redirects

A ws.client.redirects.Redirects instance for the current wiki.

property max_ids_per_query

A maximum number of values that can be passed to the titles, pageids and revids parameters of the API. It is 500 for users with the apihighlimits right and 50 for others. These values correspond to the actual limits enforced by MediaWiki.

See also API.call_api_autoiter_ids().

property last_revision_id

ID of the last revision on the wiki.

This property is not cached since it may change very often.

Note

The total edit count is available in global statistics, but it is different from the last revision ID obtained from recentchanges.

property oldest_rc_timestamp

A timestamp of the oldest entry stored in the recentchanges table.

Items in the recentchanges table are periodically purged according to the $wgRCMaxAge setting. The value is very important for algorithms using list=recentchanges with specific timespan.

This property is not cached since it may change (though not very often).

property newest_rc_timestamp

Returns a timestamp of the newest entry stored in the recentchanges table.

Title(title)

Parse a MediaWiki title.

Parameters

title (str) – page title to be parsed

Returns

a ws.parser_helpers.title.Title object

call_api_autoiter_ids(params=None, *, expand_result=True, **kwargs)

A wrapper method around Connection.call_api() which automatically splits the call into multiple queries due to API.max_ids_per_query.

Note that this is applicable only to the titles, pageids and revids API parameters which have to be supplied as list or set to this method. Exactly one of these parameters has to be supplied.

The parameters have the same meaning as those in the Connection.call_api() method.

This method is a generator which yields the results of the call to the Connection.call_api() method for each chunk.

query_continue(params=None, **kwargs)

Generator for MediaWiki’s query-continue feature.

Parameters
Yields

from "query" part of the API response

generator(params=None, **kwargs)

Interface to API:Generators, conveniently implemented as Python generator.

Parameter generator must be supplied.

Parameters
Yields

from "pages" part of the API response

When a generator is combined with props, results are split into multiple chunks, each providing piece of information. For exmample queries with “prop=revisions” and “rvprop=content” have a limit lower than the generator’s maximum and specifying multiple props generally results in exceeding the value of $wgAPIMaxResultSize.

Although there is an automated query continuation via query_continue(), the overlapping data is not squashed automatically in order to avoid keeping big data in memory (this is the point of API:Generators). As a result, a page may be yielded multiple times. For applications where this matters, see ws.interlanguage.InterlanguageLinks.InterlanguageLinks._get_allpages() for an example of proper handling of this case.

list(params=None, **kwargs)

Interface to API:Lists, implemented as Python generator.

Parameter list must be supplied.

Parameters
Yields

from "list" part of the API response

call_with_csrftoken(params=None, **kwargs)

A wrapper around ws.client.connection.Connection.call_api() with automatic management of the CSRF token.

Parameters
Returns

same as ws.client.connection.Connection.call_api()

edit(title, pageid, text, basetimestamp, summary, **kwargs)

Interface to API:Edit. MD5 hash of the new text is computed automatically and added to the query. This method is rate-limited with the @RateLimited decorator to allow 1 call per 3 seconds.

Parameters

  • title (str) – the title of the page (used only for logging)

  • pageid (str or int) – page ID of the page to be edited

  • text (str) – new page content

  • basetimestamp (str) – Timestamp of the base revision (obtained through prop=revisions&rvprop=timestamp). Used to detect edit conflicts.

  • summary (str) – edit summary

  • kwargs – Additional query parameters, see API:Edit.

create(title, text, summary, **kwargs)

Specialization of edit() for creating pages. The createonly parameter is always added to the query. This method is rate-limited with the @RateLimited decorator to allow 1 call per 10 seconds.

Parameters

  • title (str) – the title of the page to be created

  • text (str) – new page content

  • summary (str) – edit summary

  • kwargs – Additional query parameters, see API:Edit.

move(from_title, to_title, reason, *, movetalk=True, movesubpages=True, noredirect=False, **kwargs)

Interface to API:Move. This method is rate-limited with the @RateLimited decorator to allow 1 call per 10 seconds.

Parameters

  • from_title (str) – the original title of the page to be renamed

  • to_title (str) – the new title of the page to be renamed

  • reason (str) – reason for the rename

  • movetalk (bool) – rename the associated talk page, if it exists

  • subpages (bool) – rename subpages, if applicable

  • noredirect (bool) – don’t create a redirect

  • kwargs – Additional query parameters, see API:Move.

exception ws.client.api.LoginFailed

Bases: Exception

Raised when the API.login() call failed.