1
2
3
4 """
5 Copyright (c) 2010 The Echo Nest. All rights reserved.
6 Created by Tyler Williams on 2010-04-25.
7
8 The Artist module loosely covers http://developer.echonest.com/docs/v4/artist.html
9 Refer to the official api documentation if you are unsure about something.
10 """
11 import util
12 from proxies import ArtistProxy, ResultList
13 from song import Song
14
15
17 """
18 An Artist object
19
20 Attributes:
21 id (str): Echo Nest Artist ID
22
23 name (str): Artist Name
24
25 audio (list): Artist audio
26
27 biographies (list): Artist biographies
28
29 blogs (list): Artist blogs
30
31 familiarity (float): Artist familiarity
32
33 hotttnesss (float): Artist hotttnesss
34
35 images (list): Artist images
36
37 news (list): Artist news
38
39 reviews (list): Artist reviews
40
41 similar (list): Similar Artists
42
43 songs (list): A list of song objects
44
45 terms (list): Terms for an artist
46
47 urls (list): Artist urls
48
49 video (list): Artist video
50
51 years_active (list): A list of dictionaries containing start and stop years
52
53 You create an artist object like this:
54
55 >>> a = artist.Artist('ARH6W4X1187B99274F')
56 >>> a = artist.Artist('the national')
57 >>> a = artist.Artist('musicbrainz:artist:a74b1b7f-71a5-4011-9441-d0b5e4122711')
58
59 """
60
62 """
63 Artist class
64
65 Args:
66 id (str): an artistw ID
67
68 Returns:
69 An artist object
70
71 Example:
72
73 >>> a = artist.Artist('ARH6W4X1187B99274F', buckets=['hotttnesss'])
74 >>> a.hotttnesss
75 0.80098515900997658
76 >>>
77
78 """
79 super(Artist, self).__init__(id, **kwargs)
80
82 return "<%s - %s>" % (self._object_type.encode('utf-8'), self.name.encode('utf-8'))
83
85 return self.name.encode('utf-8')
86
88 return cmp(self.id, other.id)
89
90 - def get_audio(self, results=15, start=0, cache=True):
91 """Get a list of audio documents found on the web related to an artist
92
93 Args:
94
95 Kwargs:
96 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
97
98 results (int): An integer number of results to return
99
100 start (int): An integer starting value for the result set
101
102 Returns:
103 A list of audio document dicts; list contains additional attributes 'start' and 'total'
104
105 Example:
106
107 >>> a = artist.Artist('alphabeat')
108 >>> a.get_audio()[0]
109 {u'artist': u'Alphabeat',
110 u'date': u'2010-04-28T01:40:45',
111 u'id': u'70be4373fa57ac2eee8c7f30b0580899',
112 u'length': 210.0,
113 u'link': u'http://iamthecrime.com',
114 u'release': u'The Beat Is...',
115 u'title': u'DJ',
116 u'url': u'http://iamthecrime.com/wp-content/uploads/2010/04/03_DJ_iatc.mp3'}
117 >>>
118 """
119
120 if cache and ('audio' in self.cache) and results==15 and start==0:
121 return self.cache['audio']
122 else:
123 response = self.get_attribute('audio', results=results, start=start)
124 if results==15 and start==0:
125 self.cache['audio'] = ResultList(response['audio'], 0, response['total'])
126 return ResultList(response['audio'], start, response['total'])
127
128 audio = property(get_audio)
129
131 """Get a list of artist biographies
132
133 Args:
134
135 Kwargs:
136 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
137
138 results (int): An integer number of results to return
139
140 start (int): An integer starting value for the result set
141
142 license (str): A string specifying the desired license type
143
144 Returns:
145 A list of biography document dicts; list contains additional attributes 'start' and 'total'
146
147 Example:
148
149 >>> a = artist.Artist('britney spears')
150 >>> bio = a.get_biographies(results=1)[0]
151 >>> bio['url']
152 u'http://www.mtvmusic.com/spears_britney'
153 >>>
154 """
155 if cache and ('biographies' in self.cache) and results==15 and start==0 and license==None:
156 return self.cache['biographies']
157 else:
158 response = self.get_attribute('biographies', results=results, start=start, license=license)
159 if results==15 and start==0 and license==None:
160 self.cache['biographies'] = ResultList(response['biographies'], 0, response['total'])
161 return ResultList(response['biographies'], start, response['total'])
162
163 biographies = property(get_biographies)
164
165 - def get_blogs(self, results=15, start=0, cache=True, high_relevance=False):
166 """Get a list of blog articles related to an artist
167
168 Args:
169
170 Kwargs:
171 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
172
173 results (int): An integer number of results to return
174
175 start (int): An ingteger starting value for the result set
176
177 Returns:
178 A list of blog document dicts; list contains additional attributes 'start' and 'total'
179
180 Example:
181
182 >>> a = artist.Artist('bob marley')
183 >>> blogs = a.get_blogs(results=1,start=4)
184 >>> blogs.total
185 4068
186 >>> blogs[0]['summary']
187 But the Kenyans I know relate to music about the same way Americans do. They like their Congolese afropop,
188 and I've known some to be big fans of international acts like <span>Bob</span> <span>Marley</span> and Dolly Parton.
189 They rarely talk about music that's indigenous in the way a South African or Malian or Zimbabwean would, and it's
190 even rarer to actually hear such indigenous music. I do sometimes hear ceremonial chanting from the Maasai, but only
191 when they're dancing for tourists. If East Africa isn't the most musical part ... "
192 >>>
193 """
194
195 if cache and ('blogs' in self.cache) and results==15 and start==0 and not high_relevance:
196 return self.cache['blogs']
197 else:
198 high_relevance = 'true' if high_relevance else 'false'
199 response = self.get_attribute('blogs', results=results, start=start, high_relevance=high_relevance)
200 if results==15 and start==0:
201 self.cache['blogs'] = ResultList(response['blogs'], 0, response['total'])
202 return ResultList(response['blogs'], start, response['total'])
203
204 blogs = property(get_blogs)
205
207 """Get our numerical estimation of how familiar an artist currently is to the world
208
209 Args:
210
211 Kwargs:
212 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
213
214 Returns:
215 A float representing familiarity.
216
217 Example:
218
219 >>> a = artist.Artist('frank sinatra')
220 >>> a.get_familiarity()
221 0.65142555825947457
222 >>> a.familiarity
223 0.65142555825947457
224 >>>
225 """
226 if not (cache and ('familiarity' in self.cache)):
227 response = self.get_attribute('familiarity')
228 self.cache['familiarity'] = response['artist']['familiarity']
229 return self.cache['familiarity']
230
231 familiarity = property(get_familiarity)
232
234 """Get the foreign id for this artist for a specific id space
235
236 Args:
237
238 Kwargs:
239 idspace (str): A string indicating the idspace to fetch a foreign id for.
240
241 Returns:
242 A foreign ID string
243
244 Example:
245
246 >>> a = artist.Artist('fabulous')
247 >>> a.get_foreign_id('7digital')
248 u'7digital:artist:186042'
249 >>>
250 """
251 if not (cache and ('foreign_ids' in self.cache) and filter(lambda d: d.get('catalog') == idspace, self.cache['foreign_ids'])):
252 response = self.get_attribute('profile', bucket=['id:'+idspace])
253 foreign_ids = response['artist'].get("foreign_ids", [])
254 self.cache['foreign_ids'] = self.cache.get('foreign_ids', []) + foreign_ids
255 cval = filter(lambda d: d.get('catalog') == idspace, self.cache.get('foreign_ids'))
256 return cval[0].get('foreign_id') if cval else None
257
259 """Get the twitter id for this artist if it exists
260
261 Args:
262
263 Kwargs:
264
265 Returns:
266 A twitter ID string
267
268 Example:
269
270 >>> a = artist.Artist('big boi')
271 >>> a.get_twitter_id()
272 u'BigBoi'
273 >>>
274 """
275 if not (cache and ('twitter' in self.cache)):
276 response = self.get_attribute('twitter')
277 self.cache['twitter'] = response['artist'].get('twitter')
278 return self.cache['twitter']
279
281 """Get our numerical description of how hottt an artist currently is
282
283 Args:
284
285 Kwargs:
286 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
287
288 Returns:
289 float: the hotttnesss value
290
291 Example:
292
293 >>> a = artist.Artist('hannah montana')
294 >>> a.get_hotttnesss()
295 0.59906022155998995
296 >>> a.hotttnesss
297 0.59906022155998995
298 >>>
299 """
300 if not (cache and ('hotttnesss' in self.cache)):
301 response = self.get_attribute('hotttnesss')
302 self.cache['hotttnesss'] = response['artist']['hotttnesss']
303 return self.cache['hotttnesss']
304
305 hotttnesss = property(get_hotttnesss)
306
307 - def get_images(self, results=15, start=0, license=None, cache=True):
308 """Get a list of artist images
309
310 Args:
311 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
312
313 results (int): An integer number of results to return
314
315 start (int): An integer starting value for the result set
316
317 license (str): A string specifying the desired license type
318
319 Returns:
320 A list of image document dicts; list contains additional attributes 'start' and 'total'
321
322 Example:
323
324 >>> a = artist.Artist('Captain Beefheart')
325 >>> images = a.get_images(results=1)
326 >>> images.total
327 49
328 >>> images[0]['url']
329 u'http://c4.ac-images.myspacecdn.com/images01/5/l_e1a329cdfdb16a848288edc6d578730f.jpg'
330 >>>
331 """
332
333 if cache and ('images' in self.cache) and results==15 and start==0 and license==None:
334 return self.cache['images']
335 else:
336 response = self.get_attribute('images', results=results, start=start, license=license)
337 if results==15 and start==0 and license==None:
338 self.cache['images'] = ResultList(response['images'], 0, response['total'])
339 return ResultList(response['images'], start, response['total'])
340
341 images = property(get_images)
342
343 - def get_news(self, results=15, start=0, cache=True, high_relevance=False):
344 """Get a list of news articles found on the web related to an artist
345
346 Args:
347 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
348
349 results (int): An integer number of results to return
350
351 start (int): An integer starting value for the result set
352
353 Returns:
354 A list of news document dicts; list contains additional attributes 'start' and 'total'
355
356 Example:
357
358 >>> a = artist.Artist('Henry Threadgill')
359 >>> news = a.news
360 >>> news.total
361 41
362 >>> news[0]['name']
363 u'Jazz Journalists Association Announces 2010 Jazz Award Winners'
364 >>>
365 """
366 if cache and ('news' in self.cache) and results==15 and start==0 and not high_relevance:
367 return self.cache['news']
368 else:
369 high_relevance = 'true' if high_relevance else 'false'
370 response = self.get_attribute('news', results=results, start=start, high_relevance=high_relevance)
371 if results==15 and start==0:
372 self.cache['news'] = ResultList(response['news'], 0, response['total'])
373 return ResultList(response['news'], start, response['total'])
374
375 news = property(get_news)
376
377 - def get_reviews(self, results=15, start=0, cache=True):
378 """Get reviews related to an artist's work
379
380 Args:
381
382 Kwargs:
383 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
384
385 results (int): An integer number of results to return
386
387 start (int): An integer starting value for the result set
388
389 Returns:
390 A list of review document dicts; list contains additional attributes 'start' and 'total'
391
392 Example:
393
394 >>> a = artist.Artist('Ennio Morricone')
395 >>> reviews = a.reviews
396 >>> reviews.total
397 17
398 >>> reviews[0]['release']
399 u'For A Few Dollars More'
400 >>>
401 """
402
403
404
405 if cache and ('reviews' in self.cache) and results==15 and start==0:
406 return self.cache['reviews']
407 else:
408 response = self.get_attribute('reviews', results=results, start=start)
409 if results==15 and start==0:
410 self.cache['reviews'] = ResultList(response['reviews'], 0, response['total'])
411 return ResultList(response['reviews'], start, response['total'])
412
413 reviews = property(get_reviews)
414
415 - def get_similar(self, results=15, start=0, buckets=None, limit=False, cache=True, max_familiarity=None, min_familiarity=None, \
416 max_hotttnesss=None, min_hotttnesss=None, min_results=None, reverse=False, artist_start_year_before=None, \
417 artist_start_year_after=None,artist_end_year_before=None,artist_end_year_after=None):
418 """Return similar artists to this one
419
420 Args:
421
422 Kwargs:
423 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
424
425 results (int): An integer number of results to return
426
427 start (int): An integer starting value for the result set
428
429 max_familiarity (float): A float specifying the max familiarity of artists to search for
430
431 min_familiarity (float): A float specifying the min familiarity of artists to search for
432
433 max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
434
435 min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
436
437 reverse (bool): A boolean indicating whether or not to return dissimilar artists (wrecommender). Defaults to False.
438
439 Returns:
440 A list of similar Artist objects
441
442 Example:
443
444 >>> a = artist.Artist('Sleater Kinney')
445 >>> similars = a.similar[:5]
446 >>> similars
447 [<artist - Bikini Kill>, <artist - Pretty Girls Make Graves>, <artist - Huggy Bear>, <artist - Bratmobile>, <artist - Team Dresch>]
448 >>>
449 """
450 buckets = buckets or []
451 kwargs = {}
452 if max_familiarity:
453 kwargs['max_familiarity'] = max_familiarity
454 if min_familiarity:
455 kwargs['min_familiarity'] = min_familiarity
456 if max_hotttnesss:
457 kwargs['max_hotttnesss'] = max_hotttnesss
458 if min_hotttnesss:
459 kwargs['min_hotttnesss'] = min_hotttnesss
460 if min_results:
461 kwargs['min_results'] = min_results
462 if buckets:
463 kwargs['bucket'] = buckets
464 if limit:
465 kwargs['limit'] = 'true'
466 if reverse:
467 kwargs['reverse'] = 'true'
468 if artist_start_year_before:
469 kwargs['artist_start_year_before'] = artist_start_year_before
470 if artist_start_year_after:
471 kwargs['artist_start_year_after'] = artist_start_year_after
472 if artist_end_year_before:
473 kwargs['artist_end_year_before'] = artist_end_year_before
474 if artist_end_year_after:
475 kwargs['artist_end_year_after'] = artist_end_year_after
476
477
478 if cache and ('similar' in self.cache) and results==15 and start==0 and (not kwargs):
479 return [Artist(**util.fix(a)) for a in self.cache['similar']]
480 else:
481 response = self.get_attribute('similar', results=results, start=start, **kwargs)
482 if results==15 and start==0 and (not kwargs):
483 self.cache['similar'] = response['artists']
484 return [Artist(**util.fix(a)) for a in response['artists']]
485
486 similar = property(get_similar)
487
488 - def get_songs(self, cache=True, results=15, start=0):
489 """Get the songs associated with an artist
490
491 Args:
492
493 Kwargs:
494 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
495
496 results (int): An integer number of results to return
497
498 start (int): An integer starting value for the result set
499
500 Results:
501 A list of Song objects; list contains additional attributes 'start' and 'total'
502
503 Example:
504
505 >>> a = artist.Artist('Strokes')
506 >>> a.get_songs(results=5)
507 [<song - Fear Of Sleep>, <song - Red Light>, <song - Ize Of The World>, <song - Evening Sun>, <song - Juicebox>]
508 >>>
509 """
510
511 if cache and ('songs' in self.cache) and results==15 and start==0:
512 if not isinstance(self.cache['songs'][0], Song):
513 song_objects = []
514 for s in self.cache["songs"]:
515 song_objects.append(Song(id=s['id'],
516 title=s['title'],
517 artist_name=self.name,
518 artist_id=self.id))
519 self.cache['songs'] = song_objects
520 return self.cache['songs']
521 else:
522 response = self.get_attribute('songs', results=results, start=start)
523 for s in response['songs']:
524 s.update({'artist_id':self.id, 'artist_name':self.name})
525 songs = [Song(**util.fix(s)) for s in response['songs']]
526 if results==15 and start==0:
527 self.cache['songs'] = ResultList(songs, 0, response['total'])
528 return ResultList(songs, start, response['total'])
529
530 songs = property(get_songs)
531
532 - def get_terms(self, sort='weight', cache=True):
533 """Get the terms associated with an artist
534
535 Args:
536
537 Kwargs:
538 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
539
540 sort (str): A string specifying the desired sorting type (weight or frequency)
541
542 Results:
543 A list of term document dicts
544
545 Example:
546
547 >>> a = artist.Artist('tom petty')
548 >>> a.terms
549 [{u'frequency': 1.0, u'name': u'heartland rock', u'weight': 1.0},
550 {u'frequency': 0.88569401860168606,
551 u'name': u'jam band',
552 u'weight': 0.9116501862732439},
553 {u'frequency': 0.9656145118557401,
554 u'name': u'pop rock',
555 u'weight': 0.89777934440040685},
556 {u'frequency': 0.8414744288140491,
557 u'name': u'southern rock',
558 u'weight': 0.8698567153186606},
559 {u'frequency': 0.9656145118557401,
560 u'name': u'hard rock',
561 u'weight': 0.85738022655218893},
562 {u'frequency': 0.88569401860168606,
563 u'name': u'singer-songwriter',
564 u'weight': 0.77427243392312772},
565 {u'frequency': 0.88569401860168606,
566 u'name': u'rock',
567 u'weight': 0.71158718989399083},
568 {u'frequency': 0.60874110500110956,
569 u'name': u'album rock',
570 u'weight': 0.69758668733499629},
571 {u'frequency': 0.74350792060935744,
572 u'name': u'psychedelic',
573 u'weight': 0.68457367494207944},
574 {u'frequency': 0.77213698386292873,
575 u'name': u'pop',
576 u'weight': 0.65039556639337293},
577 {u'frequency': 0.41747136183050298,
578 u'name': u'bar band',
579 u'weight': 0.54974975024767025}]
580 >>>
581
582 """
583 if cache and ('terms' in self.cache) and sort=='weight':
584 return self.cache['terms']
585 else:
586 response = self.get_attribute('terms', sort=sort)
587 if sort=='weight':
588 self.cache['terms'] = response['terms']
589 return response['terms']
590
591 terms = property(get_terms)
592
594 """Get the urls for an artist
595
596 Args:
597
598 Kwargs:
599 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
600
601 Results:
602 A url document dict
603
604 Example:
605
606 >>> a = artist.Artist('the unicorns')
607 >>> a.get_urls()
608 {u'amazon_url': u'http://www.amazon.com/gp/search?ie=UTF8&keywords=The Unicorns&tag=httpechonecom-20&index=music',
609 u'aolmusic_url': u'http://music.aol.com/artist/the-unicorns',
610 u'itunes_url': u'http://itunes.com/TheUnicorns',
611 u'lastfm_url': u'http://www.last.fm/music/The+Unicorns',
612 u'mb_url': u'http://musicbrainz.org/artist/603c5f9f-492a-4f21-9d6f-1642a5dbea2d.html',
613 u'myspace_url': u'http://www.myspace.com/iwasbornunicorn'}
614 >>>
615
616 """
617 if not (cache and ('urls' in self.cache)):
618 response = self.get_attribute('urls')
619 self.cache['urls'] = response['urls']
620 return self.cache['urls']
621
622 urls = property(get_urls)
623
624 - def get_video(self, results=15, start=0, cache=True):
625 """Get a list of video documents found on the web related to an artist
626
627 Args:
628
629 Kwargs:
630 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
631
632 results (int): An integer number of results to return
633
634 start (int): An integer starting value for the result set
635
636 Returns:
637 A list of video document dicts; list contains additional attributes 'start' and 'total'
638
639 Example:
640
641 >>> a = artist.Artist('the vapors')
642 >>> a.get_video(results=1, start=2)
643 [{u'date_found': u'2009-12-28T08:27:48',
644 u'id': u'd02f9e6dc7904f70402d4676516286b9',
645 u'image_url': u'http://i1.ytimg.com/vi/p6c0wOFL3Us/default.jpg',
646 u'site': u'youtube',
647 u'title': u'The Vapors-Turning Japanese (rectangular white vinyl promo)',
648 u'url': u'http://youtube.com/watch?v=p6c0wOFL3Us'}]
649 >>>
650
651 """
652 if cache and ('video' in self.cache) and results==15 and start==0:
653 return self.cache['video']
654 else:
655 response = self.get_attribute('video', results=results, start=start)
656 if results==15 and start==0:
657 self.cache['video'] = ResultList(response['video'], 0, response['total'])
658 return ResultList(response['video'], start, response['total'])
659
660 video = property(get_video)
661
663 """Get a list of years active dictionaries for an artist
664
665 Args:
666
667 Kwargs:
668 cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
669
670 Returns:
671 A list of years active dictionaries; list contains additional attributes 'start' and 'total'
672
673 Example:
674
675 >>> a = artist.Artist('yelle')
676 >>> a.get_years_active()
677 [{ start: 2005 }]
678 >>>
679
680 """
681 if cache and ('years_active' in self.cache):
682 return self.cache['years_active']
683 else:
684 response = self.get_attribute('profile', bucket=['years_active'])
685 self.cache['years_active'] = response['artist']['years_active']
686 return response['artist']['years_active']
687
688 years_active = property(get_years_active)
689
691 """
692 Get the number of related documents of various types for the artist.
693 The types include audio, biographies, blogs, images, news, reviews, songs, videos.
694
695 Note that these documents can be retrieved by calling artist.<document type>, for example,
696 artist.biographies.
697
698 Args:
699
700 Kwargs:
701 cache (bool): A boolean indicating whether or not the cached value should be used (if available).
702 Defaults to True.
703
704 Returns:
705 A dictionary with one key for each document type, mapped to an integer count of documents.
706
707 Example:
708
709 >>> a = artist.Artist("The Kinks")
710
711 >>> a.get_doc_counts()
712 {u'audio': 194,
713 u'biographies': 9,
714 u'blogs': 379,
715 u'images': 177,
716 u'news': 84,
717 u'reviews': 110,
718 u'songs': 499,
719 u'videos': 340}
720 >>>
721 """
722 if not cache or not ('doc_counts' in self.cache):
723 response = self.get_attribute("profile", bucket='doc_counts')
724 self.cache['doc_counts'] = response['artist']['doc_counts']
725 return self.cache['doc_counts']
726
727 doc_counts = property(get_doc_counts)
728
729 -def search(name=None, description=None, style=None, mood=None, start=0, \
730 results=15, buckets=None, limit=False, \
731 fuzzy_match=False, sort=None, max_familiarity=None, min_familiarity=None, \
732 max_hotttnesss=None, min_hotttnesss=None, test_new_things=None, rank_type=None, \
733 artist_start_year_after=None, artist_start_year_before=None,artist_end_year_after=None,artist_end_year_before=None):
734 """Search for artists by name, description, or constraint.
735
736 Args:
737
738 Kwargs:
739 name (str): the name of an artist
740
741 description (str): A string describing the artist
742
743 style (str): A string describing the style/genre of the artist
744
745 mood (str): A string describing the mood of the artist
746
747 start (int): An integer starting value for the result set
748
749 results (int): An integer number of results to return
750
751 buckets (list): A list of strings specifying which buckets to retrieve
752
753 limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
754
755 fuzzy_match (bool): A boolean indicating whether or not to search for similar sounding matches (only works with name)
756
757 max_familiarity (float): A float specifying the max familiarity of artists to search for
758
759 min_familiarity (float): A float specifying the min familiarity of artists to search for
760
761 max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
762
763 min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
764
765 artist_start_year_before (int): Returned artists will have started recording music before this year.
766
767 artist_start_year_after (int): Returned artists will have started recording music after this year.
768
769 artist_end_year_before (int): Returned artists will have stopped recording music before this year.
770
771 artist_end_year_after (int): Returned artists will have stopped recording music after this year.
772
773 rank_type (str): A string denoting the desired ranking for description searches, either 'relevance' or 'familiarity'
774
775 Returns:
776 A list of Artist objects
777
778 Example:
779
780 >>> results = artist.search(name='t-pain')
781 >>> results
782 [<artist - T-Pain>, <artist - T-Pain & Lil Wayne>, <artist - T Pain & 2 Pistols>, <artist - Roscoe Dash & T-Pain>, <artist - Tony Moxberg & T-Pain>, <artist - Flo-Rida (feat. T-Pain)>, <artist - Shortyo/Too Short/T-Pain>]
783 >>>
784
785 """
786 limit = str(limit).lower()
787 fuzzy_match = str(fuzzy_match).lower()
788 kwargs = locals()
789 kwargs['bucket'] = buckets or []
790 del kwargs['buckets']
791 """Search for artists"""
792 result = util.callm("%s/%s" % ('artist', 'search'), kwargs)
793 return [Artist(**util.fix(a_dict)) for a_dict in result['response']['artists']]
794
795 -def top_hottt(start=0, results=15, buckets = None, limit=False):
796 """Get the top hotttest artists, according to The Echo Nest
797
798 Args:
799
800 Kwargs:
801 results (int): An integer number of results to return
802
803 start (int): An integer starting value for the result set
804
805 buckets (list): A list of strings specifying which buckets to retrieve
806
807 limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
808
809 Returns:
810 A list of hottt Artist objects
811
812 Example:
813
814 >>> hot_stuff = artist.top_hottt()
815 >>> hot_stuff
816 [<artist - Deerhunter>, <artist - Sufjan Stevens>, <artist - Belle and Sebastian>, <artist - Glee Cast>, <artist - Linkin Park>, <artist - Neil Young>, <artist - Jimmy Eat World>, <artist - Kanye West>, <artist - Katy Perry>, <artist - Bruno Mars>, <artist - Lady Gaga>, <artist - Rihanna>, <artist - Lil Wayne>, <artist - Jason Mraz>, <artist - Green Day>]
817 >>>
818
819 """
820 buckets = buckets or []
821 kwargs = {}
822 if start:
823 kwargs['start'] = start
824 if results:
825 kwargs['results'] = results
826 if buckets:
827 kwargs['bucket'] = buckets
828 if limit:
829 kwargs['limit'] = 'true'
830
831 """Get top hottt artists"""
832 result = util.callm("%s/%s" % ('artist', 'top_hottt'), kwargs)
833 return [Artist(**util.fix(a_dict)) for a_dict in result['response']['artists']]
834
835
837 """Get a list of the top overall terms
838
839 Args:
840
841 Kwargs:
842 results (int): An integer number of results to return
843
844 Returns:
845 A list of term document dicts
846
847 Example:
848
849 >>> terms = artist.top_terms(results=5)
850 >>> terms
851 [{u'frequency': 1.0, u'name': u'rock'},
852 {u'frequency': 0.99054710039307992, u'name': u'electronic'},
853 {u'frequency': 0.96131624654034398, u'name': u'hip hop'},
854 {u'frequency': 0.94358477322411127, u'name': u'jazz'},
855 {u'frequency': 0.94023302416455468, u'name': u'pop rock'}]
856 >>>
857 """
858
859 kwargs = {}
860 if results:
861 kwargs['results'] = results
862
863 """Get top terms"""
864 result = util.callm("%s/%s" % ('artist', 'top_terms'), kwargs)
865 return result['response']['terms']
866
868 """Get a list of best terms to use with search
869
870 Args:
871
872 Kwargs:
873 type (str): the type of term to return, either 'mood' or 'style'
874
875 Example:
876
877 >>> best_terms = artist.list_terms('mood')
878 >>> best_terms
879 [{u'name': u'aggressive'},
880 {u'name': u'ambient'},
881 {u'name': u'angry'},
882 {u'name': u'angst-ridden'},
883 {u'name': u'bouncy'},
884 {u'name': u'calming'},
885 {u'name': u'carefree'}, etc.]
886 """
887
888 kwargs = {'type': type}
889 result = util.callm("%s/%s" % ('artist', 'list_terms'), kwargs)
890 return result['response']['terms']
891
892 -def similar(names=None, ids=None, start=0, results=15, buckets=None, limit=False, max_familiarity=None, min_familiarity=None,
893 max_hotttnesss=None, min_hotttnesss=None, seed_catalog=None,artist_start_year_before=None, \
894 artist_start_year_after=None,artist_end_year_before=None,artist_end_year_after=None):
895 """Return similar artists to this one
896
897 Args:
898
899 Kwargs:
900 ids (str/list): An artist id or list of ids
901
902 names (str/list): An artist name or list of names
903
904 results (int): An integer number of results to return
905
906 buckets (list): A list of strings specifying which buckets to retrieve
907
908 limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
909
910 start (int): An integer starting value for the result set
911
912 max_familiarity (float): A float specifying the max familiarity of artists to search for
913
914 min_familiarity (float): A float specifying the min familiarity of artists to search for
915
916 max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
917
918 min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
919
920 seed_catalog (str): A string specifying the catalog similar artists are restricted to
921
922 Returns:
923 A list of similar Artist objects
924
925 Example:
926
927 >>> some_dudes = [artist.Artist('weezer'), artist.Artist('radiohead')]
928 >>> some_dudes
929 [<artist - Weezer>, <artist - Radiohead>]
930 >>> sims = artist.similar(ids=[art.id for art in some_dudes], results=5)
931 >>> sims
932 [<artist - The Smashing Pumpkins>, <artist - Biffy Clyro>, <artist - Death Cab for Cutie>, <artist - Jimmy Eat World>, <artist - Nerf Herder>]
933 >>>
934
935 """
936
937 buckets = buckets or []
938 kwargs = {}
939
940 if ids:
941 if not isinstance(ids, list):
942 ids = [ids]
943 kwargs['id'] = ids
944 if names:
945 if not isinstance(names, list):
946 names = [names]
947 kwargs['name'] = names
948 if max_familiarity is not None:
949 kwargs['max_familiarity'] = max_familiarity
950 if min_familiarity is not None:
951 kwargs['min_familiarity'] = min_familiarity
952 if max_hotttnesss is not None:
953 kwargs['max_hotttnesss'] = max_hotttnesss
954 if min_hotttnesss is not None:
955 kwargs['min_hotttnesss'] = min_hotttnesss
956 if seed_catalog is not None:
957 kwargs['seed_catalog'] = seed_catalog
958 if start:
959 kwargs['start'] = start
960 if results:
961 kwargs['results'] = results
962 if buckets:
963 kwargs['bucket'] = buckets
964 if limit:
965 kwargs['limit'] = 'true'
966 if artist_start_year_before:
967 kwargs['artist_start_year_before'] = artist_start_year_before
968 if artist_start_year_after:
969 kwargs['artist_start_year_after'] = artist_start_year_after
970 if artist_end_year_before:
971 kwargs['artist_end_year_before'] = artist_end_year_before
972 if artist_end_year_after:
973 kwargs['artist_end_year_after'] = artist_end_year_after
974
975
976 result = util.callm("%s/%s" % ('artist', 'similar'), kwargs)
977 return [Artist(**util.fix(a_dict)) for a_dict in result['response']['artists']]
978
981 """Extract artist names from a block of text.
982
983 Args:
984
985 Kwargs:
986 text (str): The text to extract artists from
987
988 start (int): An integer starting value for the result set
989
990 results (int): An integer number of results to return
991
992 buckets (list): A list of strings specifying which buckets to retrieve
993
994 limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
995
996 max_familiarity (float): A float specifying the max familiarity of artists to search for
997
998 min_familiarity (float): A float specifying the min familiarity of artists to search for
999
1000 max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
1001
1002 min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
1003
1004 Returns:
1005 A list of Artist objects
1006
1007 Example:
1008
1009 >>> results = artist.extract(text='i saw beyonce at burger king, she was eatin, she was eatin')
1010 >>> results
1011
1012 >>>
1013
1014 """
1015
1016 buckets = buckets or []
1017 kwargs = {}
1018
1019 kwargs['text'] = text
1020
1021 if max_familiarity is not None:
1022 kwargs['max_familiarity'] = max_familiarity
1023 if min_familiarity is not None:
1024 kwargs['min_familiarity'] = min_familiarity
1025 if max_hotttnesss is not None:
1026 kwargs['max_hotttnesss'] = max_hotttnesss
1027 if min_hotttnesss is not None:
1028 kwargs['min_hotttnesss'] = min_hotttnesss
1029 if start:
1030 kwargs['start'] = start
1031 if results:
1032 kwargs['results'] = results
1033 if buckets:
1034 kwargs['bucket'] = buckets
1035 if limit:
1036 kwargs['limit'] = 'true'
1037
1038 result = util.callm("%s/%s" % ('artist', 'extract'), kwargs)
1039
1040 return [Artist(**util.fix(a_dict)) for a_dict in result['response']['artists']]
1041
1042
1043 -def suggest(q='', results=15, buckets=None, limit=False, max_familiarity=None, min_familiarity=None,
1044 max_hotttnesss=None, min_hotttnesss=None):
1045 """Suggest artists based upon partial names.
1046
1047 Args:
1048
1049 Kwargs:
1050 q (str): The text to suggest artists from
1051
1052 results (int): An integer number of results to return
1053
1054 buckets (list): A list of strings specifying which buckets to retrieve
1055
1056 limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
1057
1058 max_familiarity (float): A float specifying the max familiarity of artists to search for
1059
1060 min_familiarity (float): A float specifying the min familiarity of artists to search for
1061
1062 max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
1063
1064 min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
1065
1066 Returns:
1067 A list of Artist objects
1068
1069 Example:
1070
1071 >>> results = artist.suggest(text='rad')
1072 >>> results
1073
1074 >>>
1075
1076 """
1077
1078 buckets = buckets or []
1079 kwargs = {}
1080
1081 kwargs['q'] = q
1082
1083 if max_familiarity is not None:
1084 kwargs['max_familiarity'] = max_familiarity
1085 if min_familiarity is not None:
1086 kwargs['min_familiarity'] = min_familiarity
1087 if max_hotttnesss is not None:
1088 kwargs['max_hotttnesss'] = max_hotttnesss
1089 if min_hotttnesss is not None:
1090 kwargs['min_hotttnesss'] = min_hotttnesss
1091 if results:
1092 kwargs['results'] = results
1093 if buckets:
1094 kwargs['bucket'] = buckets
1095 if limit:
1096 kwargs['limit'] = 'true'
1097
1098 result = util.callm("%s/%s" % ('artist', 'suggest'), kwargs)
1099
1100 return [Artist(**util.fix(a_dict)) for a_dict in result['response']['artists']]
1101