def list(sandbox_name, results=15, start=0):
    """
    Returns a list of all assets available in this sandbox
    
    Args:
        sandbox_name (str): A string representing the name of the sandbox

    Kwargs:
        results (int): An integer number of results to return
        
        start (int): An integer starting value for the result set
        
    Returns:
        A list of asset dictionaries
    
    Example:

    >>> sandbox.list('bluenote')
    [{}, {}]
    >>> 

    
    """
    result = util.callm("%s/%s" % ('sandbox', 'list'), {'sandbox':sandbox_name, 'results': results, 'start': start})
    assets = result['response']['assets']
    start = result['response']['start']
    total = result['response']['total']

    return ResultList(assets, start, total)

 def post_attribute(self, method_name, **kwargs):
     if 'data' in kwargs:
         data = kwargs.pop('data')
     else:
         data = {}
     result = util.callm("%s/%s" % (self._object_type, method_name), kwargs, POST=True, data=data)
     return result['response']

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 top_terms(results=15):
    """Get a list of the top overall terms
        
    Args:
    
    Kwargs:
        results (int): An integer number of results to return
        
    Returns:
        A list of term document dicts
    
    Example:
    
    >>> terms = artist.top_terms(results=5)
    >>> terms
    [{u'frequency': 1.0, u'name': u'rock'},
     {u'frequency': 0.99054710039307992, u'name': u'electronic'},
     {u'frequency': 0.96131624654034398, u'name': u'hip hop'},
     {u'frequency': 0.94358477322411127, u'name': u'jazz'},
     {u'frequency': 0.94023302416455468, u'name': u'pop rock'}]
    >>> 
    """
    
    kwargs = {}
    if results:
        kwargs['results'] = results
    
    """Get top terms"""
    result = util.callm("%s/%s" % ('artist', 'top_terms'), kwargs)
    return result['response']['terms']

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 _upload(param_dict, timeout, data):
    """
    Calls upload either with a local audio file,
    or a url. Returns a track object.
    """
    param_dict['format'] = 'json'
    param_dict['wait'] = 'true'
    param_dict['bucket'] = 'audio_summary'
    result = util.callm('track/upload', param_dict, POST = True, socket_timeout = 300,  data = data)
    return _track_from_response(result, timeout)

def create_catalog_by_name(name, T="general"):
    """
    Creates a catalog object, with a given name. Does not check to see if the catalog already exists.

    Create a catalog object like
    """
    result = util.callm("catalog/create", {}, POST=True, 
                            data={"name":name, "type":T})
    result = result['response']
    return Catalog(result['id'], **dict( (k,result[k]) for k in ('name', 'type')))

def _upload(param_dict, timeout, data=None):
    """
    Calls upload either with a local audio file,
    or a url. Returns a track object.
    """
    param_dict["format"] = "json"
    param_dict["wait"] = "true"
    param_dict["bucket"] = "audio_summary"
    result = util.callm("track/upload", param_dict, POST=True, socket_timeout=300, data=data)
    return _track_from_response(result, timeout)

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 _wait_for_pending_track(trid, timeout):
    status = 'pending'
    start_time = time.time()
    while status == 'pending' and time.time() - start_time < timeout:
        time.sleep(1)
        param_dict = {'id': trid} # dict(id = identifier)
        param_dict['format'] = 'json'
        param_dict['bucket'] = 'audio_summary'
        result = util.callm('track/profile', param_dict)
        status = result['response']['track']['status'].lower()
    return result

def _wait_for_pending_track(trid, timeout):
    # timeout is ignored for now
    status = 'pending'
    while status == 'pending':
        time.sleep(1)
        param_dict = {'id': trid}  # dict(id = identifier)
        param_dict['format'] = 'json'
        param_dict['bucket'] = 'audio_summary'
        result = util.callm('track/profile', param_dict)
        status = result['response']['track']['status'].lower()
        # TODO: timeout if necessary
    return result

def _wait_for_pending_track(trid, timeout):
    end = time.time() + timeout
    status = 'pending'
    while status == 'pending':
        if time.time() > end:
            raise Exception('analysis timed out after %2.2f seconds' % timeout)
        time.sleep(1)
        if time.time() > end:
            raise Exception('the operation didn\'t complete before the timeout (%d secs)' % timeout)
        param_dict = {'id': trid}  # dict(id = identifier)
        param_dict['format'] = 'json'
        param_dict['bucket'] = 'audio_summary'
        result = util.callm('track/profile', param_dict)
        status = result['response']['track']['status'].lower()
    return result

def _wait_for_pending_track(trid, timeout):
    status = 'pending'
    param_dict = {'id': trid}
    param_dict['format'] = 'json'
    param_dict['bucket'] = 'audio_summary'
    start_time = time.time()
    end_time = start_time + timeout
    # counter for seconds to wait before checking track profile again.
    timeout_counter = 3
    while status == 'pending' and time.time() < end_time:
        time.sleep(timeout_counter)
        result = util.callm('track/profile', param_dict)
        status = result['response']['track']['status'].lower()
        # Slowly increment to wait longer each time.
        timeout_counter += timeout_counter / 2
    return result

def list_genres():
    """Get a list of best genres to use with genre-radio playlisting
    
    Args:
    
    Example:
    
    >>> best_terms = artist.list_genres()
    >>> best_terms
    [{u'name': u'pop'},
     {u'name': u'rock'},
     {u'name': u'country'},
    """
    kwargs = {}
    result = util.callm("%s/%s" % ('artist', 'list_genres'), kwargs)
    return result['response']['genres']

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']]    

def list_terms(type):
    """Get a list of best terms to use with search
    
    Args:
    
    Kwargs:
        type (str): the type of term to return, either 'mood' or 'style'
    
    Example:
    
    >>> best_terms = artist.list_terms('mood')
    >>> best_terms
    [{u'name': u'aggressive'},
     {u'name': u'ambient'},
     {u'name': u'angry'},
     {u'name': u'angst-ridden'},
     {u'name': u'bouncy'},
     {u'name': u'calming'},
     {u'name': u'carefree'}, etc.]
    """
    
    kwargs = {'type': type}
    result = util.callm("%s/%s" % ('artist', 'list_terms'), kwargs)
    return result['response']['terms']

#.........这里部分代码省略.........
    
        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']]