diff --git a/CHANGELOG.md b/CHANGELOG.md
index 59c8ee5d..bf144e0d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Removed `python 3.6` from GitHub Actions CI workflow. Ubuntu 20.04 is not available in GitHub Actions for `python 3.6`.
- Added extra installation step to TUTORIAL.md for required installation packages.
- Added Troubleshooting Tips section to TUTORIAL.md to address common installation issues.
+- Added link to Spotipy Tutorial for Beginners under Getting Started.
### Changed
- Changes the YouTube video link for authentication tutorial (the old video was in low definition, the new one is in high definition)
@@ -24,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Updated links to Spotify in documentation
- Fixed error obfuscation when Spotify class is being inherited and an error is raised in the Child's `__init__`
- Replaced `artist_albums(album_type=...)` with `artist_albums(include_groups=...)` due to an API change.
+- Restructured the tutorial in `index.rst` to improve logical flow and made some minor edits.
### Fixed
- Fixed unused description parameter in playlist creation example
diff --git a/docs/index.rst b/docs/index.rst
index a6fa61b8..46252f9a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,63 +8,6 @@ Welcome to Spotipy!
`_. With *Spotipy*
you get full access to all of the music data provided by the Spotify platform.
-Assuming you set the ``SPOTIPY_CLIENT_ID`` and ``SPOTIPY_CLIENT_SECRET``
-environment variables (here is a `video `_ explaining how to do so). For a longer tutorial with examples included, refer to this `video playlist `_. Below is a quick example of using *Spotipy* to list the
-names of all the albums released by the artist 'Birdy'::
-
- import spotipy
- from spotipy.oauth2 import SpotifyClientCredentials
-
- birdy_uri = 'spotify:artist:2WX2uTcsvV5OnS0inACecP'
- spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
-
- 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'])
-
-Here's another example showing how to get 30 second samples and cover art
-for the top 10 tracks for Led Zeppelin::
-
- import spotipy
- from spotipy.oauth2 import SpotifyClientCredentials
-
- lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'
-
- spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
- 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
- from spotipy.oauth2 import SpotifyClientCredentials
-
- spotify = spotipy.Spotify(auth_manager=SpotifyClientCredentials())
-
- 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'])
-
-
Features
========
@@ -80,7 +23,8 @@ Install or upgrade *Spotipy* with::
pip install spotipy --upgrade
-Or you can get the source from github at https://github.com/plamere/spotipy
+You can also obtain the source code from the `Spotify GitHub repository `_.
+
Getting Started
===============
@@ -90,20 +34,28 @@ All methods require user authorization. You will need to register your app at
to get the credentials necessary to make authorized calls
(a *client id* and *client secret*).
+
+
*Spotipy* supports two authorization flows:
- - The **Authorization Code flow** This method is suitable for long-running applications
+ - **Authorization Code flow** This method is suitable for long-running applications
which the user logs into once. It provides an access token that can be refreshed.
.. note:: Requires you to add a redirect URI to your application at
`My Dashboard `_.
See `Redirect URI`_ for more details.
- - The **Client Credentials flow** The method makes it possible
+ - **Client Credentials flow** This method makes it possible
to authenticate your requests to the Spotify Web API and to obtain
a higher rate limit than you would with the Authorization Code flow.
+For guidance on setting your app credentials watch this `video tutorial `_ or follow the
+`Spotipy Tutorial for Beginners `_.
+
+For a longer tutorial with examples included, refer to this `video playlist `_.
+
+
Authorization Code Flow
=======================
@@ -139,6 +91,7 @@ on Windows)::
export SPOTIPY_CLIENT_SECRET='your-spotify-client-secret'
export SPOTIPY_REDIRECT_URI='your-app-redirect-url'
+
Scopes
------
@@ -242,9 +195,64 @@ Feel free to contribute new cache handlers to the repo.
Examples
=======================
+
+Here is an example of using *Spotipy* to list the
+names of all the albums released by the artist 'Birdy'::
+
+ import spotipy
+ from spotipy.oauth2 import SpotifyClientCredentials
+
+ birdy_uri = 'spotify:artist:2WX2uTcsvV5OnS0inACecP'
+ spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
+
+ 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'])
+
+Here's another example showing how to get 30 second samples and cover art
+for the top 10 tracks for Led Zeppelin::
+
+ import spotipy
+ from spotipy.oauth2 import SpotifyClientCredentials
+
+ lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'
+
+ spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
+ 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
+ from spotipy.oauth2 import SpotifyClientCredentials
+
+ spotify = spotipy.Spotify(auth_manager=SpotifyClientCredentials())
+
+ 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'])
There are many more examples of how to use *Spotipy* in the `Examples
-Directory `_ on Github
+Directory `_ on GitHub.
API Reference
==============