mw.api – MediaWiki API abstraction

This module contains a set of utilities for interacting with the MediaWiki API.

Here’s an example of a common usage pattern:

>>> from mw import api
>>>
>>> session = api.Session("https://en.wikipedia.org/w/api.php")
>>>
>>> revisions = session.revisions.query(
...     properties={'ids', 'content'},
...     titles={"User:EpochFail"},
...     direction="newer",
...     limit=3
... )
>>>
>>> for rev in revisions:
...     print(
...             "rev_id={0}, length={1} characters".format(
...                     rev['revid'],
...                     len(rev.get('*', ""))
...             )
...     )
...
rev_id=190055192, length=124 characters
rev_id=276121340, length=132 characters
rev_id=276121389, length=124 characters

Session

class mw.api.Session(uri, *args, user_agent='MediaWiki-Utilities', **kwargs)

Represents a connection to a MediaWiki API.

Cookies and other session information is preserved.

Parameters:

uri : str

The base URI for the API to use. Usually ends in “api.php”

user_agent : str

The User-Agent to be sent with requests. Will raise a warning if left to default value.

pages = None

An instance of mw.api.Pages.

revisions = None

An instance of mw.api.Revisions.

recent_changes = None

An instance of mw.api.RecentChanges.

site_info = None

An instance of mw.api.SiteInfo.

user_contribs = None

An instance of mw.api.UserContribs.

users = None

An instance of mw.api.Users.

deleted_revisions = None

An instance of mw.api.DeletedRevisions.

login(username, password, token=None)

Performs a login operation. This method usually makes two requests to API – one to get a token and one to use the token to log in. If authentication fails, this method will throw an errors.AuthenticationError.

Parameters:

username : str

Your username

password : str

Your password

Returns:

The response in a json dict

Collections

class mw.api.DeletedRevisions(session)

query(*args, limit=9223372036854775807, **kwargs)

Queries deleted revisions. See https://www.mediawiki.org/wiki/API:Deletedrevs

Parameters:

titles : set(str)

A set of page names to query (note that namespace prefix is expected)

start : mw.Timestamp

A timestamp to start querying from

end : mw.Timestamp

A timestamp to end querying

from_title : str

A title from which to start querying (alphabetically)

to_title : str

A title from which to stop querying (alphabetically)

prefix : str

A title prefix to match on

drcontinue : str

When more results are available, use this to continue (3) Note: may only work if drdir is set to newer.

unique : bool

List only one revision for each page

tag : str

Only list revision tagged with this tag

user : str

Only list revisions saved by this user_text

excludeuser : str

Do not list revision saved by this user_text

namespace : int

Only list pages in this namespace (id)

limit : int

Limit the number of results

direction : str

“newer” or “older”

properties : set(str)

A list of properties to include in the results:

• ids - The ID of the revision.
• flags - Revision flags (minor).
• timestamp - The timestamp of the revision.
• user - User that made the revision.
• userid - User ID of the revision creator.
• size - Length (bytes) of the revision.
• sha1 - SHA-1 (base 16) of the revision.
• contentmodel - Content model ID of the revision.
• comment - Comment by the user for the revision.
• parsedcomment - Parsed comment by the user for the revision.
• content - Text of the revision.
• tags - Tags for the revision.

class mw.api.Pages(session)

TODO

class mw.api.RecentChanges(session)

Recent changes (revisions, page creations, registrations, moves, etc.)

query(*args, limit=None, **kwargs)

Enumerate recent changes. See https://www.mediawiki.org/wiki/API:Recentchanges

Parameters:

start : mw.Timestamp

The timestamp to start enumerating from

end : mw.Timestamp

The timestamp to end enumerating

direction :

“newer” or “older”

namespace : int

Filter log entries to only this namespace(s)

user : str

Only list changes by this user

excludeuser : str

Don’t list changes by this user

tag : str

Only list changes tagged with this tag

properties : set(str)

Include additional pieces of information

• user - Adds the user responsible for the edit and tags if they are an IP
• userid - Adds the user id responsible for the edit
• comment - Adds the comment for the edit
• parsedcomment - Adds the parsed comment for the edit
• flags - Adds flags for the edit
• timestamp - Adds timestamp of the edit
• title - Adds the page title of the edit
• ids - Adds the page ID, recent changes ID and the new and old revision ID
• sizes - Adds the new and old page length in bytes
• redirect - Tags edit if page is a redirect
• patrolled - Tags patrollable edits as being patrolled or unpatrolled
• loginfo - Adds log information (logid, logtype, etc) to log entries
• tags - Lists tags for the entry
• sha1 - Adds the content checksum for entries associated with a revision

token : set(str)

Which tokens to obtain for each change

• patrol

show : set(str)

Show only items that meet this criteria. For example, to see only minor edits done by logged-in users, set show={‘minor’, ‘!anon’}.

• minor
• !minor
• bot
• !bot
• anon
• !anon
• redirect
• !redirect
• patrolled
• !patrolled
• unpatrolled

limit : int

How many total changes to return

type : set(str)

Which types of changes to show

• edit
• external
• new
• log

toponly : bool

Only list changes which are the latest revision

rccontinue : str

Use this to continue loading results from where you last left off

class mw.api.Revisions(session)

A collection of revisions indexes by title, page_id and user_text. Note that revisions of deleted pages are queriable via mw.api.DeletedRevs.

get(rev_id, **kwargs)

Get a single revision based on it’s ID. Throws a KeyError if the rev_id cannot be found.

Parameters:

rev_id : int

Revision ID

**kwargs

Passed to query()

Returns:

A single rev dict

query(*args, limit=None, **kwargs)

Get revision information. See https://www.mediawiki.org/wiki/API:Properties#revisions_.2F_rv

Parameters:

properties : set(str)

Which properties to get for each revision:

• ids - The ID of the revision
• flags - Revision flags (minor)
• timestamp - The timestamp of the revision
• user - User that made the revision
• userid - User id of revision creator
• size - Length (bytes) of the revision
• sha1 - SHA-1 (base 16) of the revision
• contentmodel - Content model id
• comment - Comment by the user for revision
• parsedcomment - Parsed comment by the user for the revision
• content - Text of the revision
• tags - Tags for the revision

limit : int

Limit how many revisions will be returned No more than 500 (5000 for bots) allowed

start_id : int

From which revision id to start enumeration (enum)

end_id : int

Stop revision enumeration on this revid

start : mw.Timestamp

From which revision timestamp to start enumeration (enum)

end : mw.Timestamp

Enumerate up to this timestamp

direction : str

“newer” or “older”

user : str

Only include revisions made by user_text

excludeuser : bool

Exclude revisions made by user

tag : str

Only list revisions tagged with this tag

expandtemplates : bool

Expand templates in revision content (requires “content” propery)

generatexml : bool

Generate XML parse tree for revision content (requires “content” propery)

parse : bool

Parse revision content (requires “content” propery)

section : int

Only retrieve the content of this section number

token : set(str)

Which tokens to obtain for each revision

• rollback - See https://www.mediawiki.org/wiki/API:Edit_-_Rollback#Token

rvcontinue : str

When more results are available, use this to continue

diffto : int

Revision ID to diff each revision to. Use “prev”, “next” and “cur” for the previous, next and current revision respectively

difftotext : str

Text to diff each revision to. Only diffs a limited number of revisions. Overrides diffto. If section is set, only that section will be diffed against this text

contentformat : str

Serialization format used for difftotext and expected for output of content

• text/x-wiki
• text/javascript
• text/css
• text/plain
• application/json

Returns:

An iterator of rev dicts returned from the API.

class mw.api.SiteInfo(session)

General information about the site.

query(properties=None, filteriw=None, showalldb=None, numberinggroup=None, inlanguagecode=None)

General information about the site. See https://www.mediawiki.org/wiki/API:Meta#siteinfo_.2F_si

Parameters:

properties: set(str)

Which sysinfo properties to get:

• general - Overall system information
• namespaces - List of registered namespaces and their canonical names
• namespacealiases - List of registered namespace aliases
• specialpagealiases - List of special page aliases
• magicwords - List of magic words and their aliases
• statistics - Returns site statistics
• interwikimap - Returns interwiki map (optionally filtered, (optionally localised by using siinlanguagecode))
• dbrepllag - Returns database server with the highest replication lag
• usergroups - Returns user groups and the associated permissions
• extensions - Returns extensions installed on the wiki
• fileextensions - Returns list of file extensions allowed to be uploaded
• rightsinfo - Returns wiki rights (license) information if available
• restrictions - Returns information on available restriction (protection) types
• languages - Returns a list of languages MediaWiki supports(optionally localised by using siinlanguagecode)
• skins - Returns a list of all enabled skins
• extensiontags - Returns a list of parser extension tags
• functionhooks - Returns a list of parser function hooks
• showhooks - Returns a list of all subscribed hooks (contents of $wgHooks)
• variables - Returns a list of variable IDs
• protocols - Returns a list of protocols that are allowed in external links.
• defaultoptions - Returns the default values for user preferences.

filteriw : str

“local” or ”!local” Return only local or only nonlocal entries of the interwiki map

showalldb : bool

List all database servers, not just the one lagging the most

numberingroup : bool

Lists the number of users in user groups

inlanguagecode : bool

Language code for localised language names (best effort, use CLDR extension)

class mw.api.UserContribs(session)

A collection of revisions indexes by user.

query(*args, limit=None, **kwargs)

Get a user’s revisions. See https://www.mediawiki.org/wiki/API:Usercontribs

Parameters:

limit : int

The maximum number of contributions to return.

start : mw.Timestamp

The start timestamp to return from

end : mw.Timestamp

The end timestamp to return to

user : set(str)

The users to retrieve contributions for. Maximum number of values 50 (500 for bots)

userprefix : set(str)

Retrieve contributions for all users whose names begin with this value.

direction : str

“newer” or “older”

namespace : int

Only list contributions in these namespaces

properties :

Include additional pieces of information

• ids - Adds the page ID and revision ID
• title - Adds the title and namespace ID of the page
• timestamp - Adds the timestamp of the edit
• comment - Adds the comment of the edit
• parsedcomment - Adds the parsed comment of the edit
• size - Adds the new size of the edit
• sizediff - Adds the size delta of the edit against its parent
• flags - Adds flags of the edit
• patrolled - Tags patrolled edits
• tags - Lists tags for the edit

show : set(str)

Show only items that meet thse criteria, e.g. non minor edits only: ucshow=!minor. NOTE: If ucshow=patrolled or ucshow=!patrolled is set, revisions older than $wgRCMaxAge (2592000) won’t be shown

• minor
• !minor,
• patrolled,
• !patrolled,
• top,
• !top,
• new,
• !new

tag : str

Only list revisions tagged with this tag

toponly : bool

DEPRECATED! Only list changes which are the latest revision

Errors

class mw.api.errors.APIError(doc)

code = None

The error code returned by the api – if available.

message = None

The error message returned by the api – if available.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class mw.api.errors.AuthenticationError(doc)

result = None

The result code of an authentication attempt.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class mw.api.errors.MalformedResponse(key, doc)

key = None

The expected, but missing key from the API call.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.