Skip to content

AsyncSpotify

Unit Tests Codacy Badge codecov

Documentation

The full documentation can be viewed here.

Why should you use this library

  • 100% Code coverage
  • Completely type annotated
  • Completely async
  • Scales up to (theoretically) unlimited requests per second (tested with 1000 simultaneous requests which lead to a 429)
  • Customize the timeout, maximal simultaneous request
  • Throws custom errors, so you can catch different errors easily
    • Token expiration
    • Rate limit violation
    • An invalid album id
  • Gets rid of the client credential workflow if you provide spotify cookies
    • Good for automated testing
  • Offers a hook which gets called if the token expires, so you can automatically update the token

Installation

You need at least python3.6 to install the package

pip install async-spotify

Example

For more in depth examples take a look here or visit the documentation.

from async_spotify import SpotifyApiClient
from async_spotify.authentification import SpotifyAuthorisationToken
from async_spotify.authentification.authorization_flows import AuthorizationCodeFlow
# Create a auth_code_flow object and load the auth_code_flow from env variables
auth_flow = AuthorizationCodeFlow()
auth_flow.load_from_env()

# Create a new Api client and pass the auth_code_flow
api_client = SpotifyApiClient(auth_flow, hold_authentication=True)

# Get the auth token with your code
code: str = "Your Spotify Code"
auth_token: SpotifyAuthorisationToken = await api_client.get_auth_token_with_code(code)

# Create a new client
await api_client.create_new_client(request_limit=1500)

# Start making queries with the internally saved token
album_tracks: dict = await api_client.albums.get_tracks('03dlqdFWY9gwJxGl3AREVy')

# If you pass a valid auth_token this auth_token will be used for making the requests
album_tracks: dict = await api_client.albums.get_tracks('03dlqdFWY9gwJxGl3AREVy', auth_token)

# Every argument mentioned by the Spotify API can be passed as kwarg. The client will figure out if your provided kwarg
# should be added to the request body, or the url
await api_client.player.play(context_uri="spotify:album:5ht7ItJgpBH7W6vJ5BqpPr", device_id="whatever_id")
#                                 ^                                                 ^
#                                URL                                               BODY

Tests

See here.

Last update: February 12, 2022