pyfy 1.1.2

Sync/Async API wrapper for Spotify's web API

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