Background loading, initially implemented for search window
[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 #
12 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
13 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
14 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
15 # DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
16 # DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
17 # (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
18 # LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
19 # ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
20 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
21 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
22
23 # An improved, structured jamendo API wrapper for the N900 with cacheing
24 # Image / cover downloads.. and more?
25 from __future__ import with_statement
26 import urllib, threading, os, time, simplejson, re
27 import logging, hashlib
28 import pycurl, StringIO
29
30 _CACHEDIR = None
31 _COVERDIR = None
32 _GET2 = '''http://api.jamendo.com/get2/'''
33 _MP3URL = _GET2+'stream/track/redirect/?id=%d&streamencoding=mp31'
34 _OGGURL = _GET2+'stream/track/redirect/?id=%d&streamencoding=ogg2'
35 _TORRENTURL = _GET2+'bittorrent/file/redirect/?album_id=%d&type=archive&class=mp32'
36
37 try:
38     log = logging.getLogger(__name__)
39 except:
40     class StdoutLogger(object):
41         def info(self, s, *args):
42             print s % (args)
43         def debug(self, s, *args):
44             pass#print s % (args)
45     log = StdoutLogger()
46
47 # These classes can be partially constructed,
48 # and if asked for a property they don't know,
49 # makes a query internally to get the full story
50
51 _ARTIST_FIELDS = ['id', 'name', 'image']
52 _ALBUM_FIELDS = ['id', 'name', 'image', 'artist_name', 'artist_id', 'license_url']
53 _TRACK_FIELDS = ['id', 'name', 'album_image', 'artist_id', 'artist_name', 'album_name', 'album_id', 'numalbum', 'duration']
54 _RADIO_FIELDS = ['id', 'name', 'idstr', 'image']
55 _TAG_FIELDS = ['id', 'name']
56
57 _APILOCK = threading.Lock()
58
59 def curlGET(url):
60     c = pycurl.Curl()
61     s = StringIO.StringIO()
62     c.setopt(pycurl.FOLLOWLOCATION, 1)
63     c.setopt(pycurl.URL, url)
64     c.setopt(pycurl.WRITEFUNCTION, s.write)
65     try:
66         c.perform()
67     finally:
68         c.close()
69     s.seek(0)
70     return s.read()
71
72 class LazyQuery(object):
73     def set_from_json(self, json):
74         for key, value in json.iteritems():
75             if key == 'id':
76                 assert(self.ID == int(value))
77             else:
78                 if key.endswith('_id'):
79                     value = int(value)
80                 setattr(self, key, value)
81
82     def load(self):
83         """Not automatic for now,
84         will have to do artist.load()
85
86         This is filled in further down
87         in the file
88         """
89         raise NotImplemented
90
91     def _needs_load(self):
92         return True
93
94     def _set_from(self, other):
95         raise NotImplemented
96
97     def _needs_load_impl(self, *attrs):
98         for attr in attrs:
99             if getattr(self, attr) is None:
100                 return True
101         return False
102
103     def _set_from_impl(self, other, *attrs):
104         for attr in attrs:
105             self._set_if(other, attr)
106
107     def _set_if(self, other, attrname):
108         if getattr(self, attrname) is None and getattr(other, attrname) is not None:
109             setattr(self, attrname, getattr(other, attrname))
110
111     def __repr__(self):
112         try:
113             return u"%s(%s)"%(self.__class__.__name__,
114                               u", ".join(("%s:%s"%(k,repr(v))) for k,v in self.__dict__.iteritems() if not k.startswith('_')))
115         except UnicodeEncodeError:
116             #import traceback
117             #traceback.print_exc()
118             return u"%s(?)"%(self.__class__.__name__)
119
120 class Artist(LazyQuery):
121     def __init__(self, ID, json=None):
122         self.ID = int(ID)
123         self.name = None
124         self.image = None
125         self.albums = None # None means not downloaded
126         if json:
127             self.set_from_json(json)
128
129     def _needs_load(self):
130         return self._needs_load_impl('name', 'albums')
131
132     def _set_from(self, other):
133         return self._set_from_impl(other, 'name', 'image', 'albums')
134
135     def get_data(self):
136         return {'name':self.name, 'image':self.image}
137
138 class Album(LazyQuery):
139     def __init__(self, ID, json=None):
140         self.ID = int(ID)
141         self.name = None
142         self.image = None
143         self.artist_name = None
144         self.artist_id = None
145         self.license_url = None
146         self.tracks = None # None means not downloaded
147         if json:
148             self.set_from_json(json)
149
150     def torrent_url(self):
151         return _TORRENTURL%(self.ID)
152
153
154     def _needs_load(self):
155         return self._needs_load_impl('name', 'image', 'artist_name', 'artist_id', 'license_url', 'tracks')
156
157     def _set_from(self, other):
158         return self._set_from_impl(other, 'name', 'image', 'artist_name', 'artist_id', 'license_url', 'tracks')
159
160     def get_data(self):
161         return {'name':self.name, 'image':self.image,
162                 'artist_name':self.artist_name,
163                 'artist_id':self.artist_id,
164                 'license_url':self.license_url}
165
166 class Track(LazyQuery):
167     def __init__(self, ID, json=None):
168         self.ID = int(ID)
169         self.name = None
170         self.artist_id = None
171         self.artist_name = None
172         self.album_image = None
173         self.album_name = None
174         self.album_id = None
175         self.numalbum = None
176         self.duration = None
177         if json:
178             self.set_from_json(json)
179
180     def mp3_url(self):
181        return _MP3URL%(self.ID)
182
183     def ogg_url(self):
184        return _OGGURL%(self.ID)
185
186     def get_data(self):
187         return {'name':self.name,
188                 'artist_id':self.artist_id,
189                 'artist_name':self.artist_name,
190                 'album_image':self.album_image,
191                 'album_name':self.album_name,
192                 'album_id':self.album_id,
193                 'numalbum':self.numalbum,
194                 'duration':self.duration}
195
196     def _needs_load(self):
197         return self._needs_load_impl('name', 'artist_name', 'artist_id', 'album_name', 'album_id', 'numalbum', 'duration')
198
199     def _set_from(self, other):
200         return self._set_from_impl(other, 'name', 'album_image', 'artist_name', 'artist_id', 'album_name', 'album_id', 'numalbum', 'duration')
201
202 class Radio(LazyQuery):
203     def __init__(self, ID, json=None):
204         self.ID = int(ID)
205         self.name = None
206         self.idstr = None
207         self.image = None
208         if json:
209             self.set_from_json(json)
210
211     def _needs_load(self):
212         return self._needs_load_impl('name', 'idstr', 'image')
213
214     def _set_from(self, other):
215         return self._set_from_impl(other, 'name', 'idstr', 'image')
216
217 class Tag(LazyQuery):
218     def __init__(self, ID, json=None):
219         self.ID = int(ID)
220         self.name = None
221         if json:
222             self.set_from_json(json)
223
224     def _needs_load(self):
225         return self._needs_load_impl('name')
226
227     def _set_from(self, other):
228         return self._set_from_impl(other, 'name')
229
230 _artists = {} # id -> Artist()
231 _albums = {} # id -> Album()
232 _tracks = {} # id -> Track()
233 _radios = {} # id -> Radio()
234
235
236 # cache sizes per session (TODO)
237 _CACHED_ARTISTS = 100
238 _CACHED_ALBUMS = 200
239 _CACHED_TRACKS = 500
240 _CACHED_RADIOS = 10
241 # cache sizes, persistant
242 _CACHED_COVERS = 2048
243
244 # TODO: cache queries?
245
246 class Ratelimit(object):
247     rate_limit = 1.0 # seconds between queries
248     last_query = time.time() - 1.5
249
250     @classmethod
251     def ratelimit(cls):
252         now = time.time()
253         if (now - cls.last_query) < cls.rate_limit:
254             time.sleep(cls.rate_limit - (now - cls.last_query))
255         cls.last_query = time.time()
256
257 _ratelimit = Ratelimit.ratelimit
258
259 class Query(object):
260     def __init__(self):
261         pass
262
263     def _geturl(self, url):
264         _ratelimit()
265         log.info("%s", url)
266         try:
267             ret = simplejson.loads(curlGET(url))
268         except Exception, e:
269             return None
270         return ret
271
272     def __str__(self):
273         return "#%s" % (self.__class__.__name__)
274
275     def execute(self):
276         raise NotImplemented
277
278 class CoverFetcher(threading.Thread):
279     def __init__(self):
280         threading.Thread.__init__(self)
281         self.setDaemon(True)
282         self.cond = threading.Condition()
283         self.work = []
284
285     def _retrieve(self, url, fname):
286         BROKEN = 'http://imgjam.com/radios/default/default.100.png'
287         if url == BROKEN:
288             return None
289         f = open(fname, 'wb')
290         c = pycurl.Curl()
291         c.setopt(pycurl.FOLLOWLOCATION, 1)
292         c.setopt(pycurl.URL, str(url))
293         c.setopt(pycurl.WRITEFUNCTION, f.write)
294         try:
295             c.perform()
296         except:
297             fname = None
298         finally:
299             c.close()
300             f.close()
301         log.debug("Coverfetch: %s -> %s", url, fname)
302         return fname
303
304     def _fetch_cover(self, albumid, size):
305         try:
306             coverdir = _COVERDIR if _COVERDIR else '/tmp'
307             to = os.path.join(coverdir, '%d-%d.jpg'%(albumid, size))
308             if not os.path.isfile(to):
309                 url = _GET2+'image/album/redirect/?id=%d&imagesize=%d'%(albumid, size)
310                 to = self._retrieve(url, to)
311             return to
312         except Exception, e:
313             return None
314
315     def _fetch_image(self, url):
316         try:
317             h = hashlib.md5(url).hexdigest()
318             coverdir = _COVERDIR if _COVERDIR else '/tmp'
319             to = os.path.join(coverdir, h+'.jpg')
320             if not os.path.isfile(to):
321                 to = self._retrieve(url, to)
322             return to
323         except Exception, e:
324             return None
325
326     def request_cover(self, albumid, size, cb):
327         self.cond.acquire()
328         self.work.insert(0, (albumid, size, cb))
329         self.cond.notify()
330         self.cond.release()
331
332     def request_images(self, urls, cb):
333         """cb([(url, image)])"""
334         self.cond.acquire()
335         self.work = [('image', url, cb) for url in urls] + self.work
336         self.cond.notify()
337         self.cond.release()
338
339     def run(self):
340         while True:
341             work = []
342             self.cond.acquire()
343             while True:
344                 work = self.work
345                 if work:
346                     self.work = []
347                     break
348                 self.cond.wait()
349             self.cond.release()
350
351             multi = len(work) > 1
352             for job in work:
353                 if job[0] == 'image':
354                     self.process_image(job[1], job[2])
355                 else:
356                     self.process_cover(*job)
357
358     def process_cover(self, albumid, size, cb):
359         cover = self._fetch_cover(albumid, size)
360         if cover:
361             cb(albumid, size, cover)
362
363     def process_image(self, url, cb):
364         image = self._fetch_image(url)
365         if image:
366             cb([(url, image)])
367
368 class CoverCache(object):
369     """
370     cache and fetch covers
371     TODO: background thread that
372     fetches and returns covers,
373     asynchronously, LIFO
374     """
375     def __init__(self):
376         self._covers = {} # (albumid, size) -> file
377         self._images = {}
378         self._fetcher = CoverFetcher()
379         self._fetcher.start()
380         if _COVERDIR and os.path.isdir(_COVERDIR):
381             self.prime_cache()
382
383     def prime_cache(self):
384         coverdir = _COVERDIR
385         covermatch = re.compile(r'(\d+)\-(\d+)\.jpg')
386
387         prev_covers = os.listdir(coverdir)
388
389         if len(prev_covers) > _CACHED_COVERS:
390             import random
391             dropn = len(prev_covers) - _CACHED_COVERS
392             todrop = random.sample(prev_covers, dropn)
393             log.warning("Deleting from cache: %s", todrop)
394             for d in todrop:
395                 m = covermatch.match(d)
396                 if m:
397                     try:
398                         os.unlink(os.path.join(coverdir, d))
399                     except OSError, e:
400                         log.exception('unlinking failed')
401
402         for fil in os.listdir(coverdir):
403             fl = os.path.join(coverdir, fil)
404             m = covermatch.match(fil)
405             if m and os.path.isfile(fl):
406                 self._covers[(int(m.group(1)), int(m.group(2)))] = fl
407
408     def fetch_cover(self, albumid, size):
409         coverdir = _COVERDIR
410         if coverdir:
411             to = os.path.join(coverdir, '%d-%d.jpg'%(albumid, size))
412             if not os.path.isfile(to):
413                 url = _GET2+'image/album/redirect/?id=%d&imagesize=%d'%(albumid, size)
414                 urllib.urlretrieve(url, to)
415                 self._covers[(albumid, size)] = to
416             return to
417         return None
418
419     def get_cover(self, albumid, size):
420         cover = self._covers.get((albumid, size), None)
421         if not cover:
422             cover = self.fetch_cover(albumid, size)
423         return cover
424
425     def get_async(self, albumid, size, cb):
426         cover = self._covers.get((albumid, size), None)
427         if cover:
428             cb(albumid, size, cover)
429         else:
430             def cb2(albumid, size, cover):
431                 self._covers[(albumid, size)] = cover
432                 cb(albumid, size, cover)
433             self._fetcher.request_cover(albumid, size, cb2)
434
435     def get_images_async(self, url_list, cb):
436         found = []
437         lookup = []
438         for url in url_list:
439             image = self._images.get(url, None)
440             if image:
441                 found.append((url, image))
442             else:
443                 lookup.append(url)
444         if found:
445             cb(found)
446
447         if lookup:
448             def cb2(results):
449                 for url, image in results:
450                     self._images[url] = image
451                 cb(results)
452             self._fetcher.request_images(lookup, cb2)
453
454 _cover_cache = CoverCache()
455
456 def set_cache_dir(cachedir):
457     global _CACHEDIR
458     global _COVERDIR
459     _CACHEDIR = cachedir
460     _COVERDIR = os.path.join(_CACHEDIR, 'covers')
461
462     try:
463         os.makedirs(_CACHEDIR)
464     except OSError:
465         pass
466
467     try:
468         os.makedirs(_COVERDIR)
469     except OSError:
470         pass
471
472     _cover_cache.prime_cache()
473
474 def get_album_cover(albumid, size=100):
475     with _APILOCK:
476         return _cover_cache.get_cover(albumid, size)
477
478 def get_album_cover_async(cb, albumid, size=100):
479     with _APILOCK:
480         _cover_cache.get_async(albumid, size, cb)
481
482 def get_images_async(cb, url_list):
483     with _APILOCK:
484         _cover_cache.get_images_async(url_list, cb)
485
486 class CustomQuery(Query):
487     def __init__(self, url):
488         Query.__init__(self)
489         self.url = url
490
491     def execute(self):
492         return self._geturl(self.url)
493
494     def __str__(self):
495         return self.url
496
497 class GetQuery(Query):
498     queries = {
499         'artist' : {
500             'url' : _GET2+'+'.join(_ARTIST_FIELDS)+'/artist/json/?',
501             'params' : 'artist_id=%d',
502             'constructor' : Artist
503             },
504         'artist_list' : {
505             'url' : _GET2+'+'.join(_ALBUM_FIELDS)+'/artist/json/?',
506             'params' : 'artist_id=%s',
507             'constructor' : Album
508             },
509         'album' : {
510             'url' : _GET2+'+'.join(_ALBUM_FIELDS)+'/album/json/?',
511             'params' : 'album_id=%d',
512             'constructor' : Album
513             },
514         'album_list' : {
515             'url' : _GET2+'+'.join(_ALBUM_FIELDS)+'/album/json/?',
516             'params' : 'album_id=%s',
517             'constructor' : Album
518             },
519         'albums' : {
520             'url' : _GET2+'+'.join(_ALBUM_FIELDS)+'/album/json/?',
521             'params' : 'artist_id=%d',
522             'constructor' : [Album]
523             },
524         'track' : {
525             'url' : _GET2+'+'.join(_TRACK_FIELDS)+'/track/json/track_album+album_artist?',
526             'params' : 'id=%d',
527             'constructor' : Track
528             },
529         'track_list' : {
530             'url' : _GET2+'+'.join(_TRACK_FIELDS)+'/track/json/track_album+album_artist?',
531             'params' : 'id=%s',
532             'constructor' : Track
533             },
534         'tracks' : {
535             'url' : _GET2+'+'.join(_TRACK_FIELDS)+'/track/json/track_album+album_artist?',
536             'params' : 'order=numalbum_asc&album_id=%d',
537             'constructor' : [Track]
538             },
539         'radio' : {
540             'url' : _GET2+'+'.join(_TRACK_FIELDS)+'/track/json/radio_track_inradioplaylist+track_album+album_artist/?',
541             'params' : 'order=random_asc&radio_id=%d&n=16',
542             'constructor' : [Track]
543             },
544         'favorite_albums' : {
545             'url' : _GET2+'+'.join(_ALBUM_FIELDS)+'/album/json/album_user_starred/?',
546             'params' : 'user_idstr=%s',
547             'constructor' : [Album]
548             },
549         'tag' : {
550             'url' : _GET2+'+'.join(_TRACK_FIELDS)+'/track/json/track_album+album_artist?',
551             'params' : 'tag_id=%d&n=50&order=rating_desc',
552             'constructor' : [Track]
553             },
554         }
555
556     def __init__(self, what, ID):
557         Query.__init__(self)
558         self.ID = ID
559         info = GetQuery.queries[what]
560         self.url = info['url']
561         self.params = info['params']
562         self.constructor = info['constructor']
563
564     def construct(self, data):
565         constructor = self.constructor
566         if isinstance(constructor, list):
567             constructor = constructor[0]
568         if isinstance(data, list):
569             return [constructor(int(x['id']), json=x) for x in data]
570         else:
571             return constructor(int(data['id']), json=data)
572
573     def execute(self):
574         js = self._geturl(self.url + self.params % (self.ID))
575         if not js:
576             return None
577         return self.construct(js)
578
579     def __str__(self):
580         return self.url + self.params % (self.ID)
581
582 class SearchQuery(GetQuery):
583     def __init__(self, what, query=None, order=None, user=None, count=20):
584         GetQuery.__init__(self, what, None)
585         self.query = query
586         self.order = order
587         self.count = count
588         self.user = user
589
590     def execute(self):
591         params = {}
592         if self.query:
593             params['searchquery'] = self.query
594         if self.order:
595             params['order'] = self.order
596         if self.count:
597             params['n'] = self.count
598         if self.user:
599             params['user_idstr'] = self.user
600         js = self._geturl(self.url +  urllib.urlencode(params))
601         if not js:
602             return None
603         return self.construct(js)
604
605     def __str__(self):
606         params = {'searchquery':self.query, 'order':self.order, 'n':self.count}
607         return self.url +  urllib.urlencode(params)
608
609 class JamendoAPIException(Exception):
610     def __init__(self, url):
611         Exception.__init__(self, url)
612
613 def _update_cache(cache, new_items):
614     if not isinstance(new_items, list):
615         new_items = [new_items]
616     for item in new_items:
617         old = cache.get(item.ID)
618         if old:
619             old._set_from(item)
620         else:
621             cache[item.ID] = item
622         if isinstance(item, Artist) and item.albums:
623             for album in item.albums:
624                 _update_cache(_albums, album)
625         elif isinstance(item, Album) and item.tracks:
626             for track in item.tracks:
627                 _update_cache(_tracks, track)
628     # enforce cache limits here!
629     # also, TODO: save/load cache between sessions
630     # that will require storing a timestamp with
631     # each item, though..
632     # perhaps,
633     # artists: 1 day - changes often
634     # albums: 2-5 days - changes less often (?)
635     # tracks: 1 week - changes rarely, queried often
636
637 def get_artist(artist_id):
638     """Returns: Artist"""
639     with _APILOCK:
640         a = _artists.get(artist_id, None)
641         if not a:
642             q = GetQuery('artist', artist_id)
643             a = q.execute()
644             if not a:
645                 raise JamendoAPIException(str(q))
646             _update_cache(_artists, a)
647             if isinstance(a, list):
648                 a = a[0]
649         return a
650
651 def get_artists(artist_ids):
652     """Returns: [Artist]"""
653     with _APILOCK:
654         assert(isinstance(artist_ids, list))
655         found = []
656         lookup = []
657         for artist_id in artist_ids:
658             a = _artists.get(artist_id, None)
659             if not a:
660                 lookup.append(artist_id)
661             else:
662                 found.append(a)
663         if lookup:
664             q = GetQuery('artist_list', '+'.join(str(x) for x in lookup))
665             a = q.execute()
666             if not a:
667                 raise JamendoAPIException(str(q))
668             _update_cache(_artists, a)
669             lookup = a
670         return found + lookup
671
672 def get_album_list(album_ids):
673     """Returns: [Album]"""
674     with _APILOCK:
675         assert(isinstance(album_ids, list))
676         found = []
677         lookup = []
678         for album_id in album_ids:
679             a = _albums.get(album_id, None)
680             if not a:
681                 lookup.append(album_id)
682             else:
683                 found.append(a)
684         if lookup:
685             q = GetQuery('album_list', '+'.join(str(x) for x in lookup))
686             a = q.execute()
687             if not a:
688                 raise JamendoAPIException(str(q))
689             _update_cache(_albums, a)
690             lookup = a
691         return found + lookup
692
693 def get_albums(artist_id):
694     """Returns: [Album]
695     Parameter can either be an artist_id or a list of album ids.
696     """
697     with _APILOCK:
698         if isinstance(artist_id, list):
699             return get_album_list(artist_id)
700         a = _artists.get(artist_id, None)
701         if a and a.albums:
702             return a.albums
703
704         q = GetQuery('albums', artist_id)
705         a = q.execute()
706         if not a:
707             raise JamendoAPIException(str(q))
708         _update_cache(_albums, a)
709         return a
710
711 def get_album(album_id):
712     """Returns: Album"""
713     with _APILOCK:
714         a = _albums.get(album_id, None)
715         if not a:
716             q = GetQuery('album', album_id)
717             a = q.execute()
718             if not a:
719                 raise JamendoAPIException(str(q))
720             _update_cache(_albums, a)
721             if isinstance(a, list):
722                 a = a[0]
723         return a
724
725 def get_track_list(track_ids):
726     """Returns: [Track]"""
727     with _APILOCK:
728         assert(isinstance(track_ids, list))
729         found = []
730         lookup = []
731         for track_id in track_ids:
732             a = _tracks.get(track_id, None)
733             if not a:
734                 lookup.append(track_id)
735             else:
736                 found.append(a)
737         if lookup:
738             q = GetQuery('track_list', '+'.join(str(x) for x in lookup))
739             a = q.execute()
740             if not a:
741                 raise JamendoAPIException(str(q))
742             _update_cache(_tracks, a)
743             lookup = a
744         return found + lookup
745
746 def get_tracks(album_id):
747     """Returns: [Track]
748     Parameter can either be an album_id or a list of track ids.
749     """
750     with _APILOCK:
751         if isinstance(album_id, list):
752             return get_track_list(album_id)
753         a = _albums.get(album_id, None)
754         if a and a.tracks:
755             return a.tracks
756
757         q = GetQuery('tracks', album_id)
758         a = q.execute()
759         if not a:
760             raise JamendoAPIException(str(q))
761         _update_cache(_tracks, a)
762         return a
763
764 def get_track(track_id):
765     """Returns: Track"""
766     with _APILOCK:
767         a = _tracks.get(track_id, None)
768         if not a:
769             q = GetQuery('track', track_id)
770             a = q.execute()
771             if not a:
772                 raise JamendoAPIException(str(q))
773             _update_cache(_tracks, a)
774             if isinstance(a, list):
775                 a = a[0]
776         return a
777
778 def get_radio_tracks(radio_id):
779     """Returns: [Track]"""
780     with _APILOCK:
781         q = GetQuery('radio', radio_id)
782         a = q.execute()
783         if not a:
784             raise JamendoAPIException(str(q))
785         _update_cache(_tracks, a)
786         return a
787
788 #http://api.jamendo.com/get2/id+name/track/plain/?tag_id=327&n=50&order=rating_desc
789 def get_tag_tracks(tag_id):
790     """Returns: [Track]"""
791     with _APILOCK:
792         q = GetQuery('tag', tag_id)
793         a = q.execute()
794         if not a:
795             raise JamendoAPIException(str(q))
796         _update_cache(_tracks, a)
797         return a
798
799 def search_artists(query):
800     """Returns: [Artist]"""
801     with _APILOCK:
802         q = SearchQuery('artist', query, 'searchweight_desc')
803         a = q.execute()
804         if not a:
805             raise JamendoAPIException(str(q))
806         _update_cache(_artists, a)
807         return a
808
809 def search_albums(query):
810     """Returns: [Album]"""
811     with _APILOCK:
812         q = SearchQuery('album', query, 'searchweight_desc')
813         a = q.execute()
814         if not a:
815             raise JamendoAPIException(str(q))
816         _update_cache(_albums, a)
817         return a
818
819 def search_tracks(query):
820     """Returns: [Track]"""
821     with _APILOCK:
822         q = SearchQuery('track', query=query, order='searchweight_desc')
823         a = q.execute()
824         if not a:
825             raise JamendoAPIException(str(q))
826         _update_cache(_tracks, a)
827         return a
828
829 def albums_of_the_week():
830     """Returns: [Album]"""
831     with _APILOCK:
832         q = SearchQuery('album', order='ratingweek_desc')
833         a = q.execute()
834         if not a:
835             raise JamendoAPIException(str(q))
836         _update_cache(_albums, a)
837         return a
838
839 def new_releases():
840     """Returns: [Track] (playlist)"""
841     with _APILOCK:
842         q = SearchQuery('track', order='releasedate_desc')
843         a = q.execute()
844         if not a:
845             raise JamendoAPIException(str(q))
846         _update_cache(_tracks, a)
847         return a
848
849 def tracks_of_the_week():
850     """Returns: [Track] (playlist)"""
851     with _APILOCK:
852         q = SearchQuery('track', order='ratingweek_desc')
853         a = q.execute()
854         if not a:
855             raise JamendoAPIException(str(q))
856         _update_cache(_tracks, a)
857         return a
858
859 def top_artists(order='rating_desc', count=20):
860     """Returns: [Artist]"""
861     with _APILOCK:
862         q = SearchQuery('artist', order=order, count=count)
863         a = q.execute()
864         if not a:
865             raise JamendoAPIException(str(q))
866         _update_cache(_artists, a)
867         return a
868
869 def top_albums(order='rating_desc', count=20):
870     """Returns: [Album]"""
871     with _APILOCK:
872         q = SearchQuery('album', order=order, count=count)
873         a = q.execute()
874         if not a:
875             raise JamendoAPIException(str(q))
876         _update_cache(_albums, a)
877         return a
878
879 def top_tracks(order='rating_desc', count=20):
880     """Returns: [Track]"""
881     with _APILOCK:
882         q = SearchQuery('track', order=order, count=count)
883         a = q.execute()
884         if not a:
885             raise JamendoAPIException(str(q))
886         _update_cache(_tracks, a)
887         return a
888
889 def get_radio(radio_id):
890     """Returns: Radio"""
891     with _APILOCK:
892         q = CustomQuery(_GET2+"id+name+idstr+image/radio/json?id=%d"%(radio_id))
893         js = q.execute()
894         if not js:
895             raise JamendoAPIException(str(q))
896         if isinstance(js, list):
897             ks = js[0]
898         return Radio(radio_id, json=js)
899
900 def starred_radios():
901     """Returns: [Radio]"""
902     with _APILOCK:
903         q = CustomQuery(_GET2+"id+name+idstr+image/radio/json?order=starred_desc")
904         js = q.execute()
905         if not js:
906             raise JamendoAPIException(str(q))
907         return [Radio(int(radio['id']), json=radio) for radio in js]
908
909 def top_tags(count=50, order='rating_desc'):
910     """Returns: [Tag]"""
911     with _APILOCK:
912         q = CustomQuery(_GET2+"id+name/tag/json?n=%d&order=%s"%(count, order))
913         js = q.execute()
914         if not js:
915             raise JamendoAPIException(str(q))
916         return [Tag(int(tag['id']), json=tag) for tag in js]
917
918 def favorite_albums(user):
919     """Returns: [Album]"""
920     with _APILOCK:
921         q = SearchQuery('favorite_albums', user=user, count=20)
922         a = q.execute()
923         if not a:
924             raise JamendoAPIException(str(q))
925         _update_cache(_albums, a)
926         return a
927
928 ### Set loader functions for classes
929
930 def _artist_loader(self):
931     if self._needs_load():
932         artist = get_artist(self.ID)
933         artist.albums = get_albums(self.ID)
934         self._set_from(artist)
935 Artist.load = _artist_loader
936
937 def _album_loader(self):
938     if self._needs_load():
939         album = get_album(self.ID)
940         album.tracks = get_tracks(self.ID)
941         self._set_from(album)
942 Album.load = _album_loader
943
944 def _track_loader(self):
945     track = get_track(self.ID)
946     self._set_from(track)
947 Track.load = _track_loader
948
949 def _radio_loader(self):
950     radio = get_radio(self.ID)
951     self._set_from(radio)
952 Radio.load = _radio_loader