yading@7: """
yading@7: This module contains higher level classes to query Musixmatch API and build
yading@7: simple dictionary-like objects representing an Artist or an ArtistsCollection.
yading@7: 
yading@7: >>> from musixmatch.artist import Artist, ArtistsCollection
yading@7: >>> import musixmatch.api
yading@7: >>> 
yading@7: >>> try:
yading@7: ...     artist = Artist(artist_id=292)
yading@7: ...     collection = ArtistsCollection.fromChart(country='it', page=1)
yading@7: ... except musixmatch.api.Error, e:
yading@7: ...     pass
yading@7: """
yading@7: import musixmatch
yading@7: __license__ = musixmatch.__license__
yading@7: __author__ = musixmatch.__author__
yading@7: 
yading@7: from musixmatch.base import Item, ItemsCollection
yading@7: from musixmatch.ws import artist
yading@7: 
yading@7: class Artist(Item):
yading@7:     """
yading@7:     This class build a :py:class:`dict` like object representing an artist. It
yading@7:     can get artist information through the :py:class:`musixmatch.api.Method`
yading@7:     **artist.get** or from an already well-formed :py:class:`dict`. Create an
yading@7:     Artist object based on a given keyword argument:
yading@7: 
yading@7:     :param artist_id: musiXmatch artist ID
yading@7:     :param artist_mbid: Musicbrainz artist ID
yading@7:     :param artist_data: an already well-formed :py:class:`dict` of artist data.
yading@7: 
yading@7:     Once information are collected, the following keys are available:
yading@7: 
yading@7:     :keyword artist_id: musiXmatch artist ID
yading@7:     :keyword artist_mbid: Musicbrainz artist ID
yading@7:     :keyword artist_name: Artist name
yading@7:     """
yading@7:     __api_method__ = artist.get
yading@7: 
yading@7: class ArtistsCollection(ItemsCollection):
yading@7:     """
yading@7:     This class build a :py:class:`list` like object representing an artists
yading@7:     collection. It accepts :py:class:`dict` or :py:class:`Artist` objects.
yading@7:     """
yading@7:     __allowedin__ = Artist
yading@7: 
yading@7:     @classmethod
yading@7:     def fromSearch(cls, **keywords):
yading@7:         """
yading@7:         This classmethod builds an :py:class:`ArtistsCollection` from a
yading@7:         **artist.search** :py:class:`musixmatch.api.Method` call.
yading@7: 
yading@7:         :param q: a string that will be searched in every data field
yading@7:                      (q_track, q_artist, q_lyrics)
yading@7:         :param q_track: words to be searched among track titles
yading@7:         :param q_artist: words to be searched among artist names
yading@7:         :param q_lyrics: words to be searched into the lyrics
yading@7:         :param page: requested page of results
yading@7:         :param page_size: desired number of items per result page
yading@7:         :param f_has_lyrics: exclude tracks without an available lyrics
yading@7:                                 (automatic if q_lyrics is set)
yading@7:         :param f_artist_id: filter the results by the artist_id
yading@7:         :param f_artist_mbid: filter the results by the artist_mbid
yading@7:         :rtype: :py:class:`ArtistsCollection`
yading@7:         """
yading@7:         return cls.fromResponseMessage(artist.search(**keywords))
yading@7: 
yading@7:     @classmethod
yading@7:     def fromChart(cls, **keywords):
yading@7:         """
yading@7:         This classmethod builds an :py:class:`ArtistsCollection` from a
yading@7:         **artist.chart.get** :py:class:`musixmatch.api.Method` call.
yading@7: 
yading@7:         :param page: requested page of results
yading@7:         :param page_size: desired number of items per result page
yading@7:         :param country: the country code of the desired country chart
yading@7:         :rtype: :py:class:`ArtistsCollection`
yading@7:         """
yading@7:         return cls.fromResponseMessage(artist.chart.get(**keywords))
yading@7: