pyechonest.catalog
index
http://pyechonest.googlecode.com/svn/trunk/doc/catalog.py

Copyright (c) 2010 The Echo Nest. All rights reserved.
Created by Scotty Vercoe on 2010-08-25.
 
The Catalog module loosely covers http://developer.echonest.com/docs/v4/catalog.html
Refer to the official api documentation if you are unsure about something.

 
Modules
       
pyechonest.artist
datetime
json
pyechonest.song
pyechonest.util

 
Classes
       
pyechonest.proxies.CatalogProxy(pyechonest.proxies.GenericProxy)
Catalog

 
class Catalog(pyechonest.proxies.CatalogProxy)
    Catalog object
 
Attributes:
    id (str): Catalog ID
 
    name (str): Catalog Name
 
Create an catalog object like so:
 
>>> c = catalog.Catalog('CAGPXKK12BB06F9DE9') # get existing catalog
>>> c = catalog.Catalog('test_song_catalog', 'song') # get existing or create new catalog
 
 
Method resolution order:
Catalog
pyechonest.proxies.CatalogProxy
pyechonest.proxies.GenericProxy
__builtin__.object

Methods defined here:
__init__(self, id, type=None, **kwargs)
Create a catalog object (get a catalog by ID or get or create one given by name and type)
 
Args:
    id (str): A catalog id or name
 
Kwargs:
    type (str): 'song' or 'artist', specifying the catalog type
    
Returns:
    A catalog object
 
Example:
 
>>> c = catalog.Catalog('my_songs', type='song')
>>> c.id
u'CAVKUPC12BCA792120'
>>> c.name
u'my_songs'
>>>
__repr__(self)
__str__(self)
delete(self)
Deletes the entire catalog
 
Args:
    
Kwargs:
    
Returns:
    The deleted catalog's id.
 
Example:
 
>>> c
<catalog - test_song_catalog>
>>> c.delete()
{u'id': u'CAXGUPY12BB087A21D'}
>>>
get_profile(self)
Check the status of a catalog update
 
Args:
    
Kwargs:
    
Returns:
    A dictionary representing ticket status
 
Example:
 
>>> c
<catalog - test_song_catalog>
>>> c.profile()
{u'id': u'CAGPXKK12BB06F9DE9',
 u'name': u'test_song_catalog',
 u'pending_tickets': [],
 u'resolved': 2,
 u'total': 4,
 u'type': u'song'}
>>>
read_items(self, buckets=None, results=15, start=0)
Returns data from the catalog; also expanded for the requested buckets
 
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
 
Example:
 
>>> c
<catalog - my_songs>
>>> c.read_items(results=1)
[<song - Harmonice Mundi II>]
>>>
status(self, ticket)
Check the status of a catalog update
 
Args:
    ticket (str): A string representing a ticket ID
    
Kwargs:
    
Returns:
    A dictionary representing ticket status
 
Example:
 
>>> ticket
u'7dcad583f2a38e6689d48a792b2e4c96'
>>> c.status(ticket)
{u'ticket_status': u'complete', u'update_info': []}
>>>
update(self, items)
Update a catalog object
 
Args:
    items (list): A list of dicts describing update data and action codes (see api docs)
 
Kwargs:
    
Returns:
    A ticket id
 
Example:
 
>>> c = catalog.Catalog('my_songs', type='song')
>>> items 
[{'action': 'update',
  'item': {'artist_name': 'dAn ThE aUtOmAtOr',
           'disc_number': 1,
           'genre': 'Instrumental',
           'item_id': '38937DDF04BC7FC4',
           'play_count': 5,
           'release': 'Bombay the Hard Way: Guns, Cars & Sitars',
           'song_name': 'Inspector Jay From Dehli',
           'track_number': 9,
           'url': 'file://localhost/Users/tylerw/Music/iTunes/iTunes%20Media/Music/Dan%20the%20Automator/Bombay%20the%20Hard%20Way_%20Guns,%20Cars%20&%20Sitars/09%20Inspector%20Jay%20From%20Dehli.m4a'}}]
>>> ticket = c.update(items)
>>> ticket
u'7dcad583f2a38e6689d48a792b2e4c96'
>>> c.status(ticket)
{u'ticket_status': u'complete', u'update_info': []}
>>>

Data descriptors defined here:
profile
Check the status of a catalog update
 
Args:
    
Kwargs:
    
Returns:
    A dictionary representing ticket status
 
Example:
 
>>> c
<catalog - test_song_catalog>
>>> c.profile()
{u'id': u'CAGPXKK12BB06F9DE9',
 u'name': u'test_song_catalog',
 u'pending_tickets': [],
 u'resolved': 2,
 u'total': 4,
 u'type': u'song'}
>>>
read
Returns data from the catalog; also expanded for the requested buckets
 
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
 
Example:
 
>>> c
<catalog - my_songs>
>>> c.read_items(results=1)
[<song - Harmonice Mundi II>]
>>>

Methods inherited from pyechonest.proxies.CatalogProxy:
get_attribute(self, *args, **kwargs)
get_attribute_simple(self, *args, **kwargs)
post_attribute(self, *args, **kwargs)

Data descriptors inherited from pyechonest.proxies.GenericProxy:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
Functions
       
dthandler lambda obj
# deal with datetime in json
list(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()
[<catalog - test_artist_catalog>, <catalog - test_song_catalog>, <catalog - my_songs>]
>>>