From 3e552d90dffa7a641337099a9e9eef1b4a024ff8 Mon Sep 17 00:00:00 2001 From: Paul Lamere Date: Fri, 22 Aug 2014 12:10:48 -0400 Subject: [PATCH] Improved README docs --- README.md | 66 ++++++++++----------------------------------- examples/simple0.py | 6 +++++ 2 files changed, 20 insertions(+), 52 deletions(-) create mode 100644 examples/simple0.py diff --git a/README.md b/README.md index 93a6ef8..3a671af 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,16 @@ -# Spotipy - a Python client for The Spotify API +# Spotipy - a Python client for The Spotify Web API ## Description -Spotipy is a thin client library for the Spotify Web API . +Spotipy is a thin client library for the Spotify Web API. + +## Documentation + +Spotipy's full documentation is online at [Spotipy Documentation](http://spotipy.readthedocs.org/) ## Installation -If you already have [Python](http://www.python.org/) on your system you can install -the library simply by downloading the distribution, unpack it and install in the usual fashion: +If you already have [Python](http://www.python.org/) on your system you can install the library simply by downloading the distribution, unpack it and install in the usual fashion: python setup.py install @@ -26,63 +29,21 @@ or ## Quick Start -To get started: +To get started, simply install spotipy, reate a Spotify object and call methods: -- Install spotipy - -- Create a Spotify object - + import spotipy sp = spotipy.Spotify() -Call methods: - - tracks = sp.search(q='weezer', limit=20) - for i, t in enumerate(tracks['tracks']): + results = sp.search(q='weezer', limit=20) + for i, t in enumerate(results['tracks']['items']): print ' ', i, t['name'] -A full set of examples can be found in the [Spotipy examples directory](https://github.com/plamere/spotipy/tree/master/examples) +A full set of examples can be found in the [online documentation](http://spotipy.readthedocs.org/) and in the [Spotipy examples directory](https://github.com/plamere/spotipy/tree/master/examples). - -## Supported Methods - - - **album(self, album_id)** - returns a single album given the album's ID, URN or URL - - **album_tracks(self, album_id)** - Get Spotify catalog information about an album’s tracks - - **albums(self, albums)** - returns a list of albums given the album IDs, URNs, or URLs - - **artist(self, artist_id)** - returns a single artist given the artist's ID, URN or URL - - **artist_albums(self, artist_id, album_type=None, country=None, limit=20, offset=0)** - Get Spotify catalog information about an artist’s albums - - **artist_top_tracks(self, artist_id, country='US')** - Get Spotify catalog information about an artist’s top 10 tracks by country. - - **artist_related_artists(self, artist_id)** - Get Spotify catalog information about artists similar to an identified artist. Similarity is based on analysis of the Spotify community’s listening history. - - **artists(self, artists)** - returns a list of artists given the artist IDs, URNs, or URLs - - **me(self)** - returns info about me - - **next(self, result)** - returns the next result given a result - - **previous(self, result)** - returns the previous result given a result - - **search(self, q, limit=10, offset=0, type='track')** - searches for an item - - **track(self, track_id)** - returns a single track given the track's ID, URN or URL - - **tracks(self, tracks)** - returns a list of tracks given the track IDs, URNs, or URLs - - **user(self, user_id)** - Gets basic profile information about a Spotify User - - **user_playlist(self, user, playlist_id=None, fields=None)** - Gets playlist of a user - - **user_playlist_add_tracks(self, user, playlist_id, tracks, position=None)** - Adds tracks to a playlist - - **user_playlist_create(self, user, name, public=True)** - Creates a playlist for a user - - **user_playlists(self, user)** - Gets playlists of a user - - **current_user(self)** - Get detailed profile information about the current user. - - **current_user_saved_tracks(self, limit=20, offset=0)** - Gets a list of the tracks saved in the current authorized user's "Your Music" library - - **current_user_saved_tracks_delete(self, tracks)** - Remove tracks from the current authorized user's "Your Music" library - - **current_user_saved_tracks_add(self, tracks)** - Add tracks to the current authorized user's "Your Music" library - - **current_user_saved_tracks_contains(self, tracks)** - Check if one or more tracks is already saved in the current Spotify user’s “Your Music” library. - -Refer to the [Spotify API documentation](https://developer.spotify.com/spotify-web-api/) for details on the methods and parameters. - -Methods that take item IDs (such as the track, album and artist methods) accept URN, URL or simple ID types. The following 3 ids are all acceptable IDs: - - - http://open.spotify.com/track/3HfB5hBU0dmBt8T0iCmH42 - - spotify:track:3HfB5hBU0dmBt8T0iCmH42 - - 3HfB5hBU0dmBt8T0iCmH42 - ## Reporting Issues -If you have suggestions, bugs or other issues specific to this library, file them [here](https://github.com/plamere/spotipy/issues) or contact me -at [paul@echonest.com](mailto:paul@echonest.com). Or just send me a pull request. +If you have suggestions, bugs or other issues specific to this library, file them [here](https://github.com/plamere/spotipy/issues). Or just send me a pull request. ## Version @@ -99,3 +60,4 @@ at [paul@echonest.com](mailto:paul@echonest.com). Or just send me a pull request - v1.50, August 14, 2014 -- Refactored util out of examples and into the main package - v1.301, August 19, 2014 -- Upgraded version number to take precedence over previously botched release (sigh) - v1.310, August 20, 2014 -- Added playlist replace and remove methods. Added auth tests. Improved API docs +- v2.0 - August 22, 2014 -- Upgraded APIs and docs to make it be a real library diff --git a/examples/simple0.py b/examples/simple0.py new file mode 100644 index 0000000..f5e76c1 --- /dev/null +++ b/examples/simple0.py @@ -0,0 +1,6 @@ +import spotipy +sp = spotipy.Spotify() + +results = sp.search(q='weezer', limit=20) +for i, t in enumerate(results['tracks']['items']): + print ' ', i, t['name']