def get_similar(self, results=15, start=0, buckets=None, limit=False, cache=True, max_familiarity=None, min_familiarity=None, \
                 max_hotttnesss=None, min_hotttnesss=None, min_results=None, reverse=False):
     """Return similar artists to this one
     
     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
         
         max_familiarity (float): A float specifying the max familiarity of artists to search for
         
         min_familiarity (float): A float specifying the min familiarity of artists to search for
         
         max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
         
         min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
         
         reverse (bool): A boolean indicating whether or not to return dissimilar artists (wrecommender). Defaults to False.
     
     Returns:
         A list of similar Artist objects
     
     Example:
     
     >>> a = artist.Artist('Sleater Kinney')
     >>> similars = a.similar[:5]
     >>> similars
     [<artist - Bikini Kill>, <artist - Pretty Girls Make Graves>, <artist - Huggy Bear>, <artist - Bratmobile>, <artist - Team Dresch>]
     >>> 
     """
     buckets = buckets or []
     kwargs = {}
     if max_familiarity:
         kwargs['max_familiarity'] = max_familiarity
     if min_familiarity:
         kwargs['min_familiarity'] = min_familiarity
     if max_hotttnesss:
         kwargs['max_hotttnesss'] = max_hotttnesss
     if min_hotttnesss:
         kwargs['min_hotttnesss'] = min_hotttnesss
     if min_results:
         kwargs['min_results'] = min_results
     if buckets:
         kwargs['bucket'] = buckets
     if limit:
         kwargs['limit'] = 'true'
     if reverse:
         kwargs['reverse'] = 'true'
     
     if cache and ('similar' in self.cache) and results==15 and start==0 and (not kwargs):
         return [Artist(**util.fix(a)) for a in self.cache['similar']]
     else:
         response = self.get_attribute('similar', results=results, start=start, **kwargs)
         if results==15 and start==0 and (not kwargs):
             self.cache['similar'] = response['artists']
         return [Artist(**util.fix(a)) for a in response['artists']]

    def read_items(self, buckets=None, results=15, start=0,item_ids=None):
        """
        Returns data from the catalog; also expanded for the requested buckets.
        This method is provided for backwards-compatibility

        Args:

        Kwargs:
            buckets (list): A list of strings specifying which buckets to retrieve

            results (int): An integer number of results to return

            start (int): An integer starting value for the result set

        Returns:
            A list of objects in the catalog; list contains additional attributes 'start' and 'total'

        Example:

        >>> c
        <catalog - my_songs>
        >>> c.read_items(results=1)
        [<song - Harmonice Mundi II>]
        >>>
        """
        warnings.warn("catalog.read_items() is depreciated. Please use catalog.get_item_dicts() instead.")
        kwargs = {}
        kwargs['bucket'] = buckets or []
        kwargs['item_id'] = item_ids or []
        response = self.get_attribute("read", results=results, start=start, **kwargs)
        rval = ResultList([])
        if item_ids:
            rval.start=0;
            rval.total=len(response['catalog']['items'])
        else:
            rval.start = response['catalog']['start']
            rval.total = response['catalog']['total']
        for item in response['catalog']['items']:
            new_item = None
            # song items
            if 'song_id' in item:
                item['id'] = item.pop('song_id')
                item['title'] = item.pop('song_name')
                request = item['request']
                new_item = song.Song(**util.fix(item))
                new_item.request = request
            # artist item
            elif 'artist_id' in item:
                item['id'] = item.pop('artist_id')
                item['name'] = item.pop('artist_name')
                request = item['request']
                new_item = artist.Artist(**util.fix(item))
                new_item.request = request
            # unresolved item
            else:
                new_item = item
            rval.append(new_item)
        return rval

    def get_songs(self, cache=True, results=15, start=0):
        """Get the songs associated with 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
            
        Results:
            A list of Song objects; list contains additional attributes 'start' and 'total'
        
        Example:

        >>> a = artist.Artist('Strokes')
        >>> a.get_songs(results=5)
        [<song - Fear Of Sleep>, <song - Red Light>, <song - Ize Of The World>, <song - Evening Sun>, <song - Juicebox>]
        >>> 
        """

        if cache and ('songs' in self.cache) and results==15 and start==0:
            return self.cache['songs']
        else:
            response = self.get_attribute('songs', results=results, start=start)
            for s in response['songs']:
                s.update({'artist_id':self.id, 'artist_name':self.name})
            songs = [Song(**util.fix(s)) for s in response['songs']]
            if results==15 and start==0:
                self.cache['songs'] = ResultList(songs, 0, response['total'])
            return ResultList(songs, start, response['total'])

def list_catalogs(results=30, start=0):
    """
    Returns list of all catalogs created on this API key

    Args:

    Kwargs:
        results (int): An integer number of results to return

        start (int): An integer starting value for the result set

    Returns:
        A list of catalog objects

    Example:

    >>> catalog.list_catalogs()
    [<catalog - test_artist_catalog>, <catalog - test_song_catalog>, <catalog - my_songs>]
    >>>

    """
    result = util.callm("%s/%s" % ('catalog', 'list'), {'results': results, 'start': start})
    cats = [Catalog(**util.fix(d)) for d in result['response']['catalogs']]
    start = result['response']['start']
    total = result['response']['total']
    return ResultList(cats, start, total)

    def get_current_song(self):
        """Get the current song in the playlist
        
        Args:
        
        Kwargs:
        
        Returns:
            A song object
        
        Example:
        
        >>> p = playlist.Playlist(type='artist-radio', artist=['ida maria', 'florence + the machine'])
        >>> p.song
        <song - Later On>
        >>> p.get_current_song()
        <song - Later On>
        >>> 

        """
        # we need this to fix up all the dict keys to be strings, not unicode objects
        if not 'songs' in self.cache:
            self.get_next_song()
        if len(self.cache['songs']):
            return Song(**util.fix(self.cache['songs'][0]))
        else:
            return None

 def _get_friends_and_idols(self, person_type, results, sort=None):
     assert person_type in ('followers', 'following')
     paramd = {}
     if sort:
         assert sort in ('when', 'affinity', 'alpha')
         paramd['order'] = sort
     friends_and_idols = self._get_listed_things(person_type, 'people', results, **paramd)
     return [TIMJUser(**util.fix(raw_person)) for raw_person in friends_and_idols]

def profile(ids=None, track_ids=None, buckets=None, limit=False):
    """get the profiles for multiple songs at once
        
    Args:
        ids (str or list): a song ID or list of song IDs
    
    Kwargs:
        buckets (list): A list of strings specifying which buckets to retrieve

        limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
    
    Returns:
        A list of term document dicts
    
    Example:

    >>> song_ids = ['SOBSLVH12A8C131F38', 'SOXMSGY1338A5D5873', 'SOJPHZO1376210AFE5', 'SOBHNKR12AB0186218', 'SOSJAHD13770F4D40C']
    >>> songs = song.profile(song_ids, buckets=['audio_summary'])
    [<song - Say It Ain't So>,
     <song - Island In The Sun>,
     <song - My Name Is Jonas>,
     <song - Buddy Holly>]
    >>> songs[0].audio_summary
    {u'analysis_url': u'https://echonest-analysis.s3.amazonaws.com/TR/7VRBNguufpHAQQ4ZjJ0eWsIQWl2S2_lrK-7Bp2azHOvPN4VFV-YnU7uO0dXgYtOKT-MTEa/3/full.json?Signature=hmNghHwfEsA4JKWFXnRi7mVP6T8%3D&Expires=1349809918&AWSAccessKeyId=AKIAJRDFEY23UEVW42BQ',
     u'audio_md5': u'b6079b2b88f8265be8bdd5fe9702e05c',
     u'danceability': 0.64540643050283253,
     u'duration': 255.92117999999999,
     u'energy': 0.30711665772260549,
     u'key': 8,
     u'liveness': 0.088994423525370583,
     u'loudness': -9.7799999999999994,
     u'mode': 1,
     u'speechiness': 0.031970700260699259,
     u'tempo': 76.049999999999997,
     u'time_signature': 4}
    >>> 
    """
    kwargs = {}

    if ids:
        if not isinstance(ids, list):
            ids = [ids]
        kwargs['id'] = ids

    if track_ids:
        if not isinstance(track_ids, list):
            track_ids = [track_ids]
        kwargs['track_id'] = track_ids

    buckets = buckets or []
    if buckets:
        kwargs['bucket'] = buckets

    if limit:
        kwargs['limit'] = 'true'
    
    result = util.callm("%s/%s" % ('song', 'profile'), kwargs)
    return [Song(**util.fix(s_dict)) for s_dict in result['response']['songs']]

def suggest(q='', results=15, buckets=None, limit=False, max_familiarity=None, min_familiarity=None,
                max_hotttnesss=None, min_hotttnesss=None):
    """Suggest artists based upon partial names.

    Args:

    Kwargs:
        q (str): The text to suggest artists from

        results (int): An integer number of results to return

        buckets (list): A list of strings specifying which buckets to retrieve

        limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets

        max_familiarity (float): A float specifying the max familiarity of artists to search for

        min_familiarity (float): A float specifying the min familiarity of artists to search for

        max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for

        min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for

    Returns:
        A list of Artist objects

    Example:

    >>> results = artist.suggest(text='rad')
    >>> results

    >>> 

    """

    buckets = buckets or []
    kwargs = {}

    kwargs['q'] = q

    if max_familiarity is not None:
        kwargs['max_familiarity'] = max_familiarity
    if min_familiarity is not None:
        kwargs['min_familiarity'] = min_familiarity
    if max_hotttnesss is not None:
        kwargs['max_hotttnesss'] = max_hotttnesss
    if min_hotttnesss is not None:
        kwargs['min_hotttnesss'] = min_hotttnesss
    if results:
        kwargs['results'] = results
    if buckets:
        kwargs['bucket'] = buckets
    if limit:
        kwargs['limit'] = 'true'

    result = util.callm("%s/%s" % ('artist', 'suggest'), kwargs)

    return [Artist(**util.fix(a_dict)) for a_dict in result['response']['artists']]

def profile(ids=None, track_ids=None, buckets=None, limit=False):
    """get the profiles for multiple songs at once
        
    Args:
        ids (str or list): a song ID or list of song IDs
    
    Kwargs:
        buckets (list): A list of strings specifying which buckets to retrieve

        limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
    
    Returns:
        A list of term document dicts
    
    Example:

    >>> song_ids = [u'SOGNMKX12B0B806320', u'SOLUHKP129F0698D49', u'SOOLGAZ127F3E1B87C', u'SOQKVPH12A58A7AF4D', u'SOHKEEM1288D3ED9F5']
    >>> songs = song.profile(song_ids, buckets=['audio_summary'])
    [<song - chickfactor>,
     <song - One Step Closer>,
     <song - And I Am Telling You I'm Not Going (Glee Cast Version)>,
     <song - In This Temple As In The Hearts Of Man For Whom He Saved The Earth>,
     <song - Octet>]
    >>> songs[0].audio_summary
    {u'analysis_url': u'https://echonest-analysis.s3.amazonaws.com:443/TR/TRKHTDL123E858AC4B/3/full.json?Signature=sE6OwAzg6UvrtiX6nJJW1t7E6YI%3D&Expires=1287585351&AWSAccessKeyId=AKIAIAFEHLM3KJ2XMHRA',
     u'danceability': None,
     u'duration': 211.90485000000001,
     u'energy': None,
     u'key': 7,
     u'loudness': -16.736999999999998,
     u'mode': 1,
     u'tempo': 94.957999999999998,
     u'time_signature': 4}
    >>> 
    
    """
    kwargs = {}

    if ids:
        if not isinstance(ids, list):
            ids = [ids]
        kwargs['id'] = ids

    if track_ids:
        if not isinstance(track_ids, list):
            track_ids = [track_ids]
        kwargs['track_id'] = track_ids

    buckets = buckets or []
    if buckets:
        kwargs['bucket'] = buckets

    if limit:
        kwargs['limit'] = 'true'
    
    result = util.callm("%s/%s" % ('song', 'profile'), kwargs)
    return [Song(**util.fix(s_dict)) for s_dict in result['response']['songs']]

def get_catalog_by_name(name):
    """
    Grabs a catalog by name, if its there on the api key.
    Otherwise, an error is thrown (mirroring the API)
    """
    kwargs = {
            'name' : name,
        }
    result = util.callm("%s/%s" % ('catalog', 'profile'), kwargs)
    return Catalog(**util.fix(result['response']['catalog']))

    def get_current_songs(self):
        if not 'songs' in self.cache:
            self.get_next_songs(results=1)
        if len(self.cache['songs']):
            songs = self.cache['songs'][:]
            songs = [Song(**util.fix(song)) for song in songs]

            return songs
        else:
            return None

    def get_lookahead_songs(self):
        if not 'lookahead' in self.cache:
            return None
        if len(self.cache['lookahead']):
            lookahead = self.cache['lookahead'][:]
            lookahead = [Song(**util.fix(song)) for song in lookahead]

            return lookahead
        else:
            return None

 def get_next_songs(self, results=None, lookahead=None):
     response = self.get_attribute(method="next", session_id=self.session_id, results=results, lookahead=lookahead)
     self.cache["songs"] = response["songs"]
     self.cache["lookahead"] = response["lookahead"]
     if len(self.cache["songs"]):
         songs = self.cache["songs"][:]
         songs = [Song(**util.fix(song)) for song in songs]
         return songs
     else:
         return None

    def __init__(self, name, **kwargs):
        super(UserProxy, self).__init__()
        self.id = name
        kwargs = util.fix(kwargs)
        core_attrs = [] # things you want/need initted at object creation time

        if not all(core_attr in kwargs for core_attr in core_attrs):
            profile = get_json_resource(self.id)['person']
            kwargs.update(profile)
        
        self.cache.update(kwargs)

def basic(
    type="artist-radio",
    artist_id=None,
    artist=None,
    song_id=None,
    song=None,
    track_id=None,
    dmca=False,
    results=15,
    buckets=None,
    limit=False,
):
    """Get a basic playlist
    
    Args:
    
    Kwargs:
        type (str): a string representing the playlist type ('artist-radio' or 'song-radio')
        
        artist_id (str): the artist_id to seed the playlist
        
        artist (str): the name of an artist to seed the playlist
        
        song_id (str): a song_id to seed the playlist
        
        song (str): the name of a song to seed the playlist
        
        track_id (str): the name of a track to seed the playlist
        
        dmca (bool): make the playlist dmca-compliant
        
        results (int): desired length of the playlist
        
        buckets (list): A list of strings specifying which buckets to retrieve
        
        limit (bool): Whether results should be restricted to any idspaces given in the buckets parameter
    """

    limit = str(limit).lower()
    dmca = str(dmca).lower()

    kwargs = locals()
    kwargs["bucket"] = kwargs["buckets"]
    del kwargs["buckets"]

    result = util.callm("%s/%s" % ("playlist", "basic"), kwargs)
    return [Song(**util.fix(s_dict)) for s_dict in result["response"]["songs"]]

def top_hottt(start=0, results=15, buckets = None, limit=False):
    """Get the top hotttest artists, according to The Echo Nest
    
    Args:
    
    Kwargs:
        results (int): An integer number of results to return
        
        start (int): An integer starting value for the result set
        
        buckets (list): A list of strings specifying which buckets to retrieve
        
        limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
        
    Returns:
        A list of hottt Artist objects

    Example:

    >>> hot_stuff = artist.top_hottt()
    >>> hot_stuff
    [<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>]
    >>> 

    """
    buckets = buckets or []
    kwargs = {}
    if start:
        kwargs['start'] = start
    if results:
        kwargs['results'] = results
    if buckets:
        kwargs['bucket'] = buckets
    if limit:
        kwargs['limit'] = 'true'
    
    """Get top hottt artists"""
    result = util.callm("%s/%s" % ('artist', 'top_hottt'), kwargs)
    return [Artist(**util.fix(a_dict)) for a_dict in result['response']['artists']]    

#.........这里部分代码省略.........
    
        max_loudness (float): The max loudness of song results
    
        min_loudness (float): The min loudness of song results
    
        artist_max_familiarity (float): A float specifying the max familiarity of artists to search for
    
        artist_min_familiarity (float): A float specifying the min familiarity of artists to search for
    
        artist_max_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
    
        artist_min_hotttnesss (float): A float specifying the max hotttnesss of artists to search for
    
        song_max_hotttnesss (float): A float specifying the max hotttnesss of songs to search for
    
        song_min_hotttnesss (float): A float specifying the max hotttnesss of songs to search for
    
        max_energy (float): The max energy of song results
    
        min_energy (float): The min energy of song results
    
        max_dancibility (float): The max dancibility of song results
    
        min_dancibility (float): The min dancibility of song results
    
        mode (int): 0 or 1 (minor or major)
    
        key (int): 0-11 (c, c-sharp, d, e-flat, e, f, f-sharp, g, a-flat, a, b-flat, b)
    
        max_latitude (float): A float specifying the max latitude of artists to search for
    
        min_latitude (float): A float specifying the min latitude of artists to search for
    
        max_longitude (float): A float specifying the max longitude of artists to search for
    
        min_longitude (float): A float specifying the min longitude of artists to search for                        
        
        adventurousness (float): A float ranging from 0 for old favorites to 1.0 for unheard music according to a seed_catalog
    
        sort (str): A string indicating an attribute and order for sorting the results
    
        buckets (list): A list of strings specifying which buckets to retrieve
    
        limit (bool): A boolean indicating whether or not to limit the results to one of the id spaces specified in buckets
        
        seed_catalog (str or Catalog): An Artist Catalog object or Artist Catalog id to use as a seed
        
        source_catalog (str or Catalog): A Catalog object or catalog id

        rank_type (str): A string denoting the desired ranking for description searches, either 'relevance' or 'familiarity'    
        
        artist_start_year_before (int): Returned songs's artists will have started recording music before this year.
        
        artist_start_year_after (int): Returned songs's artists will have started recording music after this year.
        
        artist_end_year_before (int): Returned songs's artists will have stopped recording music before this year.
        
        artist_end_year_after (int): Returned songs's artists will have stopped recording music after this year.

        distribution (str): Affects the range of artists returned and how many songs each artsits will have in the playlist realative to how similar they are to the seed. (wandering, focused)

    Returns:
        A list of Song objects
    
    Example:
    
    >>> p = playlist.static(type='artist-radio', artist=['ida maria', 'florence + the machine'])
    >>> p
    [<song - Pickpocket>,
     <song - Self-Taught Learner>,
     <song - Maps>,
     <song - Window Blues>,
     <song - That's Not My Name>,
     <song - My Lover Will Go>,
     <song - Home Sweet Home>,
     <song - Stella & God>,
     <song - Don't You Want To Share The Guilt?>,
     <song - Forget About It>,
     <song - Dull Life>,
     <song - This Trumpet In My Head>,
     <song - Keep Your Head>,
     <song - One More Time>,
     <song - Knights in Mountain Fox Jackets>]
    >>> 

    """
    limit = str(limit).lower()

    if seed_catalog and isinstance(seed_catalog, catalog.Catalog):
        seed_catalog = seed_catalog.id

    if source_catalog and isinstance(source_catalog, catalog.Catalog):
        source_catalog = source_catalog.id
    dmca = str(dmca).lower()
    kwargs = locals()
    kwargs['bucket'] = kwargs['buckets']
    del kwargs['buckets']
    
    result = util.callm("%s/%s" % ('playlist', 'static'), kwargs)
    return [Song(**util.fix(s_dict)) for s_dict in result['response']['songs']]

def _search_users_by(by, q, results):
    get_function = proxies.get_json_resource
    raw = proxies.get_listed_things(get_function, "search/person", 'people', results, by=by, q=q)
    return [TIMJUser(**util.fix(raw_person)) for raw_person in raw]

 def get_current_jam(self):
     jam = self.get_json_resource(self.id).get('jam')
     if jam:
         return Jam(**util.fix(jam))
     else:
         return None

 def get_liked_jams(self, results=10):
     liked_jams = self._get_listed_things('likes', 'jams', results)
     return [Jam(**util.fix(raw_jam)) for raw_jam in liked_jams]