0
# Spotipy
1
2
A lightweight Python library for the Spotify Web API that provides comprehensive access to all Spotify endpoints. Spotipy handles authentication, rate limiting, and provides a clean Pythonic interface for integrating Spotify's music data and services into applications.
3
4
## Package Information
5
6
- **Package Name**: spotipy
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install spotipy`
10
11
## Core Imports
12
13
```python
14
import spotipy
15
from spotipy.oauth2 import SpotifyClientCredentials, SpotifyOAuth
16
```
17
18
## Basic Usage
19
20
### Client Credentials Flow (App-only access)
21
22
```python
23
import spotipy
24
from spotipy.oauth2 import SpotifyClientCredentials
25
26
# Initialize client
27
client_credentials_manager = SpotifyClientCredentials(
28
client_id="YOUR_CLIENT_ID",
29
client_secret="YOUR_CLIENT_SECRET"
30
)
31
sp = spotipy.Spotify(client_credentials_manager=client_credentials_manager)
32
33
# Search for tracks
34
results = sp.search(q='artist:radiohead', type='track', limit=10)
35
for track in results['tracks']['items']:
36
print(track['name'], '-', track['artists'][0]['name'])
37
```
38
39
### Authorization Code Flow (User authentication)
40
41
```python
42
import spotipy
43
from spotipy.oauth2 import SpotifyOAuth
44
45
# Initialize with user authentication
46
sp = spotipy.Spotify(auth_manager=SpotifyOAuth(
47
client_id="YOUR_CLIENT_ID",
48
client_secret="YOUR_CLIENT_SECRET",
49
redirect_uri="YOUR_REDIRECT_URI",
50
scope="user-library-read user-read-playback-state"
51
))
52
53
# Access user's saved tracks
54
results = sp.current_user_saved_tracks(limit=50)
55
for item in results['items']:
56
track = item['track']
57
print(f"{track['name']} by {track['artists'][0]['name']}")
58
```
59
60
## Architecture
61
62
Spotipy follows a modular architecture with clear separation of concerns:
63
64
- **Spotify Client**: Core API client handling all Spotify Web API endpoints
65
- **Authentication Managers**: OAuth2 flows (Client Credentials, Authorization Code, PKCE, Implicit Grant)
66
- **Cache Handlers**: Token persistence across sessions (File, Memory, Redis, Memcache, Django, Flask)
67
- **Exception Handling**: Structured error handling for API and OAuth errors
68
- **Utilities**: Helper functions for scope management and URL parsing
69
70
## Capabilities
71
72
### Core API Client
73
74
The main Spotify client providing access to all Spotify Web API endpoints including search, tracks, albums, artists, playlists, user data, and playback control.
75
76
```python { .api }
77
class Spotify:
78
def __init__(self, auth=None, requests_session=True, client_credentials_manager=None,
79
oauth_manager=None, auth_manager=None, proxies=None, requests_timeout=5,
80
status_forcelist=None, retries=3, status_retries=3, backoff_factor=0.3,
81
language=None):
82
"""Initialize Spotify client with authentication and configuration."""
83
84
def search(self, q, limit=10, offset=0, type="track", market=None):
85
"""Search for tracks, albums, artists, playlists, shows, episodes, or audiobooks."""
86
87
def track(self, track_id, market=None):
88
"""Get Spotify track information."""
89
90
def album(self, album_id, market=None):
91
"""Get Spotify album information."""
92
93
def artist(self, artist_id):
94
"""Get Spotify artist information."""
95
```
96
97
[Core API Client](./client.md)
98
99
### Authentication and Authorization
100
101
OAuth2 authentication flows for both app-only and user authentication scenarios, supporting multiple flow types with comprehensive token management.
102
103
```python { .api }
104
class SpotifyClientCredentials:
105
def __init__(self, client_id=None, client_secret=None, proxies=None,
106
requests_session=True, requests_timeout=None, cache_handler=None):
107
"""Client Credentials flow for app-only authentication."""
108
109
class SpotifyOAuth:
110
def __init__(self, client_id=None, client_secret=None, redirect_uri=None,
111
state=None, scope=None, cache_path=None, username=None,
112
proxies=None, requests_session=True, show_dialog=False,
113
requests_timeout=None, open_browser=True, cache_handler=None):
114
"""Authorization Code flow for user authentication."""
115
```
116
117
[Authentication](./authentication.md)
118
119
### User Library and Profile
120
121
Manage user's saved content including tracks, albums, shows, episodes, followed artists, and personal profile information.
122
123
```python { .api }
124
def current_user_saved_tracks(self, limit=20, offset=0, market=None):
125
"""Get user's saved tracks."""
126
127
def current_user_saved_albums(self, limit=20, offset=0, market=None):
128
"""Get user's saved albums."""
129
130
def current_user_followed_artists(self, limit=20, after=None):
131
"""Get user's followed artists."""
132
133
def me(self):
134
"""Get current user's profile."""
135
```
136
137
[User Library and Profile](./user-library.md)
138
139
### Playlist Management
140
141
Comprehensive playlist operations including creation, modification, track management, and collaboration features.
142
143
```python { .api }
144
def playlist(self, playlist_id, fields=None, market=None, additional_types=("track",)):
145
"""Get playlist information."""
146
147
def playlist_add_items(self, playlist_id, items, position=None):
148
"""Add tracks or episodes to playlist."""
149
150
def playlist_change_details(self, playlist_id, name=None, public=None,
151
collaborative=None, description=None):
152
"""Change playlist details."""
153
```
154
155
[Playlist Management](./playlists.md)
156
157
### Playback Control
158
159
Control Spotify playback across user's devices including play/pause, track navigation, volume, and queue management.
160
161
```python { .api }
162
def current_playback(self, market=None, additional_types=None):
163
"""Get current playback information."""
164
165
def start_playback(self, device_id=None, context_uri=None, uris=None,
166
offset=None, position_ms=None):
167
"""Start or resume playback."""
168
169
def pause_playback(self, device_id=None):
170
"""Pause playback."""
171
```
172
173
[Playback Control](./playback.md)
174
175
### Browse and Discover
176
177
Discovery features including featured playlists, new releases, categories, recommendations, and audio features analysis.
178
179
```python { .api }
180
def featured_playlists(self, country=None, locale=None, timestamp=None,
181
limit=20, offset=0):
182
"""Get featured playlists."""
183
184
def recommendations(self, seed_artists=None, seed_genres=None, seed_tracks=None,
185
limit=20, country=None, **kwargs):
186
"""Get track recommendations."""
187
188
def audio_features(self, tracks=[]):
189
"""Get audio features for tracks."""
190
```
191
192
[Browse and Discover](./browse.md)
193
194
### Podcasts and Shows
195
196
Access podcast shows, episodes, and audiobook content with comprehensive metadata and user library integration.
197
198
```python { .api }
199
def show(self, show_id, market=None):
200
"""Get show information."""
201
202
def episode(self, episode_id, market=None):
203
"""Get episode information."""
204
205
def get_audiobook(self, id, market=None):
206
"""Get audiobook information."""
207
```
208
209
[Podcasts and Shows](./podcasts.md)
210
211
### Cache Management and Utilities
212
213
Token caching strategies and utility functions for efficient session management and scope handling.
214
215
```python { .api }
216
class CacheFileHandler:
217
def __init__(self, cache_path=None, username=None, encoder_cls=None):
218
"""File-based token caching."""
219
220
class RedisCacheHandler:
221
def __init__(self, redis_instance=None, key=None, encoder_cls=None):
222
"""Redis-based token caching."""
223
```
224
225
[Cache Management](./cache.md)
226
227
## Error Handling
228
229
```python { .api }
230
class SpotifyException(Exception):
231
def __init__(self, http_status, code, msg, reason=None, headers=None):
232
"""General Spotify API exception with HTTP status and error details."""
233
234
class SpotifyOauthError(Exception):
235
def __init__(self, message, error=None, error_description=None, *args, **kwargs):
236
"""OAuth-related authentication errors."""
237
```
238
239
Common error scenarios include rate limiting (429), invalid tokens (401), insufficient scope permissions (403), and resource not found (404). All exceptions include detailed error information for debugging.