#!/usr/bin/env python
# encoding: utf-8

"""
Copyright (c) 2010 The Echo Nest. All rights reserved.
Created by Tyler Williams on 2010-04-25.

The Artist module loosely covers http://developer.echonest.com/docs/v4/artist.html
Refer to the official api documentation if you are unsure about something.
"""
import util
from proxies import ArtistProxy, ResultList
from song import Song


class Artist(ArtistProxy):
    """
    An Artist object
    
    Attributes: 
        id (str): Echo Nest Artist ID
        
        name (str): Artist Name
        
        audio (list): Artist audio
        
        biographies (list): Artist biographies
        
        blogs (list): Artist blogs
        
        familiarity (float): Artist familiarity
        
        hotttnesss (float): Artist hotttnesss
        
        images (list): Artist images
        
        news (list): Artist news
        
        reviews (list): Artist reviews
        
        similar (list): Similar Artists
        
        songs (list): A list of song objects
        
        terms (list): Terms for an artist
        
        urls (list): Artist urls
        
        video (list): Artist video
        
        years_active (list): A list of dictionaries containing start and stop years
        
    You create an artist object like this:
    
    >>> a = artist.Artist('ARH6W4X1187B99274F')
    >>> a = artist.Artist('the national')
    >>> a = artist.Artist('musicbrainz:artist:a74b1b7f-71a5-4011-9441-d0b5e4122711')
        
    """

    def __init__(self, id, **kwargs):
        """
        Artist class
        
        Args:
            id (str): an artistw ID 
            
        Returns:
            An artist object
            
        Example:
        
        >>> a = artist.Artist('ARH6W4X1187B99274F', buckets=['hotttnesss'])
        >>> a.hotttnesss
        0.80098515900997658
        >>>
        
        """
        super(Artist, self).__init__(id, **kwargs)    
    
    def __repr__(self):
        return "<%s - %s>" % (self._object_type.encode('utf-8'), self.name.encode('utf-8'))
    
    def __str__(self):
        return self.name.encode('utf-8')
    
    def __cmp__(self, other):
        return cmp(self.id, other.id)
    
    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'])
    
    audio = property(get_audio)
    
    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'])
    
    biographies = property(get_biographies)    
    
    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:
            high_relevance = 'true' if high_relevance else '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'])
    
    blogs = property(get_blogs)
       
    def get_familiarity(self, cache=True):
        """Get our numerical estimation of how familiar an artist currently is to the world
        
        Args:
        
        Kwargs:
            cache (bool): A boolean indicating whether or not the cached value should be used (if available). Defaults to True.
        
        Returns:
            A float representing familiarity.
        
        Example:

        >>> a = artist.Artist('frank sinatra')
        >>> a.get_familiarity()
        0.65142555825947457
        >>> a.familiarity
        0.65142555825947457
        >>>
        """
        if not (cache and ('familiarity' in self.cache)):
            response = self.get_attribute('familiarity')
            self.cache['familiarity'] = response['artist']['familiarity']
        return self.cache['familiarity']
    
    familiarity = property(get_familiarity)    

    def get_foreign_id(self, idspace='musicbrainz', cache=True):