rtm.py

   1 # Python library for Remember The Milk API
   2
   3 __author__ = 'Sridhar Ratnakumar <http://nearfar.org/>'
   4 __all__ = (
   5     'API',
   6     'createRTM',
   7     'set_log_level',
   8         )
   9
  10
  11 import new
  12 import warnings
  13 import urllib
  14 import logging
  15 from md5 import md5
  16
  17 warnings.simplefilter('default', ImportWarning)
  18
  19 _use_simplejson = False
  20 try:
  21     import simplejson
  22     _use_simplejson = True
  23 except ImportError:
  24     pass
  25
  26 if not _use_simplejson:
  27     warnings.warn("simplejson module is not available, "
  28              "falling back to the internal JSON parser. "
  29              "Please consider installing the simplejson module from "
  30              "http://pypi.python.org/pypi/simplejson.", ImportWarning,
  31              stacklevel=2)
  32
  33 logging.basicConfig()
  34 LOG = logging.getLogger(__name__)
  35 LOG.setLevel(logging.INFO)
  36
  37 SERVICE_URL = 'http://api.rememberthemilk.com/services/rest/'
  38 AUTH_SERVICE_URL = 'http://www.rememberthemilk.com/services/auth/'
  39
  40
  41 class RTMError(Exception): pass
  42
  43 class RTMAPIError(RTMError): pass
  44
  45 class AuthStateMachine(object):
  46
  47     class NoData(RTMError): pass
  48
  49     def __init__(self, states):
  50         self.states = states
  51         self.data = {}
  52
  53     def dataReceived(self, state, datum):
  54         if state not in self.states:
  55             raise RTMError, "Invalid state <%s>" % state
  56         self.data[state] = datum
  57
  58     def get(self, state):
  59         if state in self.data:
  60             return self.data[state]
  61         else:
  62             raise AuthStateMachine.NoData, 'No data for <%s>' % state
  63
  64
  65 class RTM(object):
  66
  67     def __init__(self, apiKey, secret, token=None):
  68         self.apiKey = apiKey
  69         self.secret = secret
  70         self.authInfo = AuthStateMachine(['frob', 'token'])
  71
  72         # this enables one to do 'rtm.tasks.getList()', for example
  73         for prefix, methods in API.items():
  74             setattr(self, prefix,
  75                     RTMAPICategory(self, prefix, methods))
  76
  77         if token:
  78             self.authInfo.dataReceived('token', token)
  79
  80     def _sign(self, params):
  81         "Sign the parameters with MD5 hash"
  82         pairs = ''.join(['%s%s' % (k,v) for k,v in sortedItems(params)])
  83         return md5(self.secret+pairs).hexdigest()
  84
  85     def get(self, **params):
  86         "Get the XML response for the passed `params`."
  87         params['api_key'] = self.apiKey
  88         params['format'] = 'json'
  89         params['api_sig'] = self._sign(params)
  90
  91         json = openURL(SERVICE_URL, params).read()
  92
  93         LOG.debug("JSON response: \n%s" % json)
  94
  95         if _use_simplejson:
  96             data = dottedDict('ROOT', simplejson.loads(json))
  97         else:
  98             data = dottedJSON(json)
  99         rsp = data.rsp
 100
 101         if rsp.stat == 'fail':
 102             raise RTMAPIError, 'API call failed - %s (%s)' % (
 103                 rsp.err.msg, rsp.err.code)
 104         else:
 105             return rsp
 106
 107     def getNewFrob(self):
 108         rsp = self.get(method='rtm.auth.getFrob')
 109         self.authInfo.dataReceived('frob', rsp.frob)
 110         return rsp.frob
 111
 112     def getAuthURL(self):
 113         try:
 114             frob = self.authInfo.get('frob')
 115         except AuthStateMachine.NoData:
 116             frob = self.getNewFrob()
 117
 118         params = {
 119             'api_key': self.apiKey,
 120             'perms'  : 'delete',
 121             'frob'   : frob
 122             }
 123         params['api_sig'] = self._sign(params)
 124         return AUTH_SERVICE_URL + '?' + urllib.urlencode(params)
 125
 126     def getToken(self):
 127         frob = self.authInfo.get('frob')
 128         rsp = self.get(method='rtm.auth.getToken', frob=frob)
 129         self.authInfo.dataReceived('token', rsp.auth.token)
 130         return rsp.auth.token
 131
 132 class RTMAPICategory:
 133     "See the `API` structure and `RTM.__init__`"
 134
 135     def __init__(self, rtm, prefix, methods):
 136         self.rtm = rtm
 137         self.prefix = prefix
 138         self.methods = methods
 139
 140     def __getattr__(self, attr):
 141         if attr in self.methods:
 142             rargs, oargs = self.methods[attr]
 143             if self.prefix == 'tasksNotes':
 144                 aname = 'rtm.tasks.notes.%s' % attr
 145             else:
 146                 aname = 'rtm.%s.%s' % (self.prefix, attr)
 147             return lambda **params: self.callMethod(
 148                 aname, rargs, oargs, **params)
 149         else:
 150             raise AttributeError, 'No such attribute: %s' % attr
 151
 152     def callMethod(self, aname, rargs, oargs, **params):
 153         # Sanity checks
 154         for requiredArg in rargs:
 155             if requiredArg not in params:
 156                 raise TypeError, 'Required parameter (%s) missing' % requiredArg
 157
 158         for param in params:
 159             if param not in rargs + oargs:
 160                 warnings.warn('Invalid parameter (%s)' % param)
 161
 162         return self.rtm.get(method=aname,
 163                             auth_token=self.rtm.authInfo.get('token'),
 164                             **params)
 165
 166
 167
 168 # Utility functions
 169
 170 def sortedItems(dictionary):
 171     "Return a list of (key, value) sorted based on keys"
 172     keys = dictionary.keys()
 173     keys.sort()
 174     for key in keys:
 175         yield key, dictionary[key]
 176
 177 def openURL(url, queryArgs=None):
 178     if queryArgs:
 179         url = url + '?' + urllib.urlencode(queryArgs)
 180     LOG.debug("URL> %s", url)
 181     return urllib.urlopen(url)
 182
 183 class dottedDict(object):
 184     "Make dictionary items accessible via the object-dot notation."
 185
 186     def __init__(self, name, dictionary):
 187         self._name = name
 188
 189         if type(dictionary) is dict:
 190             for key, value in dictionary.items():
 191                 if type(value) is dict:
 192                     value = dottedDict(key, value)
 193                 elif type(value) in (list, tuple) and key != 'tag':
 194                     value = [dottedDict('%s_%d' % (key, i), item)
 195                              for i, item in indexed(value)]
 196                 setattr(self, key, value)
 197
 198     def __repr__(self):
 199         children = [c for c in dir(self) if not c.startswith('_')]
 200         return 'dotted <%s> : %s' % (
 201             self._name,
 202             ', '.join(children))
 203
 204
 205 def safeEval(string):
 206     return eval(string, {}, {})
 207
 208 def dottedJSON(json):
 209     return dottedDict('ROOT', safeEval(json))
 210
 211 def indexed(seq):
 212     index = 0
 213     for item in seq:
 214         yield index, item
 215         index += 1
 216
 217
 218 # API spec
 219
 220 API = {
 221    'auth': {
 222        'checkToken':
 223            [('auth_token'), ()],
 224        'getFrob':
 225            [(), ()],
 226        'getToken':
 227            [('frob'), ()]
 228        },
 229     'contacts': {
 230         'add':
 231             [('timeline', 'contact'), ()],
 232         'delete':
 233             [('timeline', 'contact_id'), ()],
 234         'getList':
 235             [(), ()]
 236         },
 237     'groups': {
 238         'add':
 239             [('timeline', 'group'), ()],
 240         'addContact':
 241             [('timeline', 'group_id', 'contact_id'), ()],
 242         'delete':
 243             [('timeline', 'group_id'), ()],
 244         'getList':
 245             [(), ()],
 246         'removeContact':
 247             [('timeline', 'group_id', 'contact_id'), ()],
 248         },
 249     'lists': {
 250         'add':
 251             [('timeline', 'name'), ('filter'), ()],
 252         'archive':
 253             [('timeline', 'list_id'), ()],
 254         'delete':
 255             [('timeline', 'list_id'), ()],
 256         'getList':
 257             [(), ()],
 258         'setDefaultList':
 259             [('timeline'), ('list_id'), ()],
 260         'setName':
 261             [('timeline', 'list_id', 'name'), ()],
 262         'unarchive':
 263             [('timeline'), ('list_id'), ()],
 264         },
 265     'locations': {
 266         'getList':
 267             [(), ()]
 268         },
 269     'reflection': {
 270         'getMethodInfo':
 271             [('methodName',), ()],
 272         'getMethods':
 273             [(), ()]
 274         },
 275     'settings': {
 276         'getList':
 277             [(), ()]
 278         },
 279     'tasks': {
 280         'add':
 281             [('timeline', 'name',), ('list_id', 'parse',)],
 282         'addTags':
 283             [('timeline', 'list_id', 'taskseries_id', 'task_id', 'tags'),
 284              ()],
 285         'complete':
 286             [('timeline', 'list_id', 'taskseries_id', 'task_id',), ()],
 287         'delete':
 288             [('timeline', 'list_id', 'taskseries_id', 'task_id'), ()],
 289         'getList':
 290             [(),
 291              ('list_id', 'filter', 'last_sync')],
 292         'movePriority':
 293             [('timeline', 'list_id', 'taskseries_id', 'task_id', 'direction'),
 294              ()],
 295         'moveTo':
 296             [('timeline', 'from_list_id', 'to_list_id', 'taskseries_id', 'task_id'),
 297              ()],
 298         'postpone':
 299             [('timeline', 'list_id', 'taskseries_id', 'task_id'),
 300              ()],
 301         'removeTags':
 302             [('timeline', 'list_id', 'taskseries_id', 'task_id', 'tags'),
 303              ()],
 304         'setDueDate':
 305             [('timeline', 'list_id', 'taskseries_id', 'task_id'),
 306              ('due', 'has_due_time', 'parse')],
 307         'setEstimate':
 308             [('timeline', 'list_id', 'taskseries_id', 'task_id'),
 309              ('estimate',)],
 310         'setLocation':
 311             [('timeline', 'list_id', 'taskseries_id', 'task_id'),
 312              ('location_id',)],
 313         'setName':
 314             [('timeline', 'list_id', 'taskseries_id', 'task_id', 'name'),
 315              ()],
 316         'setPriority':
 317             [('timeline', 'list_id', 'taskseries_id', 'task_id'),
 318              ('priority',)],
 319         'setRecurrence':
 320             [('timeline', 'list_id', 'taskseries_id', 'task_id'),
 321              ('repeat',)],
 322         'setTags':
 323             [('timeline', 'list_id', 'taskseries_id', 'task_id'),
 324              ('tags',)],
 325         'setURL':
 326             [('timeline', 'list_id', 'taskseries_id', 'task_id'),
 327              ('url',)],
 328         'uncomplete':
 329             [('timeline', 'list_id', 'taskseries_id', 'task_id'),
 330              ()],
 331         },
 332     'tasksNotes': {
 333         'add':
 334             [('timeline', 'list_id', 'taskseries_id', 'task_id', 'note_title', 'note_text'), ()],
 335         'delete':
 336             [('timeline', 'note_id'), ()],
 337         'edit':
 338             [('timeline', 'note_id', 'note_title', 'note_text'), ()]
 339         },
 340     'test': {
 341         'echo':
 342             [(), ()],
 343         'login':
 344             [(), ()]
 345         },
 346     'time': {
 347         'convert':
 348             [('to_timezone',), ('from_timezone', 'to_timezone', 'time')],
 349         'parse':
 350             [('text',), ('timezone', 'dateformat')]
 351         },
 352     'timelines': {
 353         'create':
 354             [(), ()]
 355         },
 356     'timezones': {
 357         'getList':
 358             [(), ()]
 359         },
 360     'transactions': {
 361         'undo':
 362             [('timeline', 'transaction_id'), ()]
 363         },
 364     }
 365
 366 def createRTM(apiKey, secret, token=None):
 367     rtm = RTM(apiKey, secret, token)
 368
 369     if token is None:
 370         print 'No token found'
 371         print 'Give me access here:', rtm.getAuthURL()
 372         raw_input('Press enter once you gave access')
 373         print 'Note down this token for future use:', rtm.getToken()
 374
 375     return rtm
 376
 377 def test(apiKey, secret, token=None):
 378     rtm = createRTM(apiKey, secret, token)
 379
 380     rspTasks = rtm.tasks.getList(filter='dueWithin:"1 week of today"')
 381     print [t.name for t in rspTasks.tasks.list.taskseries]
 382     print rspTasks.tasks.list.id
 383
 384     rspLists = rtm.lists.getList()
 385     # print rspLists.lists.list
 386     print [(x.name, x.id) for x in rspLists.lists.list]
 387
 388 def set_log_level(level):
 389     '''Sets the log level of the logger used by the module.
 390
 391     >>> import rtm
 392     >>> import logging
 393     >>> rtm.set_log_level(logging.INFO)
 394     '''
 395
 396     LOG.setLevel(level)