yading@7: """
yading@7: This module contains higher level classes to query Musixmatch API and build
yading@7: simple dictionary-like objects representing an Album or an AlbumsCollection.
yading@7: 
yading@7: >>> from musixmatch.album import Album, AlbumsCollection
yading@7: >>> import musixmatch.api
yading@7: >>> 
yading@7: >>> try:
yading@7: ...     album = Album(album_id=292)
yading@7: ...     collection = AlbumsCollection.fromArtist(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 album, artist
yading@7: 
yading@7: class Album(Item):
yading@7:     """
yading@7:     This class build a :py:class:`dict` like object representing an album. It
yading@7:     can get album information through the :py:class:`musixmatch.api.Method`
yading@7:     **album.get** or from an already well-formed :py:class:`dict`. Create an
yading@7:     Album object based on a given keyword argument:
yading@7: 
yading@7:     :param   album_id: musiXmatch album ID
yading@7:     :param album_data: an already well-formed :py:class:`dict` of album data.
yading@7: 
yading@7:     Once information are collected, the following keys are available:
yading@7: 
yading@7:     :keyword album_id: musiXmatch album ID
yading@7:     :keyword album_name: album name
yading@7:     :keyword album_release_date: album release date
yading@7:     :keyword album_release_type: type of the album
yading@7:     :keyword album_coverart_100x100: coverart URL
yading@7:     :keyword artist_id: album artist musiXmatch ID
yading@7:     :keyword artist_name: album artist name
yading@7:     """
yading@7:     __api_method__ = album.get
yading@7: 
yading@7: class AlbumsCollection(ItemsCollection):
yading@7:     """
yading@7:     This class build a :py:class:`list` like object representing an albums
yading@7:     collection. It accepts :py:class:`dict` or :py:class:`Album` objects.
yading@7:     """
yading@7:     __allowedin__ = Album
yading@7: 
yading@7:     @classmethod
yading@7:     def fromArtist(cls, **keywords):
yading@7:         """
yading@7:         This classmethod builds an :py:class:`AlbumsCollection` from a
yading@7:         **artist.albums.get** :py:class:`musixmatch.api.Method` call.
yading@7: 
yading@7:         :param artist_id: album artist musiXmatch ID
yading@7:         :param g_album_name: group albums by name
yading@7:         :param s_release_date: sort albums by release date
yading@7:         :rtype: :py:class:`AlbumsCollection`
yading@7:         """
yading@7:         return cls.fromResponseMessage(artist.albums.get(**keywords))
yading@7: