Documentation updates
This commit is contained in:
Paul Lamere
parent
080786654a
commit
58e5206076
171
docs/index.rst
171
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
|
||||
<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::
|
||||
: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 <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
|
||||
=======
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
@ -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")
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -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']
|
||||
|
||||
Loading…
Reference in New Issue