simplemediawiki — Extremely low-level wrapper to the MediaWiki API

simplemediawiki is an extremely low-level wrapper to the MediaWiki API. It automatically handles cookies and gzip compression so that you can make basic calls to the API in the easiest and fastest way possible. It also provides a few functions to make day-to-day API access easier.

To use this module, initialize a MediaWiki object, passing it the URL of api.php for the wiki you want to work with. Calls go through A generic login wrapper as well as functions to determine limits and get a list of namespaces are provided for your convenience.

>>> from simplemediawiki import MediaWiki
>>> wiki = MediaWiki('')
>>>{'action': 'query', 'prop': 'revisions', 'titles': 'Main Page'})
{u'query': {u'pages': {...}}}

Module reference

class simplemediawiki.MediaWiki(api_url, cookie_file=None, cookiejar=None, user_agent='python-simplemediawiki/1.2.0b1 +', http_user=None, http_password=None)

Create a new object to access a wiki via api_url.

If you’re interested in saving session data across multiple MediaWiki objects, provide a cookielib.CookieJar object cookiejar or filename cookie_file to where you want to save the cookies. If cookiejar is present cookie_file is ignored.

Applications that use simplemediawiki should change the user_agent argument to something that can help identify the application if it is misbehaving. It’s recommended to use build_user_agent() to create a User-Agent string that will be most helpful to server administrators. Wikimedia sites enforce using a correct User-Agent; you should read Wikimedia’s User-Agent policy if you plan to be accessing those wikis.


If a user of your application may not know how to get the correct API URL for their MediaWiki, you can try getting the right one with MediaWiki.normalize_api_url().

  • api_url – URL for the path to the API endpoint
  • cookiejar – already-created cookielib.CookieJar object
  • cookie_file – path to a cookielib.FileCookieJar file
  • user_agent – string sent as User-Agent header to web server

Make an API call to the wiki. params is a dictionary of query string arguments. For example, to get basic information about the wiki, run:

>>>{'action': 'query', 'meta': 'siteinfo'})

which would make a call to http://domain/w/api.php?action=query&meta=siteinfo&format=json (except the query string would be sent in POST).

Parameters:params – dictionary of query string parameters
Returns:dictionary containing API response
limits(low, high)

Convenience function for determining appropriate limits in the API. If the (usually logged-in) client has the apihighlimits right, it will return high; otherwise it will return low.

It’s generally a good idea to use the highest limit possible; this reduces the amount of HTTP requests and therefore overhead. Read the API documentation for details on the limits for the function you are using.

  • low – value to return if client does not have apihighlimits
  • high – value to return if client has apihighlimits

low or high

login(user, passwd)

Logs into the wiki with username user and password passwd. Returns True on successful login.

  • user – username
  • passwd – password

True on successful login, otherwise False


Logs out of the wiki.


Fetches a list of namespaces for this wiki and returns them as a dictionary of namespace IDs corresponding to namespace names. If psuedo is True, the dictionary will also list psuedo-namespaces, which are the “Special:” and “Media:” namespaces (special because they have no content associated with them and their IDs are negative).

Parameters:psuedo – boolean to determine inclusion of psuedo-namespaces
Returns:dictionary of namespace IDs and names

Checks that the API URL used to initialize this object actually returns JSON. If it doesn’t, make some educated guesses and try to find the correct URL.

Returns:a valid API URL or None
static parse_date(date)

Converts ISO 8601 dates generated by the MediaWiki API into datetime.datetime objects.

This will return a time in what your wiki thinks is UTC. Plan accordingly for bad server configurations.

Parameters:date – string ISO 8601 date representation
Returns:datetime.datetime object
simplemediawiki.build_user_agent(application_name, version, url)

Build a good User-Agent header string that can help server administrators contact you if your application is misbehaving. This string will also contain a reference to python-simplemediawiki.

See the documentation for simplemediawiki.MediaWiki for good reasons why you should use a custom User-Agent string for your application.

  • application_name – your application’s name
  • version – your application’s version
  • url – a URL where smoeone can find information about your application or your email address

User-Agent string

Table Of Contents

This Page