projects.mako.cc - python-simplemediawiki.debian/blob - simplemediawiki.py

   1 # python-simplemediawiki - Extremely low-level wrapper to the MediaWiki API
   2 # Copyright (C) 2010 Red Hat, Inc.
   3 #
   4 # This library is free software; you can redistribute it and/or modify it under
   5 # the terms of the GNU Lesser General Public License as published by the Free
   6 # Software Foundation; either version 2.1 of the License, or (at your option)
   7 # any later version.
   8 #
   9 # This library is distributed in the hope that it will be useful, but WITHOUT
  10 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  11 # FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
  12 # details.
  13 #
  14 # You should have received a copy of the GNU General Public License along with
  15 # this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 """
  18 simplemediawiki is an extremely low-level wrapper to the MediaWiki API. It
  19 automatically handles cookies and gzip compression so that you can make basic
  20 calls to the API in the easiest way possible. It also provides a few functions
  21 to make day-to-day API access easier.
  22
  23 To use this module, instantiate a MediaWiki object, passing it the URL of
  24 api.php for the wiki you want to work with. Calls go through MediaWiki.call().
  25 A generic login wrapper as well as functions to determine limits and get a list
  26 of namespaces are provided for your convenience.
  27
  28 >>> from simplemediawiki import MediaWiki
  29 >>> wiki = MediaWiki('http://en.wikipedia.org/w/api.php')
  30 >>> wiki.call({'action': 'query', 'prop': 'revisions', 'titles': 'Main Page'})
  31 {u'query': {u'pages': {...}}}
  32 """
  33
  34 import cookielib
  35 import gzip
  36 import iso8601
  37 import json
  38 from StringIO import StringIO
  39 import urllib
  40 import urllib2
  41
  42 __author__ = 'Ian Weller <ian@ianweller.org>'
  43 __version__ = '1.0.2'
  44 DEFAULT_UA = ('python-simplemediawiki/%s '
  45               '+https://github.com/ianweller/python-simplemediawiki') \
  46         % __version__
  47
  48
  49 class MediaWiki():
  50     """
  51     Class to represent a MediaWiki installation with an enabled API.
  52
  53     api_url: URL to api.php (usually similar to http://example.com/w/api.php)
  54     """
  55     _high_limits = None
  56     _namespaces = None
  57     _psuedo_namespaces = None
  58     _mediawiki_version = None
  59
  60     def __init__(self, api_url, cookie_file=None, user_agent=DEFAULT_UA):
  61         self._api_url = api_url
  62         if cookie_file:
  63             self._cj = cookielib.MozillaCookieJar(cookie_file)
  64             try:
  65                 self._cj.load()
  66             except IOError:
  67                 self._cj.save()
  68                 self._cj.load()
  69         else:
  70             self._cj = cookielib.CookieJar()
  71         self._opener = urllib2.build_opener(
  72                 urllib2.HTTPCookieProcessor(self._cj)
  73         )
  74         self._opener.addheaders = [('User-agent', user_agent)]
  75
  76     def _fetch_http(self, url, params):
  77         """
  78         Standard HTTP request handler for this class with gzip and cookie
  79         support.
  80         """
  81         request = urllib2.Request(url, urllib.urlencode(params))
  82         request.add_header('Accept-encoding', 'gzip')
  83         response = self._opener.open(request)
  84         if isinstance(self._cj, cookielib.MozillaCookieJar):
  85             self._cj.save()
  86         if response.headers.get('Content-Encoding') == 'gzip':
  87             compressed = StringIO(response.read())
  88             gzipper = gzip.GzipFile(fileobj=compressed)
  89             data = gzipper.read()
  90         else:
  91             data = response.read()
  92         return data
  93
  94     def call(self, params):
  95         """
  96         Make a call to the wiki. Returns a dictionary that represents the JSON
  97         returned by the API.
  98         """
  99         params['format'] = 'json'
 100         return json.loads(self._fetch_http(self._api_url, params))
 101
 102     def normalize_api_url(self):
 103         """
 104         This function checks the given URL for a correct API endpoint and
 105         returns that URL, while also helpfully setting this object's API URL to
 106         it. If it can't magically conjure an API endpoint, it returns False.
 107         """
 108         def tester(self, api_url):
 109             """
 110             Attempts to fetch general information about the MediaWiki instance
 111             in order to test whether the given URL will return JSON.
 112             """
 113             data = self._fetch_http(api_url, {'action': 'query',
 114                                               'meta': 'siteinfo',
 115                                               'siprop': 'general',
 116                                               'format': 'json'})
 117             try:
 118                 data_json = json.loads(data)
 119                 # may as well set the version
 120                 try:
 121                     version_string = data_json['query']['general']['generator']
 122                     self._mediawiki_version = version_string.split(' ', 1)[1]
 123                 except KeyError:
 124                     pass
 125                 return (data, data_json)
 126             except ValueError:
 127                 return (data, None)
 128
 129         data, data_json = tester(self, self._api_url)
 130         if data_json:
 131             return self._api_url
 132         else:
 133             # if there's an index.php in the URL, we might find the API
 134             if 'index.php' in self._api_url:
 135                 test_api_url = self._api_url.split('index.php')[0] + 'api.php'
 136                 print test_api_url
 137                 test_data, test_data_json = tester(self, test_api_url)
 138                 print (test_data, test_data_json)
 139                 if test_data_json:
 140                     self._api_url = test_api_url
 141                     return self._api_url
 142             return False
 143
 144
 145     def login(self, user, passwd, token=None):
 146         """
 147         Convenience function for logging into the wiki. It should never be
 148         necessary to provide a token argument; it is part of the login process
 149         since MediaWiki 1.15.3 (see MediaWiki bug 23076).
 150         """
 151         data = {'action': 'login',
 152                 'lgname': user,
 153                 'lgpassword': passwd}
 154         if token:
 155             data['lgtoken'] = token
 156         result = self.call(data)
 157         if result['login']['result'] == 'Success':
 158             self._high_limits = None
 159             return True
 160         elif result['login']['result'] == 'NeedToken' and not token:
 161             return self.login(user, passwd, result['login']['token'])
 162         else:
 163             return False
 164
 165     def logout(self):
 166         """
 167         Conveinence function for logging out of the wiki.
 168         """
 169         data = {'action': 'logout'}
 170         self.call(data)
 171         self._high_limits = None
 172         return True
 173
 174     def limits(self, low, high):
 175         """
 176         Convenience function for determining appropriate limits in the API. If
 177         the logged in user has the "apihighlimits" right, it will return the
 178         high argument; otherwise it will return the low argument.
 179         """
 180         if self._high_limits == None:
 181             result = self.call({'action': 'query',
 182                                 'meta': 'userinfo',
 183                                 'uiprop': 'rights'})
 184             self._high_limits = 'apihighlimits' in \
 185                     result['query']['userinfo']['rights']
 186         if self._high_limits:
 187             return high
 188         else:
 189             return low
 190
 191     def namespaces(self, psuedo=True):
 192         """
 193         Fetches a list of namespaces for this wiki.
 194         """
 195         if self._namespaces == None:
 196             result = self.call({'action': 'query',
 197                                 'meta': 'siteinfo',
 198                                 'siprop': 'namespaces'})
 199             self._namespaces = {}
 200             self._psuedo_namespaces = {}
 201             for nsid in result['query']['namespaces']:
 202                 if int(nsid) >= 0:
 203                     self._namespaces[int(nsid)] = \
 204                             result['query']['namespaces'][nsid]['*']
 205                 else:
 206                     self._psuedo_namespaces[int(nsid)] = \
 207                             result['query']['namespaces'][nsid]['*']
 208         if psuedo:
 209             retval = {}
 210             retval.update(self._namespaces)
 211             retval.update(self._psuedo_namespaces)
 212             return retval
 213         else:
 214             return self._namespaces
 215
 216     @staticmethod
 217     def parse_date(date):
 218         """
 219         Converts dates provided by the MediaWiki API into datetime.datetime
 220         objects.
 221         """
 222         return iso8601.parse_date(date)