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 MediaWiki.call(). 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('http://en.wikipedia.org/w/api.php')
>>> wiki.call({'action': 'query', 'prop': 'revisions', 'titles': 'Main Page'})
{u'query': {u'pages': {...}}}
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.
Tip
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().
Parameters: |
|
---|
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:
>>> wiki.call({'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 |
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.
Parameters: |
|
---|---|
Returns: | low or high |
Logs into the wiki with username user and password passwd. Returns True on successful login.
Parameters: |
|
---|---|
Returns: | True on successful login, otherwise False |
Logs out of the wiki.
Returns: | True |
---|
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 |
---|
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 |
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.
Parameters: |
|
---|---|
Returns: | User-Agent string |