Skip to main content

Sync/Async API wrapper for Spotify's web API

Project description


Build Status Software License

Spotify's Web API Wrapper in Python


  • Async and Sync clients
  • Authenticate using:
    • OAuth2 client credentials flow
    • OAuth2 authroization code flow
    • Access token only authorization
  • Covers every parameter for every endpoint in Spotify's Web API
  • Automatically refreshes tokens for clients and users
  • Descriptive errors
  • Able to automatically default to user's locales
  • Rate limiting
  • HTTP and SOCKS proxies
  • HTTP caching (Sync only)
  • Unit and integration tested
  • Fit for both production and experimental/personal environments
  • Begginner friendly interface
  • Almost identical Async and Sync Interfaces


Link to Readthedocs


$ pip install --upgrade --user pyfy

Quick Start


from pyfy import Spotify

spt = Spotify('your_access_token')

results ='alice in chains them bones')


1. Make a single call:

import asyncio
from pyfy import AsyncSpotify

spt = AsyncSpotify('your_access_token')

async def query():
    return await'Like a motherless child')

or even:

awaited_search_result ='A tout le monde'))

2. Make multiple calls using a single TCP connection (no async/await syntax):

from pprint import pprint
from pyfy import AsyncSpotify

spt = AsyncSpotify('your_access_token')

gathered_results = spt.gather_now('Seize the day', to_gather=True),'Feel good inc'', to_gather=True),'In your room', to_gather=True),'Tout Petit Moineau', to_gather=True)


3. To manually await the results:

import asyncio
from pyfy import AsyncSpotify

spt = AsyncSpotify('your_access_token')

async def runner():
    return await spt.gather('Saeed', to_gather=True),'Killing time', to_gather=True),'Project 100', to_gather=True),'Tout Petit Moineau', to_gather=True)

results =

Authentication and Authorization

1. With User's Access Token: *get from here

from pyfy import Spotify

spt = Spotify('your access token')

2. With Client Credentials Flow (OAauth2): *get from here

from pyfy import ClientCreds, Spotify

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

3. With Authorization Code Flow (OAuth2) *examples with Sanic(async) and Flask(sync) here

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

client = ClientCreds(client_id='clientid', client_secret='client_secret')
spt = Spotify(client)

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

# Authorization callback
def callback(grant):
        user_creds = spt.build_credentials(grant=grant)
    except AuthError as e:
        return redirect(url_for_home)

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

👨 Ways to load Credentials (User & Client)

# Instantiate directly
client = ClientCreds(client_id='aclientid', client_secret='averysecrettoken')

# Load from environment
client = ClientCreds()

# Load from json file
client = ClientCreds()
client.load_from_json(path='full/dir/path', name='name_of_the_json_file')

🎶 Resources

  • Playback:
    • devices()
    • play()
    • pause()
    • repeat()
    • seek()
    • previous()
    • shuffle()
    • recently_played_tracks()
    • currently_playing_info()
    • currently_playing()
    • playback_transfer()
    • volume()
  • Playlists:
    • playlist()
    • user_playlists()
    • follows_playlist()
    • follow_playlist()
    • create_playlist()
    • update_playlist()
    • unfollow_playlist()
    • delete_playlist()
  • Playlist Contents:
    • playlist_tracks():
    • add_playlist_tracks()
    • reorder_playlist_track()
    • delete_playlist_tracks()
  • Tracks:
    • tracks()
    • user_tracks()
    • owns_tracks()
    • save_tracks()
    • delete_tracks()
    • user_top_tracks()
  • Albums:
    • albums()
    • user_albums()
    • owns_albums()
    • save_albums()
    • delete_albums()
  • Artists:
    • artists()
    • followed_artists()
    • follows_artists()
    • follow_artists()
    • artist_related_artists()
  • Users:
    • me()
    • is_premium
    • user_profile()
    • follows_users()
    • unfollow_users()
    • follow_users()
  • Others:
    • user_top_artists()
    • artist_albums()
    • album_tracks()
    • artist_top_tracks()
    • next_page()
    • previous_page()
  • Explore and Personalization:
    • available_genre_seeds()
    • categories()
    • category_playlist()
    • featured_playlists()
    • new_releases()
    • search()
    • recommendations()
    • tracks_audio_features()


  • All kinds of contributions are welcome :)


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pyfy-1.1.3.tar.gz (41.1 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page