Welcome 👋

Pyfy is a Sync + Async Pythonic Spotify Client that focuses on ease of use in personal projects and API stability and security for production grade codebases.

Setup ⚙️

$ pip install pyfy

Quick Start 🎛️

Sync:

from pyfy import Spotify

spt = Spotify('your_access_token')

spt.play()
spt.volume(85)
spt.next()
spt.pause()

Async:

import asyncio
from pyfy import AsyncSpotify

spt = AsyncSpotify('your_access_token')

async def search():
    return await spt.search('A tout le monde')

search_result = asyncio.run(search())

Getting Started 👩

You should start by creating client credentials from Spotify's Developers console

Next edit your application's settings and set a Redirect URL. If it's for personal use then set it as:

http://localhost:9000 Port can be any port of choice, not necessarily 9000

Next, copy your:

1. Client ID
2. Client Secret
3. Redirect URL (That you just set)

Next, figure out the scopes that you think you'll need from here: https://developer.spotify.com/documentation/general/guides/scopes/

e.g. ["user-library-modify", "app-remote-control"]

Next, follow the first authentication scheme from below (it's the one you'll most likely need, unless you're sure otherwise)

Authentication Schemes 👩‍🎤

1. Authorization Code Flow (OAuth2) (recommended)

Suitable if you want to access user-related resources. e.g. user-playlists, user-tracks etc.

Click here for full working examples with Sanic(async) and Flask(sync)

from pyfy import Spotify, ClientCreds, UserCreds, AuthError, ApiError

client = ClientCreds(
    client_id='clientid',
    client_secret='client_secret',
    redirect_uri='https://localhost:9000",
    scopes=["user-library-modify", "app-remote-control"]
)
spt = Spotify(client_creds=client)

def authorize():
    # Fist step of OAuth, Redirect user to spotify's authorization endpoint
    if spt.is_oauth_ready:
        return redirect(spt.auth_uri())

# Authorization callback
def callback(grant):
    try:
        user_creds = spt.build_credentials(grant=grant)
    except AuthError as e:
        abort(401)
        logging.info(e.msg)
        logging.info(e.http_response)
    else:
        db.insert(user_creds)
        return redirect(url_for_home)

def get_user_tracks():
    try:
        return json.dumps(spt.user_tracks())
    except ApiError:
        abort(500)

2. User's Access Token get from here

Same as the Authorization Code Flow above but without a refresh token. Suitable for quick runs.

from pyfy import Spotify
spt = Spotify('your access token')

3. Client Credentials Flow (OAauth2):

Suitable for when you want to access public information quickly. (Accessing user information is porhibited using this method)

from pyfy import ClientCreds, Spotify

client = ClientCreds(client_id=client_id, client_secret=client_secret)
spt = Spotify(client_creds=client)
spt.authorize_client_creds()

API endpoints 🌐

Albums:

• Get an album

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.albums
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/albums/get-album/

• Get an album's tracks

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.album_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/albums/get-albums-tracks/

• Get several albums

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.albums
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/albums/get-several-albums/

Artists:

• Get an artist

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.artists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/artists/get-artist/

• Artist albums

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.artist_albums
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/artists/get-artists-albums/

• Artist top tracks

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.artist_top_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/artists/get-artists-top-tracks/

• Artist related artists

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.artist_related_artists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/artists/get-related-artists/

• Get several artists

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.artists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/artists/get-several-artists/

Browse:

• Get a category

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.category
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/browse/get-category/

• Get a category's playlists

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.category_playlist
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/browse/get-categorys-playlists/

• Get list of categories

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.categories
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/browse/get-list-categories/

• Get a list of featured playlists

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.featured_playlists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/browse/get-list-featured-playlists/

• Get a list of new releases

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.new_releases
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/browse/get-list-new-releases/

• Get recommendations based on seeds

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.recommendations
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/browse/get-recommendations/

Episodes:

• Get an episode

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/episodes/get-an-episode/

• Get several episodes

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/episodes/get-several-episodes/

Follow:

• Check if Current User Follows Artists or Users

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.follows_users
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/follow/check-current-user-follows/

• Check if Users Follow a Playlist

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.follows_playlist
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/follow/check-user-following-playlist/

• Follow Artists

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.follow_artists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/follow/follow-artists-users/

• Follow Users

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.follow_artists
  • Web API reference: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.follow_users

• Follow a playlist

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.follow_playlist
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/follow/follow-playlist/

• Get User's Followed Artists

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.followed_artists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/follow/get-followed/

• Unfollow Artists

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.unfollow_artists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/follow/unfollow-artists-users/

• Unfollow Users

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.unfollow_users
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/follow/unfollow-artists-users/

• Unfollow Playlist

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.unfollow_playlist
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/follow/unfollow-playlist/

User Library:

• Check User's Saved Albums

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.owns_albums
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/check-users-saved-albums/

• Check User's Saved Shows

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/check-users-saved-shows/

• Check User's Saved Tracks

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.owns_tracks
  • Web API reference: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.owns_tracks

• Get Current User's Saved Albums

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.user_albums
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/get-users-saved-albums/

• Get User's Saved Shows

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/get-users-saved-shows/

• Get a User's Saved Tracks

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.user_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/get-users-saved-tracks/

• Remove Albums for Current User

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.delete_albums
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/remove-albums-user/

• Remove User's Saved Shows

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/remove-shows-user/

• Remove User's Saved Tracks

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.delete_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/remove-tracks-user/

• Save Albums for Current User

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.save_albums
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/save-albums-user/

• Save Shows for Current User

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/save-shows-user/

• Save Tracks for User

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.save_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/library/save-tracks-user/

Personalization:

• Get a User's Top Artists

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.user_top_artists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/personalization/get-users-top-artists-and-tracks/

• Get a User's Top Tracks

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.artist_top_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/personalization/get-users-top-artists-and-tracks/

Player:

• Add an Item to the User's Playback Queue

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.queue
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/add-to-queue/

• Get a User's Available Devices

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.devices
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/get-a-users-available-devices/

• Get Information About The User's Current Playback

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.currently_playing_info
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/get-information-about-the-users-current-playback/

• Get Current User's Recently Played Tracks

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.recently_played_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/get-recently-played/

• Get the User's Currently Playing Track

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.currently_playing
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/get-the-users-currently-playing-track/

• Pause a User's Playback

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.pause
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/pause-a-users-playback/

• Seek To Position In Currently Playing Track

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.seek
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/seek-to-position-in-currently-playing-track/

• Set Repeat Mode On User’s Playback

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.repeat
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/set-repeat-mode-on-users-playback/

• Set Volume For User's Playback

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.volume
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/set-volume-for-users-playback/

• Skip User’s Playback To Next Track

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.next
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/skip-users-playback-to-next-track/

• Skip User’s Playback To Previous Track

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.previous
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/skip-users-playback-to-previous-track/

• Start/Resume a User's Playback

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.play
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/start-a-users-playback/

• Toggle Shuffle For User’s Playback

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.shuffle
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/toggle-shuffle-for-users-playback/

• Transfer a User's Playback

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.playback_transfer
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/player/transfer-a-users-playback/

Playlists:

• Add playlist items:

  • Docs: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.add_playlist_tracks
  • Web API Reference: https://developer.spotify.com/documentation/web-api/reference/playlists/add-tracks-to-playlist/

• Edit playlist:

  • Pyfy: https://developer.spotify.com/documentation/web-api/reference/playlists/change-playlist-details/
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/change-playlist-details/

• Create playlist:

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.create_playlist
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/create-playlist/

• List a user's playlists:

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.user_playlists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/get-a-list-of-current-users-playlists/

• Playlist cover:

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.playlist_cover
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/get-playlist-cover/

• List a playlist:

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.playlist
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/get-playlist/

• List a playlist items:

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.playlist_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/get-playlists-tracks/

• Remove playlist items:

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.delete_playlist_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/remove-tracks-playlist/

• Reorder playlist items:

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.reorder_playlist_track
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/reorder-playlists-tracks/

• Replace playlist items:

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.replace_playlist_tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/replace-playlists-tracks/

• Upload custom playlist cover image:

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/upload-custom-playlist-cover/

• List current user playlists:

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.user_playlists
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/playlists/get-a-list-of-current-users-playlists/

Search:

• Search for an item
  • Pyfy: https://developer.spotify.com/documentation/web-api/reference/search/search/
  • Web API reference: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.search

Shows:

• Get a Show

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/shows/get-a-show/

• Get Several Shows

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/shows/get-several-shows/

• Get a Show's Episodes

  • Pyfy: TODO
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/shows/get-shows-episodes/

Tracks:

• Get Audio Analysis for a Track

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.track_audio_analysis
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/tracks/get-audio-analysis/

• Get Audio Features for a Track

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.tracks_audio_features
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/tracks/get-audio-features/

• Get Audio Features for Several Tracks

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.tracks_audio_features
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/tracks/get-several-audio-features/

• Get Several Tracks

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/tracks/get-several-tracks/

• Get a Track

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.tracks
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/tracks/get-track/

Users Profile:

• Get Current User's Profile

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.user_profile
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/users-profile/get-current-users-profile/

• Get a User's Profile

  • Pyfy: https://pyfy.readthedocs.io/en/latest/#pyfy.sync_client.Spotify.user_profile
  • Web API reference: https://developer.spotify.com/documentation/web-api/reference/users-profile/get-users-profile/

Pagination 📖

from pyfy import Spotify

user_creds = {'access_token': '...', 'refresh_token': '....'}

spt = Spotify(user_creds=user_creds)

user_top_tracks = spt.user_top_tracks(limit=5)

next_page_1 = spt.next_page(user_top_tracks)
next_page_2 = spt.next_page(next_page_1)

previous_page_1 = spt.previous_page(next_page_2)
previous_page_1 === next_page_1  # True

Documentation 📑

For a detailed documentation of Pyfy's API, please visit: https://pyfy.readthedocs.io/en/latest where you'll find:

• Sync client API 🎸: https://pyfy.readthedocs.io/en/latest/#sync-client-api

• Async client API 🎼: https://pyfy.readthedocs.io/en/latest/#async-client-api

• Exceptions API ⚠️: https://pyfy.readthedocs.io/en/latest/#module-pyfy.excs

• Credentials API 📇: https://pyfy.readthedocs.io/en/latest/#module-pyfy.creds

Backward Incompatibility Notices

V2:

1. Removed Spotify.oauth_uri property in favor of Spotify.auth_uri method.

2. Spotify.play() now accepts, track_ids, artist_ids etc. instead of resource_ids + resource_names

3. Oauth2 state handling:

   • Removed deprecated enforce_state_check functionality

   • Removed state attribute from user_creds

   • Oauth2 state checking is no longer done by Pyfy's client and should be handled manually

Testing 👩‍🔬:

Please visit: https://pyfy.readthedocs.io/en/latest/#testing

Contributors

Big thank you to our amazing contributors:

• Stɑrry Shivɑm
• exofeel
• Schiism
• kevinhynes
• haykkh
• ykelle
• Patrick Arminio
• Mustafa