Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganized index.rst for improved logical flow #1054

Merged
merged 4 commits into from
May 21, 2024
Merged

Reorganized index.rst for improved logical flow #1054

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
19c2636
reorganized sections without changing any header. Made a few small gr…
johnmel3 Dec 10, 2023
ad6d55a
cleaning up examples section.
johnmel3 Dec 10, 2023
ce1bfa8
updating changelog for proposed edits
johnmel3 Dec 10, 2023
1d2771d
Merge branch 'master' into alternative-index-file
dieser-niko May 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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
Expand Down
130 changes: 69 additions & 61 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,63 +8,6 @@ Welcome to Spotipy!
<https://developer.spotify.com/documentation/web-api/>`_. 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 <https://youtu.be/kaBVN8uP358>`_ explaining how to do so). For a longer tutorial with examples included, refer to this `video playlist <https://www.youtube.com/watch?v=tmt5SdvTqUI&list=PLqgOPibB_QnzzcaOFYmY2cQjs35y0is9N&index=1>`_. 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
========

Expand All @@ -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 <https://github.com/plamere/spotipy>`_.


Getting Started
===============
Expand All @@ -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 <https://developer.spotify.com/dashboard/applications>`_.
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 <https://youtu.be/kaBVN8uP358>`_ or follow the
`Spotipy Tutorial for Beginners <https://github.com/spotipy-dev/spotipy/blob/2.22.1/TUTORIAL.md>`_.

For a longer tutorial with examples included, refer to this `video playlist <https://www.youtube.com/watch?v=tmt5SdvTqUI&list=PLqgOPibB_QnzzcaOFYmY2cQjs35y0is9N&index=1>`_.


Authorization Code Flow
=======================

Expand Down Expand Up @@ -139,6 +91,7 @@ on Windows)::
export SPOTIPY_CLIENT_SECRET='your-spotify-client-secret'
export SPOTIPY_REDIRECT_URI='your-app-redirect-url'


Scopes
------

Expand Down Expand Up @@ -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 <https://github.com/plamere/spotipy/tree/master/examples>`_ on Github
Directory <https://github.com/plamere/spotipy/tree/master/examples>`_ on GitHub.

API Reference
==============
Expand Down
Loading