Initial commit of cloudplaya.

cloudplaya is a set of APIs and a command line utility for querying
information and download songs from Amazon Cloud Player.

COPYING

@@ -0,0 +1,19 @@
+Copyright (c) 2012  Christian Hammond
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README

@@ -0,0 +1,168 @@
+cloudplay
+=========
+
+cloudplaya is a Python library and command line utility for querying Amazon's
+Cloud Player service. It can be used to build playlists, download songs, or
+integrate with other software that needs to talk to Cloud Player.
+
+
+Installation
+------------
+
+To install cloudplaya, just run::
+
+    $ sudo easy_install cloudplaya
+
+
+Authenticating
+--------------
+
+You will need to first authenticate with Amazon Cloud Player. This will store
+.cloudplayarc file in your home directory containing some session information.
+Note that it's possible you may have to repeat this on occasion.
+
+To authenticate, run::
+
+    $ cloudplaya authenticate --username <email_address> --password <password>
+
+Replace ``<email_address>`` and ``<password>`` with your Amazon account
+e-mail and password above.
+
+You're then ready to use cloudplaya!
+
+
+Commands
+--------
+
+cloudplaya has a few different commands that are used to fetch data from
+Amazon Cloud Player. They each have their own arguments, and are invoked like::
+
+    $ cloudplaya command [options]
+
+
+get-album
+~~~~~~~~~
+
+Displays information on an album. It requires the ``--artist`` and ``--name``
+options, and will show some basic information on the album.
+
+For example::
+
+    $ cloudplaya get-album --artist "The Birthday Massacre" --name "Walking With Strangers"
+    Walking With Strangers by The Birthday Massacre (12 tracks)
+
+You can use ``--format`` to specify the format for display. This defaults to
+``%(name)s by %(artist_name)s (%(num_tracks)s tracks)``. Use ``%r`` with any
+query to see all the available options. (This will display a Python dictionary
+of the data.)
+
+
+get-albums
+~~~~~~~~~~
+
+Lists all the albums in the account, or all matching the given options.
+
+You can use ``--artist`` to specify an artist name. In this case, it will
+show all albums by that artist. If you don't specify an artist, all albums
+in your account will be listed.
+
+For example::
+
+    $ cloudplaya get-albums --artist "Greg Edmonson"
+    Firefly
+
+
+You can use ``--format`` to specify the format for display. This defaults to
+``%(name)s by %(artist_name)s (%(num_tracks)s tracks)``. Use ``%r`` with any
+query to see all the available options. (This will display a Python dictionary
+of the data.)
+
+
+get-artists
+~~~~~~~~~~~
+
+Lists all artists with albums in your account.
+
+
+For example::
+
+    $ cloudplaya get-artists
+    ...
+    Trent Reznor and Atticus Ross (56 tracks)
+    Various Artists (1 tracks)
+    Video Games Live (18 tracks)
+    ...
+
+You can use ``--format`` to specify the format for display. This defaults to
+``%(name)s (%(num_tracks)s tracks)``. Use ``%r`` with any query to see all the
+available options. (This will display a Python dictionary of the data.)
+
+
+get-songs
+~~~~~~~~~
+
+Lists all songs in the account, or all matching the given options.
+
+You can narrow down the results by using one or more of ``--artist``,
+``--album``, or ``--title``.
+
+For example::
+
+    $ cloudplaya get-songs --album "Walking With Strangers"
+    The Birthday Massacre - Falling Down
+    The Birthday Massacre - Goodnight
+    The Birthday Massacre - Kill The Lights
+    The Birthday Massacre - Looking Glass
+    The Birthday Massacre - Movie
+    The Birthday Massacre - Red Stars
+    The Birthday Massacre - Remember Me
+    The Birthday Massacre - Science
+    The Birthday Massacre - To Die For
+    The Birthday Massacre - Unfamiliar
+    The Birthday Massacre - Walking With Strangers
+    The Birthday Massacre - Weekend
+
+You can use ``--format`` to specify the format for display. This defaults to
+``%(artist_name)s - %(title)s'``. Use ``%r`` with any query to see all the
+available options. (This will display a Python dictionary of the data.)
+
+
+get-stream-urls
+~~~~~~~~~~~~~~~
+
+Lists URLs for one or more songs. These can be used to download or stream the
+songs.
+
+This command takes song IDs as parameters. You can retrieve a song ID by
+using the ``%(id)s`` format argument to ``get-songs`` above.
+
+For example::
+
+    $ cloudplaya get-songs --album "Walking With Strangers" --format "%(id)s"
+    12fad491-033f-43f2-9fff-c65a96ccf173
+    ...
+
+    $ cloudplaya get-stream-urls 12fad491-033f-43f2-9fff-c65a96ccf173
+    http://blahblah.amazonaws.com/lotsandlotsofstuff
+
+(IDs and URLs have been changed to protect the innocent.)
+
+
+download-album
+~~~~~~~~~~~~~~
+
+Downloads all the songs in an album.
+
+This command requires the ``--album`` and ``--artist`` options. It can also
+take a ``--out-directory`` (or ``-o``) to specify where to save the files
+(defaults to the current directory).
+
+It also can take a ``--format`` option to specify the filename format (defaults
+to ``%(album_name)s/%(track_num)s. %(title)s.%(extension)s``). This will
+create any directories as needed.
+
+For example::
+
+    $ cloudplaya download-album --album "Walking With Strangers" --artist "The Birthday Massacre"
+
+Progress will be reported as the album downloads.

cloudplaya/__init__.py

@@ -0,0 +1 @@
+VERSION = '0.1'

cloudplaya/album.py

@@ -0,0 +1,33 @@
+class Album(object):
+    COLUMNS = [
+        'albumArtistName', 'albumName', 'artistName', 'objectId',
+        'primaryGenre', 'sortAlbumArtistName', 'sortAlbumName',
+        'sortArtistName', 'albumCoverImageMedium', 'albumAsin',
+        'artistAsin', 'gracenoteId',
+    ]
+
+    def __init__(self, client, payload):
+        self.client = client
+
+        metadata = payload['metadata']
+        self.id = metadata['objectId']
+        self.name = metadata['albumName']
+        self.asin = metadata.get('albumAsin', None)
+        self.num_tracks = int(payload['numTracks'])
+        self.artist_asin = metadata.get('artistAsin', None)
+        self.artist_name = metadata['artistName']
+        self.primary_genre = metadata['primaryGenre']
+        self.album_artist_name = metadata['albumArtistName']
+        self.cover_image_url = metadata.get('albumCoverImageMedium', None)
+        self.sort_album_artist_name = metadata['sortAlbumArtistName']
+        self.sort_artist_name = metadata['sortArtistName']
+        self.sort_album_name = metadata['sortAlbumName']
+
+    def get_songs(self, *args, **kwargs):
+        return self.client.get_track_list(self)
+
+    def __repr__(self):
+        return '<Album "%s">' % self.name
+
+    def __str__(self):
+        return self.name

cloudplaya/artist.py

@@ -0,0 +1,20 @@
+class Artist(object):
+    COLUMNS = [
+        'artistName', 'objectId', 'sortArtistName', 'artistAsin',
+    ]
+
+    def __init__(self, client, payload):
+        self.client = client
+
+        metadata = payload['metadata']
+        self.id = metadata['objectId']
+        self.name = metadata['artistName']
+        self.asin = metadata.get('artistAsin', None)
+        self.sort_name = metadata['sortArtistName']
+        self.num_tracks = payload['numTracks']
+
+    def __repr__(self):
+        return '<Artist "%s">' % self.name
+
+    def __str__(self):
+        return self.name