def get_reviews(self, results=15, start=0, cache=True):
"""Get reviews related to an artist's work
Args:
Kwargs:
cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of review document dicts; list contains additional attributes 'start' and 'total'
Example:
>>> a = artist.Artist('Ennio Morricone')
>>> reviews = a.reviews
>>> reviews.total
17
>>> reviews[0]['release']
u'For A Few Dollars More'
>>>
"""
if cache and ('reviews' in self.cache) and results==15 and start==0:
return self.cache['reviews']
else:
response = self.get_attribute('reviews', results=results, start=start)
if results==15 and start==0:
self.cache['reviews'] = ResultList(response['reviews'], 0, response['total'])
return ResultList(response['reviews'], start, response['total'])
def get_video(self, results=15, start=0, cache=True):
"""Get a list of video documents found on the web related to an artist
Args:
Kwargs:
cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of video document dicts; list contains additional attributes 'start' and 'total'
Example:
>>> a = artist.Artist('the vapors')
>>> a.get_video(results=1, start=2)
[{u'date_found': u'2009-12-28T08:27:48',
u'id': u'd02f9e6dc7904f70402d4676516286b9',
u'image_url': u'http://i1.ytimg.com/vi/p6c0wOFL3Us/default.jpg',
u'site': u'youtube',
u'title': u'The Vapors-Turning Japanese (rectangular white vinyl promo)',
u'url': u'http://youtube.com/watch?v=p6c0wOFL3Us'}]
>>>
"""
if cache and ('video' in self.cache) and results==15 and start==0:
return self.cache['video']
else:
response = self.get_attribute('video', results=results, start=start)
if results==15 and start==0:
self.cache['video'] = ResultList(response['video'], 0, response['total'])
return ResultList(response['video'], start, response['total'])
def get_news(self, results=15, start=0, cache=True, high_relevance=False):
"""Get a list of news articles found on the web related to an artist
Args:
cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of news document dicts; list contains additional attributes 'start' and 'total'
Example:
>>> a = artist.Artist('Henry Threadgill')
>>> news = a.news
>>> news.total
41
>>> news[0]['name']
u'Jazz Journalists Association Announces 2010 Jazz Award Winners'
>>>
"""
if cache and ('news' in self.cache) and results==15 and start==0 and not high_relevance:
return self.cache['news']
else:
high_relevance = 'true' if high_relevance else 'false'
response = self.get_attribute('news', results=results, start=start, high_relevance=high_relevance)
if results==15 and start==0:
self.cache['news'] = ResultList(response['news'], 0, response['total'])
return ResultList(response['news'], start, response['total'])
def get_images(self, results=15, start=0, license=None, cache=True):
"""Get a list of artist images
Args:
cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results (int): An integer number of results to return
start (int): An integer starting value for the result set
license (str): A string specifying the desired license type
Returns:
A list of image document dicts; list contains additional attributes 'start' and 'total'
Example:
>>> a = artist.Artist('Captain Beefheart')
>>> images = a.get_images(results=1)
>>> images.total
49
>>> images[0]['url']
u'http://c4.ac-images.myspacecdn.com/images01/5/l_e1a329cdfdb16a848288edc6d578730f.jpg'
>>>
"""
if cache and ('images' in self.cache) and results==15 and start==0 and license==None:
return self.cache['images']
else:
response = self.get_attribute('images', results=results, start=start, license=license)
total = response.get('total') or 0
if results==15 and start==0 and license==None:
self.cache['images'] = ResultList(response['images'], 0, total)
return ResultList(response['images'], start, total)
def get_biographies(self, results=15, start=0, license=None, cache=True):
"""Get a list of artist biographies
Args:
Kwargs:
cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results (int): An integer number of results to return
start (int): An integer starting value for the result set
license (str): A string specifying the desired license type
Returns:
A list of biography document dicts; list contains additional attributes 'start' and 'total'
Example:
>>> a = artist.Artist('britney spears')
>>> bio = a.get_biographies(results=1)[0]
>>> bio['url']
u'http://www.mtvmusic.com/spears_britney'
>>>
"""
if cache and ('biographies' in self.cache) and results==15 and start==0 and license==None:
return self.cache['biographies']
else:
response = self.get_attribute('biographies', results=results, start=start, license=license)
if results==15 and start==0 and license==None:
self.cache['biographies'] = ResultList(response['biographies'], 0, response['total'])
return ResultList(response['biographies'], start, response['total'])
def get_songs(self, cache=True, results=15, start=0):
"""Get the songs associated with an artist
Args:
Kwargs:
cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Results:
A list of Song objects; list contains additional attributes 'start' and 'total'
Example:
>>> a = artist.Artist('Strokes')
>>> a.get_songs(results=5)
[<song - Fear Of Sleep>, <song - Red Light>, <song - Ize Of The World>, <song - Evening Sun>, <song - Juicebox>]
>>>
"""
if cache and ('songs' in self.cache) and results == 15 and start == 0:
return self.cache['songs']
else:
response = self.get_attribute('songs',
results=results,
start=start)
for s in response['songs']:
s.update({'artist_id': self.id, 'artist_name': self.name})
songs = [Song(**util.fix(s)) for s in response['songs']]
if results == 15 and start == 0:
self.cache['songs'] = ResultList(songs, 0, response['total'])
return ResultList(songs, start, response['total'])
def read_items(self, buckets=None, results=15, start=0):
"""
Returns data from the catalog; also expanded for the requested buckets
Args:
Kwargs:
buckets (list): A list of strings specifying which buckets to retrieve
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of objects in the catalog; list contains additional attributes 'start' and 'total'
Example:
>>> c
<catalog - my_songs>
>>> c.read_items(results=1)
[<song - Harmonice Mundi II>]
>>>
"""
kwargs = {}
kwargs['bucket'] = buckets or []
response = self.get_attribute("read", results=results, start=start, **kwargs)
rval = ResultList([])
rval.start = response['catalog']['start']
rval.total = response['catalog']['total']
for item in response['catalog']['items']:
new_item = None
# song item
if 'song_id' in item:
item['id'] = item.pop('song_id')
item['title'] = item.pop('song_name')
request = item['request']
new_item = song.Song(**util.fix(item))
new_item.request = request
# artist item
elif 'artist_id' in item:
item['id'] = item.pop('artist_id')
item['name'] = item.pop('artist_name')
request = item['request']
new_item = artist.Artist(**util.fix(item))
new_item.request = request
# unresolved item
else:
new_item = item
rval.append(new_item)
return rval
def get_item_dicts(self, buckets=None, results=15, start=0,item_ids=None):
"""
Returns data from the catalog; also expanded for the requested buckets
Args:
Kwargs:
buckets (list): A list of strings specifying which buckets to retrieve
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of dicts representing objects in the catalog; list has additional attributes 'start' and 'total'
Example:
>>> c
<catalog - my_songs>
>>> c.read_items(results=1)
[
{
"artist_id": "AR78KRI1187B98E6F2",
"artist_name": "Art of Noise",
"date_added": "2012-04-02T16:50:02",
"foreign_id": "CAHLYLR13674D1CF83:song:1000",
"request": {
"artist_name": "The Art Of Noise",
"item_id": "1000",
"song_name": "Love"
},
"song_id": "SOSBCTO1311AFE7AE0",
"song_name": "Love"
}
]
"""
kwargs = {}
kwargs['bucket'] = buckets or []
kwargs['item_id'] = item_ids or []
response = self.get_attribute("read", results=results, start=start, **kwargs)
rval = ResultList(response['catalog']['items'])
if item_ids:
rval.start=0;
rval.total=len(response['catalog']['items'])
else:
rval.start = response['catalog']['start']
rval.total = response['catalog']['total']
return rval
def read_items(self, buckets=None, results=15, start=0, item_ids=None):
"""
Returns data from the catalog; also expanded for the requested buckets
Args:
Kwargs:
buckets (list): A list of strings specifying which buckets to retrieve
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of objects in the catalog; list contains additional attributes 'start' and 'total'
Example:
>>> c
<catalog - my_songs>
>>> c.read_items(results=1)
[<song - Harmonice Mundi II>]
>>>
"""
kwargs = {}
kwargs['bucket'] = buckets or []
kwargs['item_id'] = item_ids or []
response = self.get_attribute("read",
results=results,
start=start,
**kwargs)
rval = ResultList([])
if item_ids:
rval.start = 0
rval.total = len(response['catalog']['items'])
else:
rval.start = response['catalog']['start']
rval.total = response['catalog']['total']
for item in response['catalog']['items']:
new_item = None
# song items
if 'song_id' in item:
item['id'] = item.pop('song_id')
item['title'] = item.pop('song_name')
request = item['request']
new_item = song.Song(**util.fix(item))
new_item.request = request
# artist item
elif 'artist_id' in item:
item['id'] = item.pop('artist_id')
item['name'] = item.pop('artist_name')
request = item['request']
new_item = artist.Artist(**util.fix(item))
new_item.request = request
# unresolved item
else:
new_item = item
rval.append(new_item)
return rval
def list_catalogs(results=30, start=0):
"""
Returns list of all catalogs created on this API key
Args:
Kwargs:
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of catalog objects
Example:
>>> catalog.list()
[<catalog - test_artist_catalog>, <catalog - test_song_catalog>, <catalog - my_songs>]
>>>
"""
result = util.callm("%s/%s" % ('catalog', 'list'), {
'results': results,
'start': start
})
cats = [Catalog(**util.fix(d)) for d in result['response']['catalogs']]
start = result['response']['start']
total = result['response']['total']
return ResultList(cats, start, total)
def list(sandbox_name, results=15, start=0):
"""
Returns a list of all assets available in this sandbox
Args:
sandbox_name (str): A string representing the name of the sandbox
Kwargs:
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of asset dictionaries
Example:
>>> sandbox.list('bluenote')
[{}, {}]
>>>
"""
result = util.callm("%s/%s" % ('sandbox', 'list'), {
'sandbox': sandbox_name,
'results': results,
'start': start
})
assets = result['response']['assets']
start = result['response']['start']
total = result['response']['total']
return ResultList(assets, start, total)
def get_blogs(self, results=15, start=0, cache=True, high_relevance=False):
"""Get a list of blog articles related to an artist
Args:
Kwargs:
cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results (int): An integer number of results to return
start (int): An ingteger starting value for the result set
Returns:
A list of blog document dicts; list contains additional attributes 'start' and 'total'
Example:
>>> a = artist.Artist('bob marley')
>>> blogs = a.get_blogs(results=1,start=4)
>>> blogs.total
4068
>>> blogs[0]['summary']
But the Kenyans I know relate to music about the same way Americans do. They like their Congolese afropop,
and I've known some to be big fans of international acts like <span>Bob</span> <span>Marley</span> and Dolly Parton.
They rarely talk about music that's indigenous in the way a South African or Malian or Zimbabwean would, and it's
even rarer to actually hear such indigenous music. I do sometimes hear ceremonial chanting from the Maasai, but only
when they're dancing for tourists. If East Africa isn't the most musical part ... "
>>>
"""
if cache and (
'blogs' in self.cache
) and results == 15 and start == 0 and not high_relevance:
return self.cache['blogs']
else:
if high_relevance:
high_relevance = 'true'
else:
high_relevance = 'false'
response = self.get_attribute('blogs',
results=results,
start=start,
high_relevance=high_relevance)
if results == 15 and start == 0:
self.cache['blogs'] = ResultList(response['blogs'], 0,
response['total'])
return ResultList(response['blogs'], start, response['total'])
def get_audio(self, results=15, start=0, cache=True):
"""Get a list of audio documents found on the web related to an artist
Args:
Kwargs:
cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of audio document dicts; list contains additional attributes 'start' and 'total'
Example:
>>> a = artist.Artist('alphabeat')
>>> a.get_audio()[0]
{u'artist': u'Alphabeat',
u'date': u'2010-04-28T01:40:45',
u'id': u'70be4373fa57ac2eee8c7f30b0580899',
u'length': 210.0,
u'link': u'http://iamthecrime.com',
u'release': u'The Beat Is...',
u'title': u'DJ',
u'url': u'http://iamthecrime.com/wp-content/uploads/2010/04/03_DJ_iatc.mp3'}
>>>
"""
if cache and ('audio' in self.cache) and results == 15 and start == 0:
return self.cache['audio']
else:
response = self.get_attribute('audio',
results=results,
start=start)
if results == 15 and start == 0:
self.cache['audio'] = ResultList(response['audio'], 0,
response['total'])
return ResultList(response['audio'], start, response['total'])
def get_item_dicts(self, buckets=None, results=15, start=0, item_ids=None):
"""
Returns data from the catalog; also expanded for the requested buckets
Args:
Kwargs:
buckets (list): A list of strings specifying which buckets to retrieve
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of dicts representing objects in the catalog; list has additional attributes 'start' and 'total'
Example:
>>> c
<catalog - my_songs>
>>> c.read_items(results=1)
[
{
"artist_id": "AR78KRI1187B98E6F2",
"artist_name": "Art of Noise",
"date_added": "2012-04-02T16:50:02",
"foreign_id": "CAHLYLR13674D1CF83:song:1000",
"request": {
"artist_name": "The Art Of Noise",
"item_id": "1000",
"song_name": "Love"
},
"song_id": "SOSBCTO1311AFE7AE0",
"song_name": "Love"
}
]
"""
kwargs = {}
kwargs['bucket'] = buckets or []
kwargs['item_id'] = item_ids or []
response = self.get_attribute("read",
results=results,
start=start,
**kwargs)
rval = ResultList(response['catalog']['items'])
if item_ids:
rval.start = 0
rval.total = len(response['catalog']['items'])
else:
rval.start = response['catalog']['start']
rval.total = response['catalog']['total']
return rval
def get_feed(self, buckets=None, since=None, results=15, start=0):
"""
Returns feed (news, blogs, reviews, audio, video) for the catalog artists; response depends on requested buckets
Args:
Kwargs:
buckets (list): A list of strings specifying which feed items to retrieve
results (int): An integer number of results to return
start (int): An integer starting value for the result set
Returns:
A list of news, blogs, reviews, audio or video document dicts;
Example:
>>> c
<catalog - my_artists>
>>> c.get_feed(results=15)
{u'date_found': u'2011-02-06T07:50:25',
u'date_posted': u'2011-02-06T07:50:23',
u'id': u'caec686c0dff361e4c53dceb58fb9d2f',
u'name': u'Linkin Park \u2013 \u201cWaiting For The End\u201d + \u201cWhen They Come For Me\u201d 2/5 SNL',
u'references': [{u'artist_id': u'ARQUMH41187B9AF699',
u'artist_name': u'Linkin Park'}],
u'summary': u'<span>Linkin</span> <span>Park</span> performed "Waiting For The End" and "When They Come For Me" on Saturday Night Live. Watch the videos below and pick up their album A Thousand Suns on iTunes, Amazon MP3, CD Social Bookmarking ... ',
u'type': u'blogs',
u'url': u'http://theaudioperv.com/2011/02/06/linkin-park-waiting-for-the-end-when-they-come-for-me-25-snl/'}
>>>
"""
kwargs = {}
kwargs['bucket'] = buckets or []
if since:
kwargs['since'] = since
response = self.get_attribute("feed",
results=results,
start=start,
**kwargs)
rval = ResultList(response['feed'])
return rval
