Skip to main content

Sync/Async API wrapper for Spotify's web API

Project description

Logo

Build Status Software License

Spotify's Web API Wrapper

Features

  • 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

Quick Start

Sync

from pyfy import Spotify

spt = Spotify('your_access_token')

spt.user_playlists()
spt.play()
spt.volume(85)
spt.next()
spt.pause()
results = spt.search(q='alice in chains them bones')
print(results)

Async

1. Make a single call:

import asyncio
from pyfy import AsyncSpotify

spt = AsyncSpotify('your_access_token')

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

asyncio.run(query())

or even:

awaited_search_result = asyncio.run(spt.search('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(
    spt.search('Seize the day', to_gather=True),
    spt.search('Feel good inc'', to_gather=True),
    spt.search('In your room', to_gather=True),
    spt.search('Tout Petit Moineau', to_gather=True)
)

pprint(gathered_results)

3. To manually await the results:

import asyncio
from pyfy import AsyncSpotify

spt = AsyncSpotify('your_access_token')

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

results = asyncio.run(runner())

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)
spt.authorize_client_creds()

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):
    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)

👨 Ways to load Credentials (User & Client)

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

# Load from environment
client = ClientCreds()
client.load_from_env()

# 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()

Installation and Setup

$ pip install --upgrade --user pyfy

For Python3.7:

$ python3.7 -m pip install --upgrade --user pyfy

Optional for Async:

  • Faster encoding detector lib written in C:

    $ pip install --user cchardet  
    
  • Async DNS requests:

    $ pip install --user aiodns
    
  • Faster JSON parser written in C:

    $ pip install --user ujson
    

Testing

Unit tests:

$ tox

Integration tests:

  1. Open tox.ini and change thoee values to:

    1. SPOTIFY_CLIENT_ID Create an app from here
    2. SPOTIFY_CLIENT_SECRET Create an app from here
    3. SPOTIFY_ACCESS_TOKEN Get a Spotify token from here **Check all scopes
    4. SPOTIFY_REFRESH_TOKEN To avoid manually refreshing your access token from the dev console, run the Oauth2 example in the examples dir. Then copy and paste the refresh token returned to your tox file.
    5. SPOTIFY_REDIRECT_URI = 'http://localhost:5000/callback/spotify', # You have to register this callback in your Application's dashboard https://developer.spotify.com/dashboard/applications
    6. PYFY_TEST_INTEGRATION_SYNC = 'true'
    7. PYFY_TEST_INTEGRATION_ASYNC = 'true'
  2. Run: *This will run some tests using your client ID, client secret and access token.
    *Unfortunately Spotify does not have a sandbox API, so we have to test it against the live API
    *Tests will carefully teardown all resources created and/or modified
    *Integration tests will not be abusive to the API and should only test for successful integration with minimum API calls
    *OAuth2 flow isn't tested in the tests folder (yet). Instead you can manually test it in the examples folder by running: pip install flask pyfy && python examples/oauth2.py

     $ tox
    

API

Errors

  • SpotifyError

  • ApiError(SpotifyError)

    • msg
    • http_response
    • http_request
    • code
  • AuthError(SpotifyError)

    • msg
    • http_response
    • http_request
    • code

Creds

  • ClientCreds

    • pickle()

    • unpickle() # Class method

    • save_as_json()

    • load_from_json()

    • load_from_env()

    • access_is_expired

    • client_id

    • client_secret

    • redirect_uri

    • scopes

    • show_dialog

    • access_token

    • expiry

  • UserCreds

    • pickle()

    • unpickle() # Class method

    • save_as_json()

    • load_from_json()

    • load_from_env()

    • access_is_expired

    • access_token

    • refresh_token

    • expiry

    • user_id

    • state

Clients

  • Spotify

    • client_creds

    • user_creds

    • authorize_client_creds()

    • oauth_uri

    • is_oauth_ready

    • is_active

    • is_premium

    • build_user_creds()

    • populate_user_creds()

    • resources....

  • AsyncSpotify

    • client_creds

    • user_creds

    • coro: authorize_client_creds()

    • oauth_uri

    • is_oauth_ready

    • coro: is_active

    • coro: is_premium

    • coro: build_user_creds()

    • coro: populate_user_creds()

    • resources....

Please Note:

  • Use the documentation instead of the console for reading the docs, as some console endpoints aren't up to date with the documentation. Namely: 1. Create User Playlist 2. Recommendations

Contribute

  • All kinds of contributions are welcome :)

Contributors

Project details


Release history Release notifications

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.2.tar.gz (41.0 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