musixmatch-master/musixmatch/artist.py
Go to the documentation of this file.
1 """
2 This module contains higher level classes to query Musixmatch API and build
3 simple dictionary-like objects representing an Artist or an ArtistsCollection.
4 
5 >>> from musixmatch.artist import Artist, ArtistsCollection
6 >>> import musixmatch.api
7 >>>
8 >>> try:
9 ... artist = Artist(artist_id=292)
10 ... collection = ArtistsCollection.fromChart(country='it', page=1)
11 ... except musixmatch.api.Error, e:
12 ... pass
13 """
14 import musixmatch
15 __license__ = musixmatch.__license__
16 __author__ = musixmatch.__author__
17 
18 from musixmatch.base import Item, ItemsCollection
19 from musixmatch.ws import artist
20 
21 class Artist(Item):
22  """
23  This class build a :py:class:`dict` like object representing an artist. It
24  can get artist information through the :py:class:`musixmatch.api.Method`
25  **artist.get** or from an already well-formed :py:class:`dict`. Create an
26  Artist object based on a given keyword argument:
27 
28  :param artist_id: musiXmatch artist ID
29  :param artist_mbid: Musicbrainz artist ID
30  :param artist_data: an already well-formed :py:class:`dict` of artist data.
31 
32  Once information are collected, the following keys are available:
33 
34  :keyword artist_id: musiXmatch artist ID
35  :keyword artist_mbid: Musicbrainz artist ID
36  :keyword artist_name: Artist name
37  """
38  __api_method__ = artist.get
39 
40 class ArtistsCollection(ItemsCollection):
41  """
42  This class build a :py:class:`list` like object representing an artists
43  collection. It accepts :py:class:`dict` or :py:class:`Artist` objects.
44  """
45  __allowedin__ = Artist
46 
47  @classmethod
48  def fromSearch(cls, **keywords):
49  """
50  This classmethod builds an :py:class:`ArtistsCollection` from a
51  **artist.search** :py:class:`musixmatch.api.Method` call.
52 
53  :param q: a string that will be searched in every data field
54  (q_track, q_artist, q_lyrics)
55  :param q_track: words to be searched among track titles
56  :param q_artist: words to be searched among artist names
57  :param q_lyrics: words to be searched into the lyrics
58  :param page: requested page of results
59  :param page_size: desired number of items per result page
60  :param f_has_lyrics: exclude tracks without an available lyrics
61  (automatic if q_lyrics is set)
62  :param f_artist_id: filter the results by the artist_id
63  :param f_artist_mbid: filter the results by the artist_mbid
64  :rtype: :py:class:`ArtistsCollection`
65  """
66  return cls.fromResponseMessage(artist.search(**keywords))
67 
68  @classmethod
69  def fromChart(cls, **keywords):
70  """
71  This classmethod builds an :py:class:`ArtistsCollection` from a
72  **artist.chart.get** :py:class:`musixmatch.api.Method` call.
73 
74  :param page: requested page of results
75  :param page_size: desired number of items per result page
76  :param country: the country code of the desired country chart
77  :rtype: :py:class:`ArtistsCollection`
78  """
79  return cls.fromResponseMessage(artist.chart.get(**keywords))
80