Documentation updates

docs/index.rst

@@ -1,28 +1,177 @@
-.. spotipy documentation master file, created by
+Spotipy
-   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 is a lightweight Python library for the `Spotify Web API
+<https://developer.spotify.com/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::
+    import spotipy
-   :maxdepth: 2
+
+    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 <https://developer.spotify.com/web-api/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
 =======
 

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 ^<target^>` where ^<target^> 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

docs/spotipy.rst

@@ -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:
-

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")

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
+

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

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