Some licensing stuff
[jamaendo] / jamaendo / api.py
1 #!/usr/bin/env python
2 #
3 # This file is part of Jamaendo.
4 # Copyright (c) 2010, Kristoffer Gronlund
5 # All rights reserved.
6 #
7 # Redistribution and use in source and binary forms, with or without
8 # modification, are permitted provided that the following conditions are met:
9 #     * Redistributions of source code must retain the above copyright
10 #       notice, this list of conditions and the following disclaimer.
11 #     * Redistributions in binary form must reproduce the above copyright
12 #       notice, this list of conditions and the following disclaimer in the
13 #       documentation and/or other materials provided with the distribution.
14 #     * Neither the name of Jamaendo nor the
15 #       names of its contributors may be used to endorse or promote products
16 #       derived from this software without specific prior written permission.
17 #
18 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
19 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
20 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21 # DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
22 # DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 # (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
24 # LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
25 # ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28
29 # An improved, structured jamendo API wrapper for the N900 with cacheing
30 # Image / cover downloads.. and more?
31 import urllib, threading, os, gzip, time, simplejson, re
32
33 _CACHEDIR = None
34 _COVERDIR = None
35 _GET2 = '''http://api.jamendo.com/get2/'''
36 _MP3URL = _GET2+'stream/track/redirect/?id=%d&streamencoding=mp31'
37 _OGGURL = _GET2+'stream/track/redirect/?id=%d&streamencoding=ogg2'
38
39
40 def set_cache_dir(cachedir):
41     global _CACHEDIR
42     global _COVERDIR
43     _CACHEDIR = cachedir
44     _COVERDIR = os.path.join(_CACHEDIR, 'covers')
45
46     try:
47         os.makedirs(_CACHEDIR)
48     except OSError:
49         pass
50
51     try:
52         os.makedirs(_COVERDIR)
53     except OSError:
54         pass
55
56 # These classes can be partially constructed,
57 # and if asked for a property they don't know,
58 # makes a query internally to get the full story
59
60 _ARTIST_FIELDS = ['id', 'name', 'image']
61 _ALBUM_FIELDS = ['id', 'name', 'image', 'artist_name', 'artist_id', 'license_url']
62 _TRACK_FIELDS = ['id', 'name', 'image', 'artist_name', 'album_name', 'album_id', 'numalbum', 'duration']
63 _RADIO_FIELDS = ['id', 'name', 'idstr', 'image']
64
65 class LazyQuery(object):
66     def set_from_json(self, json):
67         for key, value in json.iteritems():
68             if key == 'id':
69                 assert(self.ID == int(value))
70             else:
71                 if key.endswith('_id'):
72                     value = int(value)
73                 setattr(self, key, value)
74
75     def load(self):
76         """Not automatic for now,
77         will have to do artist.load()
78
79         This is filled in further down
80         in the file
81         """
82         raise NotImplemented
83
84     def _needs_load(self):
85         return True
86
87     def _set_from(self, other):
88         raise NotImplemented
89
90     def _needs_load_impl(self, *attrs):
91         for attr in attrs:
92             if getattr(self, attr) is None:
93                 return True
94         return False
95
96     def _set_from_impl(self, other, *attrs):
97         for attr in attrs:
98             self._set_if(other, attr)
99
100     def _set_if(self, other, attrname):
101         if getattr(self, attrname) is None and getattr(other, attrname) is not None:
102             setattr(self, attrname, getattr(other, attrname))
103
104     def __repr__(self):
105         try:
106             return u"%s(%s)"%(self.__class__.__name__,
107                               u", ".join(repr(v) for k,v in self.__dict__.iteritems() if not k.startswith('_')))
108         except UnicodeEncodeError:
109             import traceback
110             traceback.print_exc()
111             return u"%s(?)"%(self.__class__.__name__)
112
113 class Artist(LazyQuery):
114     def __init__(self, ID, json=None):
115         self.ID = int(ID)
116         self.name = None
117         self.image = None
118         self.albums = None # None means not downloaded
119         if json:
120             self.set_from_json(json)
121
122     def _needs_load(self):
123         return self._needs_load_impl('name', 'albums')
124
125     def _set_from(self, other):
126         return self._set_from_impl(other, 'name', 'image', 'albums')
127
128 class Album(LazyQuery):
129     def __init__(self, ID, json=None):
130         self.ID = int(ID)
131         self.name = None
132         self.image = None
133         self.artist_name = None
134         self.artist_id = None
135         self.license_url = None
136         self.tracks = None # None means not downloaded
137         if json:
138             self.set_from_json(json)
139
140     def _needs_load(self):
141         return self._needs_load_impl('name', 'image', 'artist_name', 'artist_id', 'license_url', 'tracks')
142
143     def _set_from(self, other):
144         return self._set_from_impl(other, 'name', 'image', 'artist_name', 'artist_id', 'license_url', 'tracks')
145
146 class Track(LazyQuery):
147     def __init__(self, ID, json=None):
148         self.ID = int(ID)
149         self.name = None
150         self.image = None
151         self.artist_name = None
152         self.album_name = None
153         self.album_id = None
154         self.numalbum = None
155         self.duration = None
156         if json:
157             self.set_from_json(json)
158
159     def mp3_url(self):
160        return _MP3URL%(self.ID)
161
162     def ogg_url(self):
163        return _OGGURL%(self.ID)
164
165     def _needs_load(self):
166         return self._needs_load_impl('name', 'artist_name', 'album_name', 'album_id', 'numalbum', 'duration')
167
168     def _set_from(self, other):
169         return self._set_from_impl(other, 'name', 'image', 'artist_name', 'album_name', 'album_id', 'numalbum', 'duration')
170
171 class Radio(LazyQuery):
172     def __init__(self, ID, json=None):
173         self.ID = int(ID)
174         self.name = None
175         self.idstr = None
176         self.image = None
177         if json:
178             self.set_from_json(json)
179
180     def _needs_load(self):
181         return self._needs_load_impl('name', 'idstr', 'image')
182
183     def _set_from(self, other):
184         return self._set_from_impl(other, 'name', 'idstr', 'image')
185
186
187 _artists = {} # id -> Artist()
188 _albums = {} # id -> Album()
189 _tracks = {} # id -> Track()
190 _radios = {} # id -> Radio()
191
192
193 # cache sizes per session (TODO)
194 _CACHED_ARTISTS = 100
195 _CACHED_ALBUMS = 200
196 _CACHED_TRACKS = 500
197 _CACHED_RADIOS = 10
198
199 # TODO: cache queries?
200
201 class Query(object):
202     rate_limit = 1.1 # seconds between queries
203     last_query = time.time() - 1.5
204
205     @classmethod
206     def _ratelimit(cls):
207         now = time.time()
208         if now - cls.last_query < cls.rate_limit:
209             time.sleep(cls.rate_limit - (now - cls.last_query))
210         cls.last_query = now
211
212     def __init__(self):
213         pass
214
215     def _geturl(self, url):
216         print "*** %s" % (url)
217         Query._ratelimit()
218         f = urllib.urlopen(url)
219         ret = simplejson.load(f)
220         f.close()
221         return ret
222
223     def __str__(self):
224         return "#%s" % (self.__class__.__name__)
225
226     def execute(self):
227         raise NotImplemented
228
229 class CoverCache(object):
230     """
231     cache and fetch covers
232     TODO: background thread that
233     fetches and returns covers,
234     asynchronously, LIFO
235     """
236     def __init__(self):
237         self._covers = {} # (albumid, size) -> file
238         coverdir = _COVERDIR if _COVERDIR else '/tmp'
239         if os.path.isdir(coverdir):
240             covermatch = re.compile(r'(\d+)\-(\d+)\.jpg')
241             for fil in os.listdir(coverdir):
242                 fl = os.path.join(coverdir, fil)
243                 m = covermatch.match(fil)
244                 if m and os.path.isfile(fl):
245                     self._covers[(int(m.group(1)), int(m.group(2)))] = fl
246
247     def fetch_cover(self, albumid, size):
248         coverdir = _COVERDIR if _COVERDIR else '/tmp'
249         to = os.path.join(coverdir, '%d-%d.jpg'%(albumid, size))
250         if not os.path.isfile(to):
251             url = _GET2+'image/album/redirect/?id=%d&imagesize=%d'%(albumid, size)
252             urllib.urlretrieve(url, to)
253             self._covers[(albumid, size)] = to
254         return to
255
256     def get_cover(self, albumid, size):
257         cover = self._covers.get((albumid, size), None)
258         if not cover:
259             cover = self.fetch_cover(albumid, size)
260         return cover
261
262     def get_async(self, albumid, size, cb):
263         cover = self._covers.get((albumid, size), None)
264         if cover:
265             cb(cover)
266         else:
267             # TODO
268             cover = self.fetch_cover(albumid, size)
269             cb(cover)
270
271 _cover_cache = CoverCache()
272
273 def get_album_cover(albumid, size=200):
274     return _cover_cache.get_cover(albumid, size)
275
276 def get_album_cover_async(cb, albumid, size=200):
277     _cover_cache.get_async(albumid, size, cb)
278
279 class CustomQuery(Query):
280     def __init__(self, url):
281         Query.__init__(self)
282         self.url = url
283
284     def execute(self):
285         return self._geturl(self.url)
286
287     def __str__(self):
288         return self.url
289
290 class GetQuery(Query):
291     queries = {
292         'artist' : {
293             'url' : _GET2+'+'.join(_ARTIST_FIELDS)+'/artist/json/?',
294             'params' : 'artist_id=%d',
295             'constructor' : Artist
296             },
297         'album' : {
298             'url' : _GET2+'+'.join(_ALBUM_FIELDS)+'/album/json/?',
299             'params' : 'album_id=%d',
300             'constructor' : Album
301             },
302         'albums' : {
303             'url' : _GET2+'+'.join(_ALBUM_FIELDS)+'/album/json/?',
304             'params' : 'artist_id=%d',
305             'constructor' : [Album]
306             },
307         'track' : {
308             'url' : _GET2+'+'.join(_TRACK_FIELDS)+'/track/json/track_album+album_artist?',
309             'params' : 'id=%d',
310             'constructor' : Track
311             },
312         'tracks' : {
313             'url' : _GET2+'+'.join(_TRACK_FIELDS)+'/track/json/track_album+album_artist?',
314             'params' : 'order=numalbum_asc&album_id=%d',
315             'constructor' : [Track]
316             },
317         'radio' : {
318             'url' : _GET2+'+'.join(_TRACK_FIELDS)+'/track/json/radio_track_inradioplaylist+track_album+album_artist/?',
319             'params' : 'order=random_asc&radio_id=%d',
320             'constructor' : [Track]
321             },
322         'favorite_albums' : {
323             'url' : _GET2+'+'.join(_ALBUM_FIELDS)+'/album/json/album_user_starred/?',
324             'params' : 'user_idstr=%s',
325             'constructor' : [Album]
326             },
327     #http://api.jamendo.com/get2/id+name+url+image+artist_name/album/jsonpretty/album_user_starred/?user_idstr=sylvinus&n=all
328     #q = SearchQuery('album', user_idstr=user)
329
330         }
331 #http://api.jamendo.com/get2/id+name+image+artist_name+album_name+album_id+numalbum+duration/track/json/radio_track_inradioplaylist+track_album+album_artist/?order=numradio_asc&radio_id=283
332
333     def __init__(self, what, ID):
334         Query.__init__(self)
335         self.ID = ID
336         info = GetQuery.queries[what]
337         self.url = info['url']
338         self.params = info['params']
339         self.constructor = info['constructor']
340
341     def construct(self, data):
342         constructor = self.constructor
343         if isinstance(constructor, list):
344             constructor = constructor[0]
345         if isinstance(data, list):
346             return [constructor(int(x['id']), json=x) for x in data]
347         else:
348             return constructor(int(data['id']), json=data)
349
350     def execute(self):
351         js = self._geturl(self.url + self.params % (self.ID))
352         if not js:
353             return None
354         return self.construct(js)
355
356     def __str__(self):
357         return self.url + self.params % (self.ID)
358
359 class SearchQuery(GetQuery):
360     def __init__(self, what, query=None, order=None, user=None, count=10):
361         GetQuery.__init__(self, what, None)
362         self.query = query
363         self.order = order
364         self.count = count
365         self.user = user
366
367     def execute(self):
368         params = {}
369         if self.query:
370             params['searchquery'] = self.query
371         if self.order:
372             params['order'] = self.order
373         if self.count:
374             params['n'] = self.count
375         if self.user:
376             params['user_idstr'] = self.user
377         js = self._geturl(self.url +  urllib.urlencode(params))
378         if not js:
379             return None
380         return self.construct(js)
381
382     def __str__(self):
383         params = {'searchquery':self.query, 'order':self.order, 'n':self.count}
384         return self.url +  urllib.urlencode(params)
385
386 class JamendoAPIException(Exception):
387     def __init__(self, url):
388         Exception.__init__(self, url)
389
390 def _update_cache(cache, new_items):
391     if not isinstance(new_items, list):
392         new_items = [new_items]
393     for item in new_items:
394         old = cache.get(item.ID)
395         if old:
396             old._set_from(item)
397         else:
398             cache[item.ID] = item
399
400 def get_artist(artist_id):
401     """Returns: Artist"""
402     a = _artists.get(artist_id, None)
403     if not a:
404         q = GetQuery('artist', artist_id)
405         a = q.execute()
406         if not a:
407             raise JamendoAPIException(str(q))
408         _update_cache(_artists, a)
409         if isinstance(a, list):
410             a = a[0]
411     return a
412
413 def get_albums(artist_id):
414     """Returns: [Album]"""
415     q = GetQuery('albums', artist_id)
416     a = q.execute()
417     if not a:
418         raise JamendoAPIException(str(q))
419     _update_cache(_artists, a)
420     return a
421
422 def get_album(album_id):
423     """Returns: Album"""
424     a = _albums.get(album_id, None)
425     if not a:
426         q = GetQuery('album', album_id)
427         a = q.execute()
428         if not a:
429             raise JamendoAPIException(str(q))
430         _update_cache(_albums, a)
431         if isinstance(a, list):
432             a = a[0]
433     return a
434
435 def get_tracks(album_id):
436     """Returns: [Track]"""
437     q = GetQuery('tracks', album_id)
438     a = q.execute()
439     if not a:
440         raise JamendoAPIException(str(q))
441     _update_cache(_tracks, a)
442     return a
443
444 def get_track(track_id):
445     """Returns: Track"""
446     a = _tracks.get(track_id, None)
447     if not a:
448         q = GetQuery('track', track_id)
449         a = q.execute()
450         if not a:
451             raise JamendoAPIException(str(q))
452         _update_cache(_tracks, a)
453         if isinstance(a, list):
454             a = a[0]
455     return a
456
457 def get_radio_tracks(radio_id):
458     """Returns: [Track]"""
459     q = GetQuery('radio', radio_id)
460     a = q.execute()
461     if not a:
462         raise JamendoAPIException(str(q))
463     _update_cache(_tracks, a)
464     return a
465
466 def search_artists(query):
467     """Returns: [Artist]"""
468     q = SearchQuery('artist', query, 'searchweight_desc')
469     a = q.execute()
470     if not a:
471         raise JamendoAPIException(str(q))
472     _update_cache(_artists, a)
473     return a
474
475 def search_albums(query):
476     """Returns: [Album]"""
477     q = SearchQuery('album', query, 'searchweight_desc')
478     a = q.execute()
479     if not a:
480         raise JamendoAPIException(str(q))
481     _update_cache(_albums, a)
482     return a
483
484 def search_tracks(query):
485     """Returns: [Track]"""
486     q = SearchQuery('track', query=query, order='searchweight_desc')
487     a = q.execute()
488     if not a:
489         raise JamendoAPIException(str(q))
490     _update_cache(_tracks, a)
491     return a
492
493 def albums_of_the_week():
494     """Returns: [Album]"""
495     q = SearchQuery('album', order='ratingweek_desc')
496     a = q.execute()
497     if not a:
498         raise JamendoAPIException(str(q))
499     _update_cache(_albums, a)
500     return a
501
502 def new_releases():
503     """Returns: [Track] (playlist)"""
504     q = SearchQuery('track', order='releasedate_desc')
505     a = q.execute()
506     if not a:
507         raise JamendoAPIException(str(q))
508     _update_cache(_tracks, a)
509     return a
510
511 def tracks_of_the_week():
512     """Returns: [Track] (playlist)"""
513     q = SearchQuery('track', order='ratingweek_desc')
514     a = q.execute()
515     if not a:
516         raise JamendoAPIException(str(q))
517     _update_cache(_tracks, a)
518     return a
519
520 def get_radio(radio_id):
521     """Returns: Radio"""
522     q = CustomQuery(_GET2+"id+name+idstr+image/radio/json?id=%d"%(radio_id))
523     js = q.execute()
524     if not js:
525         raise JamendoAPIException(str(q))
526     if isinstance(js, list):
527         ks = js[0]
528     return Radio(radio_id, json=js)
529
530 def starred_radios():
531     """Returns: [Radio]"""
532     q = CustomQuery(_GET2+"id+name+idstr+image/radio/json?order=starred_desc")
533     js = q.execute()
534     if not js:
535         raise JamendoAPIException(str(q))
536     return [Radio(int(radio['id']), json=radio) for radio in js]
537
538 def favorite_albums(user):
539     """Returns: [Album]"""
540     q = SearchQuery('favorite_albums', user=user, count=20)
541     a = q.execute()
542     if not a:
543         raise JamendoAPIException(str(q))
544     _update_cache(_albums, a)
545     return a
546
547 ### Set loader functions for classes
548
549 def _artist_loader(self):
550     if self._needs_load():
551         artist = get_artist(self.ID)
552         self._set_from(artist)
553 Artist.load = _artist_loader
554
555 def _album_loader(self):
556     if self._needs_load():
557         album = get_album(self.ID)
558         album.tracks = get_tracks(self.ID)
559         self._set_from(album)
560 Album.load = _album_loader
561
562 def _track_loader(self):
563     track = get_track(self.ID)
564     self._set_from(track)
565 Track.load = _track_loader
566
567 def _radio_loader(self):
568     radio = get_radio(self.ID)
569     self._set_from(radio)
570 Radio.load = _radio_loader