From 58e520607634432640e53cb03f6af6072c61756b Mon Sep 17 00:00:00 2001 From: Paul Lamere Date: Fri, 22 Aug 2014 09:28:19 -0400 Subject: [PATCH] Documentation updates --- docs/index.rst | 171 +++++++++++++++++++++++++++++++--- docs/make.bat | 190 ++++++++++++++++++++++++++++++++++++++ docs/spotipy.rst | 35 ------- examples/artist_albums.py | 41 ++++++++ examples/simple1.py | 17 ++++ examples/simple2.py | 15 +++ examples/simple3.py | 16 ++++ 7 files changed, 439 insertions(+), 46 deletions(-) create mode 100644 docs/make.bat delete mode 100644 docs/spotipy.rst create mode 100644 examples/artist_albums.py create mode 100644 examples/simple1.py create mode 100644 examples/simple2.py create mode 100644 examples/simple3.py 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'] +