Sync/Async API wrapper for Spotify's web API
Project description
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:
-
Open tox.ini and change thoee values to:
SPOTIFY_CLIENT_ID
Create an app from hereSPOTIFY_CLIENT_SECRET
Create an app from hereSPOTIFY_ACCESS_TOKEN
Get a Spotify token from here **Check all scopesSPOTIFY_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.SPOTIFY_REDIRECT_URI
= 'http://localhost:5000/callback/spotify', # You have to register this callback in your Application's dashboard https://developer.spotify.com/dashboard/applicationsPYFY_TEST_INTEGRATION_SYNC
= 'true'PYFY_TEST_INTEGRATION_ASYNC
= 'true'
-
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 | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.