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
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': {...}}}
Module reference¶
-
class
simplemediawiki.
MediaWiki
(api_url, cookie_file=None, cookiejar=None, user_agent='python-simplemediawiki/1.2.0b2 +https://github.com/ianweller/python-simplemediawiki', 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 acookielib.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
api_url – URL for the path to the API endpoint
cookiejar – already-created cookielib.CookieJar object
cookie_file – path to a
cookielib.FileCookieJar
fileuser_agent – string sent as
User-Agent
header to web server
-
call
(params)¶ 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
-
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.
- Parameters
low – value to return if client does not have
apihighlimits
high – value to return if client has
apihighlimits
- Returns
low or high
-
login
(user, passwd)¶ Logs into the wiki with username user and password passwd. Returns
True
on successful login.- Parameters
user – username
passwd – password
- Returns
True
on successful login, otherwiseFalse
-
logout
()¶ Logs out of the wiki.
- Returns
True
-
namespaces
(psuedo=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
-
normalize_api_url
()¶ 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.- Parameters
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
- Returns
User-Agent string