Spotify SDK for Python

A Python SDK for the Spotify Web API.

Full documentation is available at spotify-sdk.dev.

Features

• Type-safe: Full type hints with Pydantic models for all API responses
• Sync and async: Dedicated SpotifyClient and AsyncSpotifyClient classes
• Automatic retries: Exponential backoff with jitter for rate limits and transient errors
• Context managers: Clean resource management with with and async with support

Installation

pip install spotify-sdk

Or with uv:

uv add spotify-sdk

Requirements

• Python 3.10+

Python version support follows the official Python release cycle. We support all versions that have not reached end-of-life.

Authentication

To use the SDK, you'll need credentials from the Spotify Developer Dashboard. The SDK supports:

• Access token authentication
• Client credentials flow (auto-refreshes tokens)
• Authorization code flow with refresh tokens

# Access token
client = SpotifyClient(access_token="your-access-token")

# Client credentials
client = SpotifyClient.from_client_credentials(
    client_id="your-client-id",
    client_secret="your-client-secret",
)

# Authorization code (user-scoped endpoints)
from spotify_sdk.auth import AuthorizationCode, FileTokenCache

auth = AuthorizationCode(
    client_id="your-client-id",
    client_secret="your-client-secret",
    redirect_uri="http://127.0.0.1:8080/callback",
    scope=["user-read-private"],
    token_cache=FileTokenCache(".cache/spotify-sdk/token.json"),
)

# Local helper: opens browser and captures the callback automatically
auth.authorize_local()

client = SpotifyClient(auth_provider=auth)

Quick Start

from spotify_sdk import SpotifyClient

client = SpotifyClient(access_token="your-access-token")

# Get an album
album = client.albums.get("5K79FLRUCSysQnVESLcTdb")
print(f"{album.name} by {album.artists[0].name}")
# DeBÍ TiRAR MáS FOToS by Bad Bunny

# Get album tracks
tracks = client.albums.get_tracks(album.id)
for track in tracks.items:
    print(f"{track.track_number}. {track.name}")

# Close the underlying HTTP connection when done
client.close()

Using Context Managers

from spotify_sdk import SpotifyClient

with SpotifyClient(access_token="your-access-token") as client:
    album = client.albums.get("4aawyAB9vmqN3uQ7FjRGTy")
    print(album.name)

Async Support

import asyncio
from spotify_sdk import AsyncSpotifyClient


async def main():
    async with AsyncSpotifyClient(access_token="your-access-token") as client:
        album = await client.albums.get("4Uv86qWpGTxf7fU7lG5X6F")
        print(f"{album.name} by {album.artists[0].name}")
        # The College Dropout by Kanye West


asyncio.run(main())

Services

See the full documentation for detailed method signatures and examples.

Error Handling

The SDK raises specific exceptions for different error types:

from spotify_sdk import (
    SpotifyClient,
    AuthenticationError,
    BadRequestError,
    ForbiddenError,
    NotFoundError,
    RateLimitError,
    ServerError,
)

try:
    album = client.albums.get("invalid_id")
except NotFoundError as e:
    print(f"Album not found: {e.message}")
except AuthenticationError as e:
    print(f"Invalid token: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ServerError as e:
    print(f"Spotify server error: {e.message}")

Exception Hierarchy

Configuration

Client Options

client = SpotifyClient(
    access_token="your-access-token",
    timeout=30.0,  # Request timeout in seconds (default: 30.0)
    max_retries=3,  # Maximum retry attempts (default: 3)
)

Retry Behavior

The SDK automatically retries requests on:

• Connection errors and timeouts
• Rate limit responses (429) - respects Retry-After header
• Server errors (5xx)

Retries use exponential backoff with jitter:

• Initial delay: 0.5 seconds
• Maximum delay: 8.0 seconds
• Multiplier: 2x per retry

Models

All API responses are returned as Pydantic models with full type hints:

album = client.albums.get("<id>")

# Access typed attributes
print(album.name)  # str
print(album.release_date)  # str
print(album.total_tracks)  # int
print(album.artists)  # list[SimplifiedArtist]
print(album.images)  # list[Image]

# Models support forward compatibility
# Unknown fields from the API are preserved

Development

Clone the repository:

git clone https://github.com/jonathan343/spotify-sdk.git
cd spotify-sdk

Install dependencies with uv:

uv sync

Run tests:

uv run pytest

Run linting:

uv run ruff check .
uv run ruff format --check --preview .

Sync/Async Architecture

The SDK uses an async-first architecture. Async code under src/spotify_sdk/_async/ is the source of truth, and the sync code under src/spotify_sdk/_sync/ is auto-generated using unasync. Do not edit _sync/ files directly.

After making changes to _async/ source or tests/_async/, regenerate the sync code:

uv run python scripts/run_unasync.py

To verify sync code is up to date (same check that runs in CI):

uv run python scripts/run_unasync.py --check

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.