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
site

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

user

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

tags

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

redirects

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

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.

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.

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

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

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