diff --git a/docs/index.rst b/docs/index.rst
index 4163dbe..4081370 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,28 +1,177 @@
-.. spotipy documentation master file, created by
- sphinx-quickstart on Thu Aug 21 11:04:39 2014.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-Welcome to spotipy's documentation!
+Spotipy
===================================
+Spotipy is a lightweight Python library for the `Spotify Web API
+`_. With *spotipy*
+you get full access to all of the music data provided by the Spotify platform.
-Contents:
+Here's a quick example of using *spotipy* to list the names of all the albums
+released by the artist 'Birdy'::
-.. toctree::
- :maxdepth: 2
+ import spotipy
+
+ birdy_uri = 'spotify:artist:2WX2uTcsvV5OnS0inACecP'
+ spotify = spotipy.Spotify()
+
+ results = spotify.artist_albums(birdy_uri, album_type='album')
+ albums = results['items']
+ while results['next']:
+ results = spotify.next(results)
+ albums.extend(results['items'])
+
+ for album in albums:
+ print(album['name'])
+ print album
+
+Here's another example showing how to get 30 second samples and cover art
+for the top 10 tracks for Led Zeppelin::
+
+ import spotipy
+
+ lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'
+
+ spotify = spotipy.Spotify()
+ results = spotify.artist_top_tracks(lz_uri)
+
+ for track in results['tracks'][:10]:
+ print 'track : ' + track['name']
+ print 'audio : ' + track['preview_url']
+ print 'cover art: ' + track['album']['images'][0]['url']
+ print
+
+Finally, here's an example that will get the URL for an artist image given the
+artist's name::
+
+ import spotipy
+ import sys
+
+ spotify = spotipy.Spotify()
+
+ if len(sys.argv) > 1:
+ name = ' '.join(sys.argv[1:])
+ else:
+ name = 'Radiohead'
+
+ results = spotify.search(q='artist:' + name, type='artist')
+ items = results['artists']['items']
+ if len(items) > 0:
+ artist = items[0]
+ print artist['name'], artist['images'][0]['url']
-$project
-========
Features
========
+*Spotipy* supports all of the features of the Spotify Web API including access
+to all end points, and support for user authorization.
Installation
============
+Install spotipy with::
+
+ pip install SpotifyWebAPI
+
+Or with::
+
+ easy_install SpotifyWebAPI
+
+Or you can get the source from github at https://github.com/plamere/spotipy
Getting Started
===============
+To use *spotipy* import the spotipy package, and create a Spotify object. For
+methods that require authorization, pass the authorization token into the
+Spotify constructor
+
+Non authorized requests::
+
+ import spotipy
+ spotify = spotipy.Spotify()
+ results = spotify.search(q='artist:' + name, type='artist')
+ print results
+
+Authorization
+-------------
+Many methods require user authentication. For these requests you will need to
+generate an authorization token that indicates that the user has granted
+permission for your application to perform the given task. Spotipy provides a
+utility method ``util.prompt_for_user_token`` that will attempt to authorize the
+user. You can pass your app credentials directly into the method as arguments,
+or if you are reluctant to immortalize your app credentials in your source code,
+you can set environment variables like so::
+
+ export CLIENT_ID='your-spotify-client-id'
+ export CLIENT_SECRET='your-spotify-client-secret'
+ export REDIRECT_URI='your-app-redirect-url'
+
+Call ``util.prompt_for_user_token`` method with the username and the
+desired scope (see `Using
+Scopes `_ for information
+about scopes) and credentials. This will coordinate the user authorization via
+a the browser. The credentials are cached locally
+
+
+Authorized requests::
+
+ import sys
+ import spotipy
+ import spotipy.util as util
+
+ scope = 'user-library-read'
+
+ if len(sys.argv) > 1:
+ username = sys.argv[1]
+ else:
+ print "Usage: %s username" % (sys.argv[0],)
+ sys.exit()
+
+ token = util.prompt_for_user_token(username, scope)
+
+ if token:
+ sp = spotipy.Spotify(auth=token)
+ results = sp.current_user_saved_tracks()
+ for item in results['items']:
+ track = item['track']
+ print track['name'] + ' - ' + track['artists'][0]['name']
+ else:
+ print "Can't get token for", username
+
+
+spotipy Package
+===============
+
+:mod:`spotipy` Package
+----------------------
+
+.. automodule:: spotipy.__init__
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+:mod:`client` Module
+--------------------
+
+.. automodule:: spotipy.client
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+:mod:`oauth2` Module
+--------------------
+
+.. automodule:: spotipy.oauth2
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+:mod:`util` Module
+------------------
+
+.. automodule:: spotipy.util
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
Support
=======
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..f9c28ed
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,190 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+ set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^` where ^ is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. texinfo to make Texinfo files
+ echo. gettext to make PO message catalogs
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\spotipy.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\spotipy.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "texinfo" (
+ %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+ goto end
+)
+
+if "%1" == "gettext" (
+ %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+:end
diff --git a/docs/spotipy.rst b/docs/spotipy.rst
deleted file mode 100644
index 69a3b2f..0000000
--- a/docs/spotipy.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-spotipy Package
-===============
-
-:mod:`spotipy` Package
-----------------------
-
-.. automodule:: spotipy.__init__
- :members:
- :undoc-members:
- :show-inheritance:
-
-:mod:`client` Module
---------------------
-
-.. automodule:: spotipy.client
- :members:
- :undoc-members:
- :show-inheritance:
-
-:mod:`oauth2` Module
---------------------
-
-.. automodule:: spotipy.oauth2
- :members:
- :undoc-members:
- :show-inheritance:
-
-:mod:`util` Module
-------------------
-
-.. automodule:: spotipy.util
- :members:
- :undoc-members:
- :show-inheritance:
-
diff --git a/examples/artist_albums.py b/examples/artist_albums.py
new file mode 100644
index 0000000..9c1e79b
--- /dev/null
+++ b/examples/artist_albums.py
@@ -0,0 +1,41 @@
+import sys
+import spotipy
+
+''' shows the albums and tracks for a given artist.
+'''
+
+def get_artist(name):
+ results = sp.search(q='artist:' + name, type='artist')
+ items = results['artists']['items']
+ if len(items) > 0:
+ return items[0]
+ else:
+ return None
+
+def show_artist_albums(id):
+ albums = []
+ results = sp.artist_albums(artist['id'], album_type='album')
+ albums.extend(results['items'])
+ while results['next']:
+ results = sp.next(results)
+ albums.extend(results['items'])
+ seen = set() # to avoid dups
+ albums.sort(key=lambda album:album['name'].lower())
+ for album in albums:
+ name = album['name']
+ if name not in seen:
+ print(' ' + name)
+ seen.add(name)
+
+if __name__ == '__main__':
+ sp = spotipy.Spotify()
+
+ if len(sys.argv) < 2:
+ print('Usage: {0} artist name'.format(sys.argv[0]))
+ else:
+ name = ' '.join(sys.argv[1:])
+ artist = get_artist(name)
+ if artist:
+ show_artist_albums(artist)
+ else:
+ print("Can't find that artist")
diff --git a/examples/simple1.py b/examples/simple1.py
new file mode 100644
index 0000000..ce828b9
--- /dev/null
+++ b/examples/simple1.py
@@ -0,0 +1,17 @@
+import spotipy
+
+
+birdy_uri = 'spotify:artist:2WX2uTcsvV5OnS0inACecP'
+
+spotify = spotipy.Spotify()
+
+results = spotify.artist_albums(birdy_uri, album_type='album')
+albums = results['items']
+while results['next']:
+ results = spotify.next(results)
+ albums.extend(results['items'])
+
+for album in albums:
+ print(album['name'])
+ print album
+
diff --git a/examples/simple2.py b/examples/simple2.py
new file mode 100644
index 0000000..6bb6526
--- /dev/null
+++ b/examples/simple2.py
@@ -0,0 +1,15 @@
+
+import spotipy
+
+
+lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'
+
+spotify = spotipy.Spotify()
+
+results = spotify.artist_top_tracks(lz_uri)
+
+for track in results['tracks'][:10]:
+ print 'track : ' + track['name']
+ print 'audio : ' + track['preview_url']
+ print 'cover art: ' + track['album']['images'][0]['url']
+ print
diff --git a/examples/simple3.py b/examples/simple3.py
new file mode 100644
index 0000000..bac271b
--- /dev/null
+++ b/examples/simple3.py
@@ -0,0 +1,16 @@
+import spotipy
+import sys
+
+spotify = spotipy.Spotify()
+
+if len(sys.argv) > 1:
+ name = ' '.join(sys.argv[1:])
+else:
+ name = 'Radiohead'
+
+results = spotify.search(q='artist:' + name, type='artist')
+items = results['artists']['items']
+if len(items) > 0:
+ artist = items[0]
+ print artist['name'], artist['images'][0]['url']
+