Spotifyaio

2.0.2 verified Sat May 09 auth: no python

Asynchronous Python client for the Spotify Web API, built on aiohttp. Current version 2.0.2, requires Python >=3.13. Actively maintained with frequent releases.

pip install spotifyaio

Common errors

error TypeError: ClientSession.__aenter__() got multiple values for argument 'self' ↓

cause Incorrect instantiation of SpotifyClient without async context manager, or reusing a session improperly.

fix

Use async with SpotifyClient(...) as client: pattern.

error spotifyaio.exceptions.SpotifyError: 401 - Unauthorized ↓

cause Invalid or expired client credentials (client_id/client_secret).

fix

Verify credentials from Spotify Developer Dashboard and set environment variables correctly.

error spotifyaio.exceptions.SpotifyError: 429 - Too Many Requests ↓

cause Rate limit exceeded. The client does not automatically throttle requests.

fix

Implement your own rate limiting or add delays between requests.

Warnings

breaking Version 2.0.0 drops Python 3.12 support; only Python >=3.13 is supported. ↓

fix Upgrade Python to 3.13 or later, or pin spotifyaio to <2.0.0 if Python 3.12 is required.

breaking Version 1.0.0 drops Python 3.11 support; only Python >=3.12 was supported at that time, but v2.0.0 now requires 3.13. ↓

fix Upgrade Python accordingly.

gotcha The client must be used as an async context manager. Forgetting 'async with' will lead to unclosed session warnings. ↓

fix Always use `async with SpotifyClient(...) as client:` or explicitly call `await client.close()`.

gotcha API calls may return None for optional fields. Always check for None before accessing nested attributes. ↓

fix Use `track.name` safely by checking `if track:` or use `.get()` if available.

Imports

SpotifyClient
```
from spotifyaio import SpotifyClient
```

Quickstart

Quickstart: authenticate and fetch a track by ID.

import asyncio
from spotifyaio import SpotifyClient

async def main():
    client_id = os.environ.get('SPOTIFY_CLIENT_ID', '')
    client_secret = os.environ.get('SPOTIFY_CLIENT_SECRET', '')
    async with SpotifyClient(client_id=client_id, client_secret=client_secret) as client:
        track = await client.tracks.get('4cOdK2wGLETKBW3PvgPWqT')
        print(track.name)

asyncio.run(main())