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
file - user_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
- low – value to return if client does not have
-
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