universal-mcp 0.1.9rc1__py3-none-any.whl → 0.1.9rc2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- universal_mcp/applications/application.py +19 -30
- universal_mcp/applications/cal_com_v2/app.py +1676 -1021
- universal_mcp/applications/clickup/app.py +1496 -846
- universal_mcp/applications/falai/README.md +42 -0
- universal_mcp/applications/falai/__init__.py +0 -0
- universal_mcp/applications/falai/app.py +332 -0
- universal_mcp/applications/gong/README.md +88 -0
- universal_mcp/applications/gong/__init__.py +0 -0
- universal_mcp/applications/gong/app.py +2297 -0
- universal_mcp/applications/hashnode/app.py +12 -8
- universal_mcp/applications/hashnode/prompt.md +2 -0
- universal_mcp/applications/heygen/README.md +69 -0
- universal_mcp/applications/heygen/__init__.py +0 -0
- universal_mcp/applications/heygen/app.py +956 -0
- universal_mcp/applications/mailchimp/app.py +3848 -1794
- universal_mcp/applications/replicate/README.md +47 -35
- universal_mcp/applications/replicate/__init__.py +0 -0
- universal_mcp/applications/replicate/app.py +215 -204
- universal_mcp/applications/retell_ai/app.py +84 -67
- universal_mcp/applications/rocketlane/app.py +49 -35
- universal_mcp/applications/spotify/app.py +723 -428
- universal_mcp/applications/supabase/app.py +909 -583
- universal_mcp/servers/server.py +50 -0
- universal_mcp/stores/store.py +2 -3
- universal_mcp/utils/docstring_parser.py +67 -36
- {universal_mcp-0.1.9rc1.dist-info → universal_mcp-0.1.9rc2.dist-info}/METADATA +5 -1
- {universal_mcp-0.1.9rc1.dist-info → universal_mcp-0.1.9rc2.dist-info}/RECORD +29 -19
- {universal_mcp-0.1.9rc1.dist-info → universal_mcp-0.1.9rc2.dist-info}/WHEEL +0 -0
- {universal_mcp-0.1.9rc1.dist-info → universal_mcp-0.1.9rc2.dist-info}/entry_points.txt +0 -0
@@ -6,31 +6,31 @@ from universal_mcp.integrations import Integration
|
|
6
6
|
|
7
7
|
class SpotifyApp(APIApplication):
|
8
8
|
def __init__(self, integration: Integration = None, **kwargs) -> None:
|
9
|
-
super().__init__(name=
|
9
|
+
super().__init__(name="spotify", integration=integration, **kwargs)
|
10
10
|
self.base_url = "https://api.spotify.com/v1"
|
11
11
|
|
12
12
|
def get_an_album(self, id, market=None) -> Any:
|
13
13
|
"""
|
14
14
|
Retrieves detailed information about a specific album by its ID from the API.
|
15
|
-
|
15
|
+
|
16
16
|
Args:
|
17
17
|
id: str. The unique identifier for the album to retrieve. Must not be None.
|
18
18
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code to filter the album's availability. Defaults to None.
|
19
|
-
|
19
|
+
|
20
20
|
Returns:
|
21
21
|
dict. A JSON-decoded dictionary containing album details as returned by the API.
|
22
|
-
|
22
|
+
|
23
23
|
Raises:
|
24
24
|
ValueError: If the 'id' parameter is None.
|
25
25
|
HTTPError: If the HTTP request to the API fails or returns an unsuccessful status code.
|
26
|
-
|
26
|
+
|
27
27
|
Tags:
|
28
28
|
get, album, api, fetch
|
29
29
|
"""
|
30
30
|
if id is None:
|
31
31
|
raise ValueError("Missing required parameter 'id'")
|
32
32
|
url = f"{self.base_url}/albums/{id}"
|
33
|
-
query_params = {k: v for k, v in [(
|
33
|
+
query_params = {k: v for k, v in [("market", market)] if v is not None}
|
34
34
|
response = self._get(url, params=query_params)
|
35
35
|
response.raise_for_status()
|
36
36
|
return response.json()
|
@@ -38,25 +38,27 @@ class SpotifyApp(APIApplication):
|
|
38
38
|
def get_multiple_albums(self, ids, market=None) -> Any:
|
39
39
|
"""
|
40
40
|
Retrieves detailed information for multiple albums by their IDs from the API.
|
41
|
-
|
41
|
+
|
42
42
|
Args:
|
43
43
|
ids: A comma-separated string or list of album IDs to retrieve.
|
44
44
|
market: (Optional) An ISO 3166-1 alpha-2 country code to filter the results based on market availability.
|
45
|
-
|
45
|
+
|
46
46
|
Returns:
|
47
47
|
A JSON-serializable object containing details of the requested albums.
|
48
|
-
|
48
|
+
|
49
49
|
Raises:
|
50
50
|
ValueError: If the 'ids' parameter is not provided.
|
51
51
|
requests.HTTPError: If the HTTP request to the API fails with a status error.
|
52
|
-
|
52
|
+
|
53
53
|
Tags:
|
54
54
|
get, albums, api, list
|
55
55
|
"""
|
56
56
|
if ids is None:
|
57
57
|
raise ValueError("Missing required parameter 'ids'")
|
58
58
|
url = f"{self.base_url}/albums"
|
59
|
-
query_params = {
|
59
|
+
query_params = {
|
60
|
+
k: v for k, v in [("ids", ids), ("market", market)] if v is not None
|
61
|
+
}
|
60
62
|
response = self._get(url, params=query_params)
|
61
63
|
response.raise_for_status()
|
62
64
|
return response.json()
|
@@ -64,27 +66,31 @@ class SpotifyApp(APIApplication):
|
|
64
66
|
def get_an_albums_tracks(self, id, market=None, limit=None, offset=None) -> Any:
|
65
67
|
"""
|
66
68
|
Retrieves the list of tracks for a specified album from the API, with optional filtering and pagination.
|
67
|
-
|
69
|
+
|
68
70
|
Args:
|
69
71
|
id: str. The unique identifier for the album. Required.
|
70
72
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code to filter track availability. Defaults to None.
|
71
73
|
limit: Optional[int]. The maximum number of tracks to return. Defaults to None.
|
72
74
|
offset: Optional[int]. The index of the first track to return. Useful for pagination. Defaults to None.
|
73
|
-
|
75
|
+
|
74
76
|
Returns:
|
75
77
|
Any. A JSON object containing the album's tracks and related pagination information as returned by the API.
|
76
|
-
|
78
|
+
|
77
79
|
Raises:
|
78
80
|
ValueError: If the 'id' parameter is None.
|
79
81
|
HTTPError: If the HTTP request to the API fails (e.g., due to network issues or an invalid album ID).
|
80
|
-
|
82
|
+
|
81
83
|
Tags:
|
82
84
|
get, list, tracks, album, api
|
83
85
|
"""
|
84
86
|
if id is None:
|
85
87
|
raise ValueError("Missing required parameter 'id'")
|
86
88
|
url = f"{self.base_url}/albums/{id}/tracks"
|
87
|
-
query_params = {
|
89
|
+
query_params = {
|
90
|
+
k: v
|
91
|
+
for k, v in [("market", market), ("limit", limit), ("offset", offset)]
|
92
|
+
if v is not None
|
93
|
+
}
|
88
94
|
response = self._get(url, params=query_params)
|
89
95
|
response.raise_for_status()
|
90
96
|
return response.json()
|
@@ -92,17 +98,17 @@ class SpotifyApp(APIApplication):
|
|
92
98
|
def get_an_artist(self, id) -> Any:
|
93
99
|
"""
|
94
100
|
Retrieve detailed information about a specific artist by their unique identifier.
|
95
|
-
|
101
|
+
|
96
102
|
Args:
|
97
103
|
id: The unique identifier of the artist to retrieve. Must not be None.
|
98
|
-
|
104
|
+
|
99
105
|
Returns:
|
100
106
|
A JSON object containing the artist's details as returned by the API.
|
101
|
-
|
107
|
+
|
102
108
|
Raises:
|
103
109
|
ValueError: Raised if the 'id' parameter is None.
|
104
110
|
requests.exceptions.HTTPError: Raised if the HTTP request to fetch the artist fails (e.g., non-2xx status code).
|
105
|
-
|
111
|
+
|
106
112
|
Tags:
|
107
113
|
get, artist, api, fetch
|
108
114
|
"""
|
@@ -117,53 +123,64 @@ class SpotifyApp(APIApplication):
|
|
117
123
|
def get_multiple_artists(self, ids) -> Any:
|
118
124
|
"""
|
119
125
|
Retrieves information for multiple artists using their IDs.
|
120
|
-
|
126
|
+
|
121
127
|
Args:
|
122
128
|
ids: A comma-separated string or list of artist IDs to retrieve information for.
|
123
|
-
|
129
|
+
|
124
130
|
Returns:
|
125
131
|
A JSON object containing details for the specified artists.
|
126
|
-
|
132
|
+
|
127
133
|
Raises:
|
128
134
|
ValueError: Raised if the 'ids' parameter is None.
|
129
135
|
requests.HTTPError: Raised if the HTTP request to the artists endpoint fails.
|
130
|
-
|
136
|
+
|
131
137
|
Tags:
|
132
138
|
get, artists, api, list
|
133
139
|
"""
|
134
140
|
if ids is None:
|
135
141
|
raise ValueError("Missing required parameter 'ids'")
|
136
142
|
url = f"{self.base_url}/artists"
|
137
|
-
query_params = {k: v for k, v in [(
|
143
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
138
144
|
response = self._get(url, params=query_params)
|
139
145
|
response.raise_for_status()
|
140
146
|
return response.json()
|
141
147
|
|
142
|
-
def get_an_artists_albums(
|
148
|
+
def get_an_artists_albums(
|
149
|
+
self, id, include_groups=None, market=None, limit=None, offset=None
|
150
|
+
) -> Any:
|
143
151
|
"""
|
144
152
|
Retrieves a list of albums for the specified artist from the API.
|
145
|
-
|
153
|
+
|
146
154
|
Args:
|
147
155
|
id: str. The unique identifier of the artist whose albums are to be retrieved.
|
148
156
|
include_groups: Optional[str]. A comma-separated list of keywords to filter the album types (e.g., 'album', 'single', 'appears_on', 'compilation').
|
149
157
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code to filter the albums for a specific market.
|
150
158
|
limit: Optional[int]. The maximum number of album objects to return. Default is determined by the API.
|
151
159
|
offset: Optional[int]. The index of the first album to return. Useful for pagination.
|
152
|
-
|
160
|
+
|
153
161
|
Returns:
|
154
162
|
dict. A JSON object containing the artist's albums, as returned by the API.
|
155
|
-
|
163
|
+
|
156
164
|
Raises:
|
157
165
|
ValueError: If the 'id' parameter is not provided.
|
158
166
|
requests.HTTPError: If the HTTP request to the API fails or returns an error status code.
|
159
|
-
|
167
|
+
|
160
168
|
Tags:
|
161
169
|
get, list, albums, artist, api
|
162
170
|
"""
|
163
171
|
if id is None:
|
164
172
|
raise ValueError("Missing required parameter 'id'")
|
165
173
|
url = f"{self.base_url}/artists/{id}/albums"
|
166
|
-
query_params = {
|
174
|
+
query_params = {
|
175
|
+
k: v
|
176
|
+
for k, v in [
|
177
|
+
("include_groups", include_groups),
|
178
|
+
("market", market),
|
179
|
+
("limit", limit),
|
180
|
+
("offset", offset),
|
181
|
+
]
|
182
|
+
if v is not None
|
183
|
+
}
|
167
184
|
response = self._get(url, params=query_params)
|
168
185
|
response.raise_for_status()
|
169
186
|
return response.json()
|
@@ -171,25 +188,25 @@ class SpotifyApp(APIApplication):
|
|
171
188
|
def get_an_artists_top_tracks(self, id, market=None) -> Any:
|
172
189
|
"""
|
173
190
|
Retrieves the top tracks for a specified artist from the API.
|
174
|
-
|
191
|
+
|
175
192
|
Args:
|
176
193
|
id: str. The Spotify ID of the artist whose top tracks are to be retrieved.
|
177
194
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code to filter the top tracks for a specific market. Defaults to None.
|
178
|
-
|
195
|
+
|
179
196
|
Returns:
|
180
197
|
dict. A JSON object containing the artist's top tracks data as returned by the API.
|
181
|
-
|
198
|
+
|
182
199
|
Raises:
|
183
200
|
ValueError: Raised if the required 'id' parameter is not provided.
|
184
201
|
requests.HTTPError: Raised if the HTTP request to the API is unsuccessful.
|
185
|
-
|
202
|
+
|
186
203
|
Tags:
|
187
204
|
get, artist, top-tracks, api, music
|
188
205
|
"""
|
189
206
|
if id is None:
|
190
207
|
raise ValueError("Missing required parameter 'id'")
|
191
208
|
url = f"{self.base_url}/artists/{id}/top-tracks"
|
192
|
-
query_params = {k: v for k, v in [(
|
209
|
+
query_params = {k: v for k, v in [("market", market)] if v is not None}
|
193
210
|
response = self._get(url, params=query_params)
|
194
211
|
response.raise_for_status()
|
195
212
|
return response.json()
|
@@ -197,17 +214,17 @@ class SpotifyApp(APIApplication):
|
|
197
214
|
def get_an_artists_related_artists(self, id) -> Any:
|
198
215
|
"""
|
199
216
|
Retrieves a list of artists related to the specified artist by their unique ID.
|
200
|
-
|
217
|
+
|
201
218
|
Args:
|
202
219
|
id: str. The unique identifier of the artist for whom related artists are to be fetched.
|
203
|
-
|
220
|
+
|
204
221
|
Returns:
|
205
222
|
dict. A JSON-decoded dictionary containing data about artists related to the specified artist.
|
206
|
-
|
223
|
+
|
207
224
|
Raises:
|
208
225
|
ValueError: Raised if the required 'id' parameter is missing or None.
|
209
226
|
HTTPError: Raised if the HTTP request to fetch related artists fails (non-success response).
|
210
|
-
|
227
|
+
|
211
228
|
Tags:
|
212
229
|
fetch, related-artists, ai, api
|
213
230
|
"""
|
@@ -222,25 +239,25 @@ class SpotifyApp(APIApplication):
|
|
222
239
|
def get_a_show(self, id, market=None) -> Any:
|
223
240
|
"""
|
224
241
|
Retrieve detailed information about a show by its unique identifier.
|
225
|
-
|
242
|
+
|
226
243
|
Args:
|
227
244
|
id: str. The unique identifier of the show to retrieve. Must not be None.
|
228
245
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code. If provided, restricts the show details to the specified market.
|
229
|
-
|
246
|
+
|
230
247
|
Returns:
|
231
248
|
dict. A dictionary containing the show's information as returned by the API.
|
232
|
-
|
249
|
+
|
233
250
|
Raises:
|
234
251
|
ValueError: Raised if the 'id' parameter is None.
|
235
252
|
requests.HTTPError: Raised if the HTTP request for the show details fails.
|
236
|
-
|
253
|
+
|
237
254
|
Tags:
|
238
255
|
get, show, api, fetch
|
239
256
|
"""
|
240
257
|
if id is None:
|
241
258
|
raise ValueError("Missing required parameter 'id'")
|
242
259
|
url = f"{self.base_url}/shows/{id}"
|
243
|
-
query_params = {k: v for k, v in [(
|
260
|
+
query_params = {k: v for k, v in [("market", market)] if v is not None}
|
244
261
|
response = self._get(url, params=query_params)
|
245
262
|
response.raise_for_status()
|
246
263
|
return response.json()
|
@@ -248,25 +265,27 @@ class SpotifyApp(APIApplication):
|
|
248
265
|
def get_multiple_shows(self, ids, market=None) -> Any:
|
249
266
|
"""
|
250
267
|
Retrieves information for multiple shows by their IDs, with optional market filtering.
|
251
|
-
|
268
|
+
|
252
269
|
Args:
|
253
270
|
ids: str or list of str. A comma-separated list or sequence of show IDs to retrieve information for. This parameter is required.
|
254
271
|
market: Optional[str]. An optional ISO 3166-1 alpha-2 country code to filter show availability.
|
255
|
-
|
272
|
+
|
256
273
|
Returns:
|
257
274
|
dict. The JSON response containing show details for the specified IDs.
|
258
|
-
|
275
|
+
|
259
276
|
Raises:
|
260
277
|
ValueError: Raised if the 'ids' parameter is not provided.
|
261
278
|
requests.HTTPError: Raised if an HTTP error occurs during the API request.
|
262
|
-
|
279
|
+
|
263
280
|
Tags:
|
264
281
|
get, list, shows, api, batch
|
265
282
|
"""
|
266
283
|
if ids is None:
|
267
284
|
raise ValueError("Missing required parameter 'ids'")
|
268
285
|
url = f"{self.base_url}/shows"
|
269
|
-
query_params = {
|
286
|
+
query_params = {
|
287
|
+
k: v for k, v in [("market", market), ("ids", ids)] if v is not None
|
288
|
+
}
|
270
289
|
response = self._get(url, params=query_params)
|
271
290
|
response.raise_for_status()
|
272
291
|
return response.json()
|
@@ -274,27 +293,31 @@ class SpotifyApp(APIApplication):
|
|
274
293
|
def get_a_shows_episodes(self, id, market=None, limit=None, offset=None) -> Any:
|
275
294
|
"""
|
276
295
|
Retrieves episodes for a specific show from the API with optional market, limit, and offset parameters.
|
277
|
-
|
296
|
+
|
278
297
|
Args:
|
279
298
|
id: str. The unique identifier of the show whose episodes are to be retrieved.
|
280
299
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code to filter episodes available in a particular market.
|
281
300
|
limit: Optional[int]. The maximum number of episodes to return. Optional.
|
282
301
|
offset: Optional[int]. The index of the first episode to return. Optional.
|
283
|
-
|
302
|
+
|
284
303
|
Returns:
|
285
304
|
Any. A JSON-decoded object containing the episodes information for the specified show.
|
286
|
-
|
305
|
+
|
287
306
|
Raises:
|
288
307
|
ValueError: If the required 'id' parameter is None.
|
289
308
|
HTTPError: If the HTTP request to the API fails (non-2xx status code).
|
290
|
-
|
309
|
+
|
291
310
|
Tags:
|
292
311
|
get, episodes, api, list, management
|
293
312
|
"""
|
294
313
|
if id is None:
|
295
314
|
raise ValueError("Missing required parameter 'id'")
|
296
315
|
url = f"{self.base_url}/shows/{id}/episodes"
|
297
|
-
query_params = {
|
316
|
+
query_params = {
|
317
|
+
k: v
|
318
|
+
for k, v in [("market", market), ("limit", limit), ("offset", offset)]
|
319
|
+
if v is not None
|
320
|
+
}
|
298
321
|
response = self._get(url, params=query_params)
|
299
322
|
response.raise_for_status()
|
300
323
|
return response.json()
|
@@ -302,25 +325,25 @@ class SpotifyApp(APIApplication):
|
|
302
325
|
def get_an_episode(self, id, market=None) -> Any:
|
303
326
|
"""
|
304
327
|
Retrieves a single podcast episode's details by its unique identifier.
|
305
|
-
|
328
|
+
|
306
329
|
Args:
|
307
330
|
id: str. Unique identifier of the episode to retrieve. Required.
|
308
331
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code to filter the episode for a specific market. Defaults to None.
|
309
|
-
|
332
|
+
|
310
333
|
Returns:
|
311
334
|
dict. The JSON-decoded response containing episode details.
|
312
|
-
|
335
|
+
|
313
336
|
Raises:
|
314
337
|
ValueError: Raised if the 'id' parameter is None.
|
315
338
|
requests.exceptions.HTTPError: Raised if the HTTP request to retrieve the episode fails.
|
316
|
-
|
339
|
+
|
317
340
|
Tags:
|
318
341
|
get, episode, api, fetch, single-item
|
319
342
|
"""
|
320
343
|
if id is None:
|
321
344
|
raise ValueError("Missing required parameter 'id'")
|
322
345
|
url = f"{self.base_url}/episodes/{id}"
|
323
|
-
query_params = {k: v for k, v in [(
|
346
|
+
query_params = {k: v for k, v in [("market", market)] if v is not None}
|
324
347
|
response = self._get(url, params=query_params)
|
325
348
|
response.raise_for_status()
|
326
349
|
return response.json()
|
@@ -328,25 +351,27 @@ class SpotifyApp(APIApplication):
|
|
328
351
|
def get_multiple_episodes(self, ids, market=None) -> Any:
|
329
352
|
"""
|
330
353
|
Retrieves details for multiple podcast episodes using their IDs, optionally filtered by market.
|
331
|
-
|
354
|
+
|
332
355
|
Args:
|
333
356
|
ids: str. A comma-separated list of episode IDs to retrieve.
|
334
357
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code to filter the episodes based on market (defaults to None).
|
335
|
-
|
358
|
+
|
336
359
|
Returns:
|
337
360
|
Any. The response JSON containing details of the requested episodes.
|
338
|
-
|
361
|
+
|
339
362
|
Raises:
|
340
363
|
ValueError: Raised if the required parameter 'ids' is not provided.
|
341
364
|
requests.HTTPError: Raised if the HTTP request to the API endpoint returns an unsuccessful status code.
|
342
|
-
|
365
|
+
|
343
366
|
Tags:
|
344
367
|
get, episodes, batch, podcast, api
|
345
368
|
"""
|
346
369
|
if ids is None:
|
347
370
|
raise ValueError("Missing required parameter 'ids'")
|
348
371
|
url = f"{self.base_url}/episodes"
|
349
|
-
query_params = {
|
372
|
+
query_params = {
|
373
|
+
k: v for k, v in [("ids", ids), ("market", market)] if v is not None
|
374
|
+
}
|
350
375
|
response = self._get(url, params=query_params)
|
351
376
|
response.raise_for_status()
|
352
377
|
return response.json()
|
@@ -354,25 +379,25 @@ class SpotifyApp(APIApplication):
|
|
354
379
|
def get_an_audiobook(self, id, market=None) -> Any:
|
355
380
|
"""
|
356
381
|
Retrieves detailed information about a specific audiobook by ID, optionally filtered by market.
|
357
|
-
|
382
|
+
|
358
383
|
Args:
|
359
384
|
id: str. The unique identifier of the audiobook to retrieve.
|
360
385
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code to filter audiobook availability. Defaults to None.
|
361
|
-
|
386
|
+
|
362
387
|
Returns:
|
363
388
|
dict. A dictionary containing audiobook details as returned from the API.
|
364
|
-
|
389
|
+
|
365
390
|
Raises:
|
366
391
|
ValueError: Raised if the 'id' parameter is not provided.
|
367
392
|
requests.HTTPError: Raised if the HTTP request to the audiobook API fails (non-2xx status code).
|
368
|
-
|
393
|
+
|
369
394
|
Tags:
|
370
395
|
get, audiobook, api, details, fetch
|
371
396
|
"""
|
372
397
|
if id is None:
|
373
398
|
raise ValueError("Missing required parameter 'id'")
|
374
399
|
url = f"{self.base_url}/audiobooks/{id}"
|
375
|
-
query_params = {k: v for k, v in [(
|
400
|
+
query_params = {k: v for k, v in [("market", market)] if v is not None}
|
376
401
|
response = self._get(url, params=query_params)
|
377
402
|
response.raise_for_status()
|
378
403
|
return response.json()
|
@@ -380,25 +405,27 @@ class SpotifyApp(APIApplication):
|
|
380
405
|
def get_multiple_audiobooks(self, ids, market=None) -> Any:
|
381
406
|
"""
|
382
407
|
Fetches details for multiple audiobooks by their IDs, optionally filtered by market.
|
383
|
-
|
408
|
+
|
384
409
|
Args:
|
385
410
|
ids: A list or comma-separated string of audiobook IDs to retrieve.
|
386
411
|
market: Optional; a string specifying the market to filter results by.
|
387
|
-
|
412
|
+
|
388
413
|
Returns:
|
389
414
|
A dictionary containing details of the requested audiobooks as parsed from the JSON API response.
|
390
|
-
|
415
|
+
|
391
416
|
Raises:
|
392
417
|
ValueError: Raised if 'ids' is not provided.
|
393
418
|
requests.exceptions.HTTPError: Raised if the API response contains a failed HTTP status.
|
394
|
-
|
419
|
+
|
395
420
|
Tags:
|
396
421
|
get, audiobook, batch, api
|
397
422
|
"""
|
398
423
|
if ids is None:
|
399
424
|
raise ValueError("Missing required parameter 'ids'")
|
400
425
|
url = f"{self.base_url}/audiobooks"
|
401
|
-
query_params = {
|
426
|
+
query_params = {
|
427
|
+
k: v for k, v in [("ids", ids), ("market", market)] if v is not None
|
428
|
+
}
|
402
429
|
response = self._get(url, params=query_params)
|
403
430
|
response.raise_for_status()
|
404
431
|
return response.json()
|
@@ -406,27 +433,31 @@ class SpotifyApp(APIApplication):
|
|
406
433
|
def get_audiobook_chapters(self, id, market=None, limit=None, offset=None) -> Any:
|
407
434
|
"""
|
408
435
|
Retrieves the chapters for a specified audiobook from the API.
|
409
|
-
|
436
|
+
|
410
437
|
Args:
|
411
438
|
id: str. The unique identifier of the audiobook whose chapters are to be retrieved.
|
412
439
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code specifying the market for the chapters. Defaults to None.
|
413
440
|
limit: Optional[int]. The maximum number of chapters to return. Defaults to None.
|
414
441
|
offset: Optional[int]. The index of the first chapter to return. Used for pagination. Defaults to None.
|
415
|
-
|
442
|
+
|
416
443
|
Returns:
|
417
444
|
dict. A JSON response containing audiobook chapter details as returned by the API.
|
418
|
-
|
445
|
+
|
419
446
|
Raises:
|
420
447
|
ValueError: If the 'id' parameter is not provided.
|
421
448
|
requests.HTTPError: If the API request fails with a non-successful HTTP status code.
|
422
|
-
|
449
|
+
|
423
450
|
Tags:
|
424
451
|
get, audiobook, chapters, api, fetch
|
425
452
|
"""
|
426
453
|
if id is None:
|
427
454
|
raise ValueError("Missing required parameter 'id'")
|
428
455
|
url = f"{self.base_url}/audiobooks/{id}/chapters"
|
429
|
-
query_params = {
|
456
|
+
query_params = {
|
457
|
+
k: v
|
458
|
+
for k, v in [("market", market), ("limit", limit), ("offset", offset)]
|
459
|
+
if v is not None
|
460
|
+
}
|
430
461
|
response = self._get(url, params=query_params)
|
431
462
|
response.raise_for_status()
|
432
463
|
return response.json()
|
@@ -434,22 +465,24 @@ class SpotifyApp(APIApplication):
|
|
434
465
|
def get_users_saved_audiobooks(self, limit=None, offset=None) -> Any:
|
435
466
|
"""
|
436
467
|
Retrieves the current user's saved audiobooks from the API with optional pagination.
|
437
|
-
|
468
|
+
|
438
469
|
Args:
|
439
470
|
limit: Optional; int or None. The maximum number of audiobooks to return. If None, the API default is used.
|
440
471
|
offset: Optional; int or None. The index of the first audiobook to retrieve. If None, the API default is used.
|
441
|
-
|
472
|
+
|
442
473
|
Returns:
|
443
474
|
dict: A JSON-decoded dictionary containing the user's saved audiobooks.
|
444
|
-
|
475
|
+
|
445
476
|
Raises:
|
446
477
|
requests.exceptions.HTTPError: If the HTTP request to the API fails or returns an unsuccessful status code.
|
447
|
-
|
478
|
+
|
448
479
|
Tags:
|
449
480
|
get, list, audiobooks, user-data, api
|
450
481
|
"""
|
451
482
|
url = f"{self.base_url}/me/audiobooks"
|
452
|
-
query_params = {
|
483
|
+
query_params = {
|
484
|
+
k: v for k, v in [("limit", limit), ("offset", offset)] if v is not None
|
485
|
+
}
|
453
486
|
response = self._get(url, params=query_params)
|
454
487
|
response.raise_for_status()
|
455
488
|
return response.json()
|
@@ -457,24 +490,24 @@ class SpotifyApp(APIApplication):
|
|
457
490
|
def save_audiobooks_user(self, ids) -> Any:
|
458
491
|
"""
|
459
492
|
Saves one or more audiobooks to the current user's library.
|
460
|
-
|
493
|
+
|
461
494
|
Args:
|
462
495
|
ids: A comma-separated string or list of audiobook IDs to add to the user's library. Must not be None.
|
463
|
-
|
496
|
+
|
464
497
|
Returns:
|
465
498
|
The JSON-decoded response from the API, typically containing the result of the save operation.
|
466
|
-
|
499
|
+
|
467
500
|
Raises:
|
468
501
|
ValueError: If 'ids' is None.
|
469
502
|
HTTPError: If the API request fails due to an unsuccessful HTTP response status.
|
470
|
-
|
503
|
+
|
471
504
|
Tags:
|
472
505
|
save, audiobooks, user, management, api
|
473
506
|
"""
|
474
507
|
if ids is None:
|
475
508
|
raise ValueError("Missing required parameter 'ids'")
|
476
509
|
url = f"{self.base_url}/me/audiobooks"
|
477
|
-
query_params = {k: v for k, v in [(
|
510
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
478
511
|
response = self._put(url, data={}, params=query_params)
|
479
512
|
response.raise_for_status()
|
480
513
|
return response.json()
|
@@ -482,24 +515,24 @@ class SpotifyApp(APIApplication):
|
|
482
515
|
def remove_audiobooks_user(self, ids) -> Any:
|
483
516
|
"""
|
484
517
|
Removes one or more audiobooks from the authenticated user's library.
|
485
|
-
|
518
|
+
|
486
519
|
Args:
|
487
520
|
ids: The identifier or list of identifiers of the audiobooks to remove.
|
488
|
-
|
521
|
+
|
489
522
|
Returns:
|
490
523
|
The API response as a parsed JSON object containing the result of the deletion operation.
|
491
|
-
|
524
|
+
|
492
525
|
Raises:
|
493
526
|
ValueError: If the 'ids' parameter is None.
|
494
527
|
requests.HTTPError: If the HTTP request to delete audiobooks does not succeed.
|
495
|
-
|
528
|
+
|
496
529
|
Tags:
|
497
530
|
remove, audiobooks, user-library, management
|
498
531
|
"""
|
499
532
|
if ids is None:
|
500
533
|
raise ValueError("Missing required parameter 'ids'")
|
501
534
|
url = f"{self.base_url}/me/audiobooks"
|
502
|
-
query_params = {k: v for k, v in [(
|
535
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
503
536
|
response = self._delete(url, params=query_params)
|
504
537
|
response.raise_for_status()
|
505
538
|
return response.json()
|
@@ -507,24 +540,24 @@ class SpotifyApp(APIApplication):
|
|
507
540
|
def check_users_saved_audiobooks(self, ids) -> Any:
|
508
541
|
"""
|
509
542
|
Checks if the specified audiobooks are saved in the current user's library.
|
510
|
-
|
543
|
+
|
511
544
|
Args:
|
512
545
|
ids: A string or list of audiobook IDs to check. Each ID should correspond to an audiobook in the catalog.
|
513
|
-
|
546
|
+
|
514
547
|
Returns:
|
515
548
|
A JSON-serializable object (typically a list of booleans) indicating whether each audiobook is saved by the user.
|
516
|
-
|
549
|
+
|
517
550
|
Raises:
|
518
551
|
ValueError: Raised if the 'ids' parameter is None.
|
519
552
|
HTTPError: Raised if the HTTP request to the API fails with an error status.
|
520
|
-
|
553
|
+
|
521
554
|
Tags:
|
522
555
|
check, audiobooks, user-library, api
|
523
556
|
"""
|
524
557
|
if ids is None:
|
525
558
|
raise ValueError("Missing required parameter 'ids'")
|
526
559
|
url = f"{self.base_url}/me/audiobooks/contains"
|
527
|
-
query_params = {k: v for k, v in [(
|
560
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
528
561
|
response = self._get(url, params=query_params)
|
529
562
|
response.raise_for_status()
|
530
563
|
return response.json()
|
@@ -532,25 +565,25 @@ class SpotifyApp(APIApplication):
|
|
532
565
|
def get_a_chapter(self, id, market=None) -> Any:
|
533
566
|
"""
|
534
567
|
Retrieves a specific chapter's details by ID from the API, optionally filtering by market.
|
535
|
-
|
568
|
+
|
536
569
|
Args:
|
537
570
|
id: The unique identifier of the chapter to retrieve. Must not be None.
|
538
571
|
market: Optional; a string specifying a market code to filter the chapter details.
|
539
|
-
|
572
|
+
|
540
573
|
Returns:
|
541
574
|
A JSON-decoded object containing the details of the requested chapter.
|
542
|
-
|
575
|
+
|
543
576
|
Raises:
|
544
577
|
ValueError: Raised when the required 'id' parameter is missing (None).
|
545
578
|
HTTPError: Raised if the HTTP request to the API fails or returns an unsuccessful status.
|
546
|
-
|
579
|
+
|
547
580
|
Tags:
|
548
581
|
get, chapter, api, data-retrieval
|
549
582
|
"""
|
550
583
|
if id is None:
|
551
584
|
raise ValueError("Missing required parameter 'id'")
|
552
585
|
url = f"{self.base_url}/chapters/{id}"
|
553
|
-
query_params = {k: v for k, v in [(
|
586
|
+
query_params = {k: v for k, v in [("market", market)] if v is not None}
|
554
587
|
response = self._get(url, params=query_params)
|
555
588
|
response.raise_for_status()
|
556
589
|
return response.json()
|
@@ -558,25 +591,27 @@ class SpotifyApp(APIApplication):
|
|
558
591
|
def get_several_chapters(self, ids, market=None) -> Any:
|
559
592
|
"""
|
560
593
|
Retrieve details for multiple chapters based on their IDs, optionally filtering by market.
|
561
|
-
|
594
|
+
|
562
595
|
Args:
|
563
596
|
ids: List or string of chapter IDs to retrieve. This parameter is required.
|
564
597
|
market: Optional market code to filter the chapters by region or market. Defaults to None.
|
565
|
-
|
598
|
+
|
566
599
|
Returns:
|
567
600
|
A JSON-decoded response containing details for the specified chapters.
|
568
|
-
|
601
|
+
|
569
602
|
Raises:
|
570
603
|
ValueError: If the 'ids' parameter is None.
|
571
604
|
HTTPError: If the HTTP request to the chapters endpoint returns an error response.
|
572
|
-
|
605
|
+
|
573
606
|
Tags:
|
574
607
|
get, chapters, batch, api
|
575
608
|
"""
|
576
609
|
if ids is None:
|
577
610
|
raise ValueError("Missing required parameter 'ids'")
|
578
611
|
url = f"{self.base_url}/chapters"
|
579
|
-
query_params = {
|
612
|
+
query_params = {
|
613
|
+
k: v for k, v in [("ids", ids), ("market", market)] if v is not None
|
614
|
+
}
|
580
615
|
response = self._get(url, params=query_params)
|
581
616
|
response.raise_for_status()
|
582
617
|
return response.json()
|
@@ -584,25 +619,25 @@ class SpotifyApp(APIApplication):
|
|
584
619
|
def get_track(self, id, market=None) -> Any:
|
585
620
|
"""
|
586
621
|
Retrieves detailed information about a track by its unique identifier from the external API.
|
587
|
-
|
622
|
+
|
588
623
|
Args:
|
589
624
|
id: str. The unique identifier for the track to retrieve. Must not be None.
|
590
625
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code to filter the track's availability (default is None).
|
591
|
-
|
626
|
+
|
592
627
|
Returns:
|
593
628
|
dict. The JSON response containing track details from the API.
|
594
|
-
|
629
|
+
|
595
630
|
Raises:
|
596
631
|
ValueError: If the required 'id' parameter is None.
|
597
632
|
HTTPError: If the API request returns an unsuccessful HTTP status code.
|
598
|
-
|
633
|
+
|
599
634
|
Tags:
|
600
635
|
get, track, api, fetch
|
601
636
|
"""
|
602
637
|
if id is None:
|
603
638
|
raise ValueError("Missing required parameter 'id'")
|
604
639
|
url = f"{self.base_url}/tracks/{id}"
|
605
|
-
query_params = {k: v for k, v in [(
|
640
|
+
query_params = {k: v for k, v in [("market", market)] if v is not None}
|
606
641
|
response = self._get(url, params=query_params)
|
607
642
|
response.raise_for_status()
|
608
643
|
return response.json()
|
@@ -610,33 +645,37 @@ class SpotifyApp(APIApplication):
|
|
610
645
|
def get_several_tracks(self, ids, market=None) -> Any:
|
611
646
|
"""
|
612
647
|
Retrieves metadata for multiple tracks based on their IDs from the API.
|
613
|
-
|
648
|
+
|
614
649
|
Args:
|
615
650
|
ids: A comma-separated list or iterable of track IDs to retrieve metadata for. This parameter is required.
|
616
651
|
market: An optional ISO 3166-1 alpha-2 country code to filter the track data. Defaults to None.
|
617
|
-
|
652
|
+
|
618
653
|
Returns:
|
619
654
|
A dictionary containing the metadata of the requested tracks as returned by the API.
|
620
|
-
|
655
|
+
|
621
656
|
Raises:
|
622
657
|
ValueError: If 'ids' is not provided (None), indicating that required parameter is missing.
|
623
658
|
requests.HTTPError: If the HTTP request to the API fails or returns a non-success status code.
|
624
|
-
|
659
|
+
|
625
660
|
Tags:
|
626
661
|
get, tracks, api, metadata
|
627
662
|
"""
|
628
663
|
if ids is None:
|
629
664
|
raise ValueError("Missing required parameter 'ids'")
|
630
665
|
url = f"{self.base_url}/tracks"
|
631
|
-
query_params = {
|
666
|
+
query_params = {
|
667
|
+
k: v for k, v in [("market", market), ("ids", ids)] if v is not None
|
668
|
+
}
|
632
669
|
response = self._get(url, params=query_params)
|
633
670
|
response.raise_for_status()
|
634
671
|
return response.json()
|
635
672
|
|
636
|
-
def search(
|
673
|
+
def search(
|
674
|
+
self, q, type, market=None, limit=None, offset=None, include_external=None
|
675
|
+
) -> Any:
|
637
676
|
"""
|
638
677
|
Performs a search query against the API and returns the matching results as a JSON object.
|
639
|
-
|
678
|
+
|
640
679
|
Args:
|
641
680
|
q: str. The search query string. Required.
|
642
681
|
type: str or list of str. The type(s) of item to search for (e.g., 'track', 'artist'). Required.
|
@@ -644,14 +683,14 @@ class SpotifyApp(APIApplication):
|
|
644
683
|
limit: Optional[int]. Maximum number of results to return. Optional.
|
645
684
|
offset: Optional[int]. The index of the first result to return. Optional.
|
646
685
|
include_external: Optional[str]. If 'audio', the response will include any relevant audio content. Optional.
|
647
|
-
|
686
|
+
|
648
687
|
Returns:
|
649
688
|
dict. The JSON response containing search results.
|
650
|
-
|
689
|
+
|
651
690
|
Raises:
|
652
691
|
ValueError: If the required parameter 'q' or 'type' is missing.
|
653
692
|
requests.HTTPError: If the HTTP request fails or the server returns an error status.
|
654
|
-
|
693
|
+
|
655
694
|
Tags:
|
656
695
|
search, api, query, async-job, important
|
657
696
|
"""
|
@@ -660,24 +699,37 @@ class SpotifyApp(APIApplication):
|
|
660
699
|
if type is None:
|
661
700
|
raise ValueError("Missing required parameter 'type'")
|
662
701
|
url = f"{self.base_url}/search"
|
663
|
-
query_params = {
|
702
|
+
query_params = {
|
703
|
+
k: v
|
704
|
+
for k, v in [
|
705
|
+
("q", q),
|
706
|
+
("type", type),
|
707
|
+
("market", market),
|
708
|
+
("limit", limit),
|
709
|
+
("offset", offset),
|
710
|
+
("include_external", include_external),
|
711
|
+
]
|
712
|
+
if v is not None
|
713
|
+
}
|
664
714
|
response = self._get(url, params=query_params)
|
665
715
|
response.raise_for_status()
|
666
716
|
return response.json()
|
667
717
|
|
668
|
-
def get_current_users_profile(
|
718
|
+
def get_current_users_profile(
|
719
|
+
self,
|
720
|
+
) -> Any:
|
669
721
|
"""
|
670
722
|
Retrieves the current authenticated user's profile information from the API.
|
671
|
-
|
723
|
+
|
672
724
|
Args:
|
673
725
|
None: This function takes no arguments
|
674
|
-
|
726
|
+
|
675
727
|
Returns:
|
676
728
|
dict: A dictionary containing the user's profile data as returned by the API.
|
677
|
-
|
729
|
+
|
678
730
|
Raises:
|
679
731
|
requests.exceptions.HTTPError: If the HTTP request returned an unsuccessful status code.
|
680
|
-
|
732
|
+
|
681
733
|
Tags:
|
682
734
|
get, profile, user, api
|
683
735
|
"""
|
@@ -687,62 +739,74 @@ class SpotifyApp(APIApplication):
|
|
687
739
|
response.raise_for_status()
|
688
740
|
return response.json()
|
689
741
|
|
690
|
-
def get_playlist(
|
742
|
+
def get_playlist(
|
743
|
+
self, playlist_id, market=None, fields=None, additional_types=None
|
744
|
+
) -> Any:
|
691
745
|
"""
|
692
746
|
Retrieves a playlist from the API using the specified playlist ID.
|
693
|
-
|
747
|
+
|
694
748
|
Args:
|
695
749
|
playlist_id: The ID of the playlist to retrieve. Required.
|
696
750
|
market: Optional. An ISO 3166-1 alpha-2 country code or the string 'from_token' to specify the market to get content for.
|
697
751
|
fields: Optional. Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned.
|
698
752
|
additional_types: Optional. A comma-separated list of item types that your client supports besides the default track type.
|
699
|
-
|
753
|
+
|
700
754
|
Returns:
|
701
755
|
A dictionary containing the playlist data in JSON format.
|
702
|
-
|
756
|
+
|
703
757
|
Raises:
|
704
758
|
ValueError: If the required playlist_id parameter is None or not provided.
|
705
759
|
HTTPError: If the API request fails (through raise_for_status()).
|
706
|
-
|
760
|
+
|
707
761
|
Tags:
|
708
762
|
retrieve, get, playlist, api, important
|
709
763
|
"""
|
710
764
|
if playlist_id is None:
|
711
765
|
raise ValueError("Missing required parameter 'playlist_id'")
|
712
766
|
url = f"{self.base_url}/playlists/{playlist_id}"
|
713
|
-
query_params = {
|
767
|
+
query_params = {
|
768
|
+
k: v
|
769
|
+
for k, v in [
|
770
|
+
("market", market),
|
771
|
+
("fields", fields),
|
772
|
+
("additional_types", additional_types),
|
773
|
+
]
|
774
|
+
if v is not None
|
775
|
+
}
|
714
776
|
response = self._get(url, params=query_params)
|
715
777
|
response.raise_for_status()
|
716
778
|
return response.json()
|
717
779
|
|
718
|
-
def change_playlist_details(
|
780
|
+
def change_playlist_details(
|
781
|
+
self, playlist_id, name=None, public=None, collaborative=None, description=None
|
782
|
+
) -> Any:
|
719
783
|
"""
|
720
784
|
Update the details of an existing playlist with the specified attributes.
|
721
|
-
|
785
|
+
|
722
786
|
Args:
|
723
787
|
playlist_id: str. The unique identifier of the playlist to update. Must not be None.
|
724
788
|
name: Optional[str]. New name for the playlist. If None, the name is not changed.
|
725
789
|
public: Optional[bool]. Whether the playlist should be public. If None, the setting is unchanged.
|
726
790
|
collaborative: Optional[bool]. Whether the playlist should be collaborative. If None, the setting is unchanged.
|
727
791
|
description: Optional[str]. New description for the playlist. If None, the description is not changed.
|
728
|
-
|
792
|
+
|
729
793
|
Returns:
|
730
794
|
dict. The JSON response containing the updated playlist details.
|
731
|
-
|
795
|
+
|
732
796
|
Raises:
|
733
797
|
ValueError: Raised if 'playlist_id' is None.
|
734
798
|
requests.HTTPError: Raised if the API request returns an unsuccessful status code.
|
735
|
-
|
799
|
+
|
736
800
|
Tags:
|
737
801
|
change, update, playlist, management, api
|
738
802
|
"""
|
739
803
|
if playlist_id is None:
|
740
804
|
raise ValueError("Missing required parameter 'playlist_id'")
|
741
805
|
request_body = {
|
742
|
-
|
743
|
-
|
744
|
-
|
745
|
-
|
806
|
+
"name": name,
|
807
|
+
"public": public,
|
808
|
+
"collaborative": collaborative,
|
809
|
+
"description": description,
|
746
810
|
}
|
747
811
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
748
812
|
url = f"{self.base_url}/playlists/{playlist_id}"
|
@@ -751,10 +815,18 @@ class SpotifyApp(APIApplication):
|
|
751
815
|
response.raise_for_status()
|
752
816
|
return response.json()
|
753
817
|
|
754
|
-
def get_playlists_tracks(
|
818
|
+
def get_playlists_tracks(
|
819
|
+
self,
|
820
|
+
playlist_id,
|
821
|
+
market=None,
|
822
|
+
fields=None,
|
823
|
+
limit=None,
|
824
|
+
offset=None,
|
825
|
+
additional_types=None,
|
826
|
+
) -> Any:
|
755
827
|
"""
|
756
828
|
Retrieves the tracks of a specified playlist from the API, applying optional filters and pagination parameters.
|
757
|
-
|
829
|
+
|
758
830
|
Args:
|
759
831
|
playlist_id: str. The unique identifier of the playlist to retrieve tracks from.
|
760
832
|
market: Optional[str]. An ISO 3166-1 alpha-2 country code, or 'from_token'. Filters the response to a specific market.
|
@@ -762,21 +834,31 @@ class SpotifyApp(APIApplication):
|
|
762
834
|
limit: Optional[int]. The maximum number of items to return (default and maximum are API-dependent).
|
763
835
|
offset: Optional[int]. The index of the first item to return for pagination.
|
764
836
|
additional_types: Optional[str]. Types of items to return, e.g., 'track', 'episode'.
|
765
|
-
|
837
|
+
|
766
838
|
Returns:
|
767
839
|
dict. JSON response containing the playlist's tracks and associated metadata.
|
768
|
-
|
840
|
+
|
769
841
|
Raises:
|
770
842
|
ValueError: If 'playlist_id' is None.
|
771
843
|
requests.HTTPError: If the API request fails due to a client or server error.
|
772
|
-
|
844
|
+
|
773
845
|
Tags:
|
774
846
|
get, list, playlist, tracks, api, management, important
|
775
847
|
"""
|
776
848
|
if playlist_id is None:
|
777
849
|
raise ValueError("Missing required parameter 'playlist_id'")
|
778
850
|
url = f"{self.base_url}/playlists/{playlist_id}/tracks"
|
779
|
-
query_params = {
|
851
|
+
query_params = {
|
852
|
+
k: v
|
853
|
+
for k, v in [
|
854
|
+
("market", market),
|
855
|
+
("fields", fields),
|
856
|
+
("limit", limit),
|
857
|
+
("offset", offset),
|
858
|
+
("additional_types", additional_types),
|
859
|
+
]
|
860
|
+
if v is not None
|
861
|
+
}
|
780
862
|
response = self._get(url, params=query_params)
|
781
863
|
response.raise_for_status()
|
782
864
|
return response.json()
|
@@ -784,39 +866,49 @@ class SpotifyApp(APIApplication):
|
|
784
866
|
def add_tracks_to_playlist(self, playlist_id, position=None, uris=None) -> Any:
|
785
867
|
"""
|
786
868
|
Adds one or more tracks to a specified playlist at an optional position.
|
787
|
-
|
869
|
+
|
788
870
|
Args:
|
789
871
|
playlist_id: str. The unique identifier of the playlist to which tracks will be added.
|
790
872
|
position: Optional[int]. The position in the playlist where the tracks should be inserted. If not specified, tracks will be added to the end.
|
791
873
|
uris: Optional[List[str]]. A list of track URIs to add to the playlist. If not specified, no tracks will be added.
|
792
|
-
|
874
|
+
|
793
875
|
Returns:
|
794
876
|
dict: The JSON response from the API containing information about the operation result.
|
795
|
-
|
877
|
+
|
796
878
|
Raises:
|
797
879
|
ValueError: If 'playlist_id' is not provided.
|
798
880
|
requests.HTTPError: If the HTTP request to the external API fails or returns an error status code.
|
799
|
-
|
881
|
+
|
800
882
|
Tags:
|
801
883
|
add, playlist-management, tracks, api, important
|
802
884
|
"""
|
803
885
|
if playlist_id is None:
|
804
886
|
raise ValueError("Missing required parameter 'playlist_id'")
|
805
887
|
request_body = {
|
806
|
-
|
807
|
-
|
888
|
+
"uris": uris,
|
889
|
+
"position": position,
|
808
890
|
}
|
809
891
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
810
892
|
url = f"{self.base_url}/playlists/{playlist_id}/tracks"
|
811
|
-
query_params = {
|
893
|
+
query_params = {
|
894
|
+
k: v for k, v in [("position", position), ("uris", uris)] if v is not None
|
895
|
+
}
|
812
896
|
response = self._post(url, data=request_body, params=query_params)
|
813
897
|
response.raise_for_status()
|
814
898
|
return response.json()
|
815
899
|
|
816
|
-
def reorder_or_replace_playlists_tracks(
|
900
|
+
def reorder_or_replace_playlists_tracks(
|
901
|
+
self,
|
902
|
+
playlist_id,
|
903
|
+
uris=None,
|
904
|
+
range_start=None,
|
905
|
+
insert_before=None,
|
906
|
+
range_length=None,
|
907
|
+
snapshot_id=None,
|
908
|
+
) -> Any:
|
817
909
|
"""
|
818
910
|
Reorders or replaces tracks in a playlist by moving, inserting, or replacing track entries using the specified parameters.
|
819
|
-
|
911
|
+
|
820
912
|
Args:
|
821
913
|
playlist_id: str. The Spotify ID of the playlist to be modified. Required.
|
822
914
|
uris: Optional[list of str]. The new track URIs to replace the playlist's tracks. If provided, replaces tracks instead of reordering.
|
@@ -824,29 +916,29 @@ class SpotifyApp(APIApplication):
|
|
824
916
|
insert_before: Optional[int]. The position where the reordered tracks should be inserted. Required for reordering.
|
825
917
|
range_length: Optional[int]. The number of tracks to be reordered. Defaults to 1 if not specified.
|
826
918
|
snapshot_id: Optional[str]. The playlist's snapshot ID against which to apply changes, used for concurrency control.
|
827
|
-
|
919
|
+
|
828
920
|
Returns:
|
829
921
|
dict. The JSON response from the Spotify API containing the new snapshot ID of the playlist.
|
830
|
-
|
922
|
+
|
831
923
|
Raises:
|
832
924
|
ValueError: If 'playlist_id' is None.
|
833
925
|
requests.HTTPError: If the HTTP request to the API fails (e.g., due to invalid parameters or network issues).
|
834
|
-
|
926
|
+
|
835
927
|
Tags:
|
836
928
|
reorder, replace, playlist, tracks, management, api
|
837
929
|
"""
|
838
930
|
if playlist_id is None:
|
839
931
|
raise ValueError("Missing required parameter 'playlist_id'")
|
840
932
|
request_body = {
|
841
|
-
|
842
|
-
|
843
|
-
|
844
|
-
|
845
|
-
|
933
|
+
"uris": uris,
|
934
|
+
"range_start": range_start,
|
935
|
+
"insert_before": insert_before,
|
936
|
+
"range_length": range_length,
|
937
|
+
"snapshot_id": snapshot_id,
|
846
938
|
}
|
847
939
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
848
940
|
url = f"{self.base_url}/playlists/{playlist_id}/tracks"
|
849
|
-
query_params = {k: v for k, v in [(
|
941
|
+
query_params = {k: v for k, v in [("uris", uris)] if v is not None}
|
850
942
|
response = self._put(url, data=request_body, params=query_params)
|
851
943
|
response.raise_for_status()
|
852
944
|
return response.json()
|
@@ -854,22 +946,24 @@ class SpotifyApp(APIApplication):
|
|
854
946
|
def get_a_list_of_current_users_playlists(self, limit=None, offset=None) -> Any:
|
855
947
|
"""
|
856
948
|
Retrieves a list of the current user's playlists with optional pagination controls.
|
857
|
-
|
949
|
+
|
858
950
|
Args:
|
859
951
|
limit: int or None. The maximum number of playlists to return. If None, the default set by the API is used.
|
860
952
|
offset: int or None. The index of the first playlist to return. If None, the default set by the API is used.
|
861
|
-
|
953
|
+
|
862
954
|
Returns:
|
863
955
|
dict. A JSON response containing the playlists of the current user.
|
864
|
-
|
956
|
+
|
865
957
|
Raises:
|
866
958
|
requests.HTTPError: If the HTTP request to the API fails or returns a non-success status code.
|
867
|
-
|
959
|
+
|
868
960
|
Tags:
|
869
961
|
list, playlists, user, api
|
870
962
|
"""
|
871
963
|
url = f"{self.base_url}/me/playlists"
|
872
|
-
query_params = {
|
964
|
+
query_params = {
|
965
|
+
k: v for k, v in [("limit", limit), ("offset", offset)] if v is not None
|
966
|
+
}
|
873
967
|
response = self._get(url, params=query_params)
|
874
968
|
response.raise_for_status()
|
875
969
|
return response.json()
|
@@ -877,23 +971,27 @@ class SpotifyApp(APIApplication):
|
|
877
971
|
def get_users_saved_albums(self, limit=None, offset=None, market=None) -> Any:
|
878
972
|
"""
|
879
973
|
Retrieves the current user's saved albums from the Spotify library with optional pagination and market filtering.
|
880
|
-
|
974
|
+
|
881
975
|
Args:
|
882
976
|
limit: Optional; maximum number of albums to return. If not specified, the default set by the API is used.
|
883
977
|
offset: Optional; the index of the first album to return. Used for pagination.
|
884
978
|
market: Optional; an ISO 3166-1 alpha-2 country code to filter albums by market availability.
|
885
|
-
|
979
|
+
|
886
980
|
Returns:
|
887
981
|
A JSON object containing the list of the user's saved albums and related pagination details as returned by the Spotify API.
|
888
|
-
|
982
|
+
|
889
983
|
Raises:
|
890
984
|
requests.HTTPError: If the HTTP request to the Spotify API fails or returns an unsuccessful status code.
|
891
|
-
|
985
|
+
|
892
986
|
Tags:
|
893
987
|
get, list, albums, user-library, spotify, api
|
894
988
|
"""
|
895
989
|
url = f"{self.base_url}/me/albums"
|
896
|
-
query_params = {
|
990
|
+
query_params = {
|
991
|
+
k: v
|
992
|
+
for k, v in [("limit", limit), ("offset", offset), ("market", market)]
|
993
|
+
if v is not None
|
994
|
+
}
|
897
995
|
response = self._get(url, params=query_params)
|
898
996
|
response.raise_for_status()
|
899
997
|
return response.json()
|
@@ -901,24 +999,24 @@ class SpotifyApp(APIApplication):
|
|
901
999
|
def check_users_saved_albums(self, ids) -> Any:
|
902
1000
|
"""
|
903
1001
|
Checks if the specified albums are saved in the current user's Spotify library.
|
904
|
-
|
1002
|
+
|
905
1003
|
Args:
|
906
1004
|
ids: A comma-separated string or list of Spotify album IDs to check for saved status.
|
907
|
-
|
1005
|
+
|
908
1006
|
Returns:
|
909
1007
|
A list of boolean values indicating whether each album specified in 'ids' is saved in the user's library.
|
910
|
-
|
1008
|
+
|
911
1009
|
Raises:
|
912
1010
|
ValueError: If the 'ids' parameter is None.
|
913
1011
|
requests.HTTPError: If the HTTP request to the Spotify API fails.
|
914
|
-
|
1012
|
+
|
915
1013
|
Tags:
|
916
1014
|
check, spotify, albums, user-library
|
917
1015
|
"""
|
918
1016
|
if ids is None:
|
919
1017
|
raise ValueError("Missing required parameter 'ids'")
|
920
1018
|
url = f"{self.base_url}/me/albums/contains"
|
921
|
-
query_params = {k: v for k, v in [(
|
1019
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
922
1020
|
response = self._get(url, params=query_params)
|
923
1021
|
response.raise_for_status()
|
924
1022
|
return response.json()
|
@@ -926,23 +1024,27 @@ class SpotifyApp(APIApplication):
|
|
926
1024
|
def get_users_saved_tracks(self, market=None, limit=None, offset=None) -> Any:
|
927
1025
|
"""
|
928
1026
|
Retrieves the current user's saved tracks from the Spotify library with optional filtering and pagination.
|
929
|
-
|
1027
|
+
|
930
1028
|
Args:
|
931
1029
|
market: Optional; an ISO 3166-1 alpha-2 country code. Filters the results to tracks available in the specified market.
|
932
1030
|
limit: Optional; maximum number of items to return (usually between 1 and 50).
|
933
1031
|
offset: Optional; the index of the first item to return, used for pagination.
|
934
|
-
|
1032
|
+
|
935
1033
|
Returns:
|
936
1034
|
A JSON object containing a paginated list of the user's saved tracks and associated metadata.
|
937
|
-
|
1035
|
+
|
938
1036
|
Raises:
|
939
1037
|
requests.HTTPError: Raised if the HTTP request to the Spotify API fails or returns a non-success status code.
|
940
|
-
|
1038
|
+
|
941
1039
|
Tags:
|
942
1040
|
list, get, user-data, spotify, tracks, batch
|
943
1041
|
"""
|
944
1042
|
url = f"{self.base_url}/me/tracks"
|
945
|
-
query_params = {
|
1043
|
+
query_params = {
|
1044
|
+
k: v
|
1045
|
+
for k, v in [("market", market), ("limit", limit), ("offset", offset)]
|
1046
|
+
if v is not None
|
1047
|
+
}
|
946
1048
|
response = self._get(url, params=query_params)
|
947
1049
|
response.raise_for_status()
|
948
1050
|
return response.json()
|
@@ -950,28 +1052,28 @@ class SpotifyApp(APIApplication):
|
|
950
1052
|
def save_tracks_user(self, ids) -> Any:
|
951
1053
|
"""
|
952
1054
|
Saves one or more tracks to the current user's music library.
|
953
|
-
|
1055
|
+
|
954
1056
|
Args:
|
955
1057
|
ids: A list or comma-separated string of track IDs to save to the user's library. Must not be None.
|
956
|
-
|
1058
|
+
|
957
1059
|
Returns:
|
958
1060
|
The JSON response from the API as a Python object, typically confirming the successful saving of tracks.
|
959
|
-
|
1061
|
+
|
960
1062
|
Raises:
|
961
1063
|
ValueError: If the 'ids' parameter is None.
|
962
1064
|
HTTPError: If the HTTP request to save tracks fails (raised by response.raise_for_status()).
|
963
|
-
|
1065
|
+
|
964
1066
|
Tags:
|
965
1067
|
save, user-library, tracks, api
|
966
1068
|
"""
|
967
1069
|
if ids is None:
|
968
1070
|
raise ValueError("Missing required parameter 'ids'")
|
969
1071
|
request_body = {
|
970
|
-
|
1072
|
+
"ids": ids,
|
971
1073
|
}
|
972
1074
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
973
1075
|
url = f"{self.base_url}/me/tracks"
|
974
|
-
query_params = {k: v for k, v in [(
|
1076
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
975
1077
|
response = self._put(url, data=request_body, params=query_params)
|
976
1078
|
response.raise_for_status()
|
977
1079
|
return response.json()
|
@@ -979,24 +1081,24 @@ class SpotifyApp(APIApplication):
|
|
979
1081
|
def check_users_saved_tracks(self, ids) -> Any:
|
980
1082
|
"""
|
981
1083
|
Checks if the current user has saved specific tracks in their Spotify library.
|
982
|
-
|
1084
|
+
|
983
1085
|
Args:
|
984
1086
|
ids: A comma-separated string of Spotify track IDs to check for saved status.
|
985
|
-
|
1087
|
+
|
986
1088
|
Returns:
|
987
1089
|
A list of boolean values indicating whether each track ID is saved by the current user.
|
988
|
-
|
1090
|
+
|
989
1091
|
Raises:
|
990
1092
|
ValueError: Raised when the 'ids' parameter is None.
|
991
1093
|
HTTPError: Raised if the HTTP request to the Spotify API fails.
|
992
|
-
|
1094
|
+
|
993
1095
|
Tags:
|
994
1096
|
check, user-library, spotify, status
|
995
1097
|
"""
|
996
1098
|
if ids is None:
|
997
1099
|
raise ValueError("Missing required parameter 'ids'")
|
998
1100
|
url = f"{self.base_url}/me/tracks/contains"
|
999
|
-
query_params = {k: v for k, v in [(
|
1101
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
1000
1102
|
response = self._get(url, params=query_params)
|
1001
1103
|
response.raise_for_status()
|
1002
1104
|
return response.json()
|
@@ -1004,23 +1106,27 @@ class SpotifyApp(APIApplication):
|
|
1004
1106
|
def get_users_saved_episodes(self, market=None, limit=None, offset=None) -> Any:
|
1005
1107
|
"""
|
1006
1108
|
Retrieves the current user's saved podcast episodes from the service, with optional support for market, pagination, and result limits.
|
1007
|
-
|
1109
|
+
|
1008
1110
|
Args:
|
1009
1111
|
market: Optional; a string specifying the market (country code) to filter episode availability.
|
1010
1112
|
limit: Optional; an integer specifying the maximum number of episodes to return.
|
1011
1113
|
offset: Optional; an integer specifying the index of the first episode to return for pagination.
|
1012
|
-
|
1114
|
+
|
1013
1115
|
Returns:
|
1014
1116
|
A JSON-decoded response containing the user's saved episodes and associated metadata.
|
1015
|
-
|
1117
|
+
|
1016
1118
|
Raises:
|
1017
1119
|
requests.HTTPError: If the HTTP request fails or the API returns a non-success status code.
|
1018
|
-
|
1120
|
+
|
1019
1121
|
Tags:
|
1020
1122
|
get, list, user-content, episodes, ai
|
1021
1123
|
"""
|
1022
1124
|
url = f"{self.base_url}/me/episodes"
|
1023
|
-
query_params = {
|
1125
|
+
query_params = {
|
1126
|
+
k: v
|
1127
|
+
for k, v in [("market", market), ("limit", limit), ("offset", offset)]
|
1128
|
+
if v is not None
|
1129
|
+
}
|
1024
1130
|
response = self._get(url, params=query_params)
|
1025
1131
|
response.raise_for_status()
|
1026
1132
|
return response.json()
|
@@ -1028,28 +1134,28 @@ class SpotifyApp(APIApplication):
|
|
1028
1134
|
def save_episodes_user(self, ids) -> Any:
|
1029
1135
|
"""
|
1030
1136
|
Saves episodes to the user's library using the provided list of episode IDs.
|
1031
|
-
|
1137
|
+
|
1032
1138
|
Args:
|
1033
1139
|
ids: A list of episode IDs to be saved to the user's library.
|
1034
|
-
|
1140
|
+
|
1035
1141
|
Returns:
|
1036
1142
|
The JSON response from the server confirming successful saving of episodes.
|
1037
|
-
|
1143
|
+
|
1038
1144
|
Raises:
|
1039
1145
|
ValueError: Raised if the 'ids' parameter is None.
|
1040
1146
|
HTTPError: Raised if the HTTP PUT request to the server fails.
|
1041
|
-
|
1147
|
+
|
1042
1148
|
Tags:
|
1043
1149
|
save, episodes, user-management, async-job
|
1044
1150
|
"""
|
1045
1151
|
if ids is None:
|
1046
1152
|
raise ValueError("Missing required parameter 'ids'")
|
1047
1153
|
request_body = {
|
1048
|
-
|
1154
|
+
"ids": ids,
|
1049
1155
|
}
|
1050
1156
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
1051
1157
|
url = f"{self.base_url}/me/episodes"
|
1052
|
-
query_params = {k: v for k, v in [(
|
1158
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
1053
1159
|
response = self._put(url, data=request_body, params=query_params)
|
1054
1160
|
response.raise_for_status()
|
1055
1161
|
return response.json()
|
@@ -1057,24 +1163,24 @@ class SpotifyApp(APIApplication):
|
|
1057
1163
|
def check_users_saved_episodes(self, ids) -> Any:
|
1058
1164
|
"""
|
1059
1165
|
Checks if the specified episodes are saved in the current user's library.
|
1060
|
-
|
1166
|
+
|
1061
1167
|
Args:
|
1062
1168
|
ids: A list or comma-separated string of episode IDs to check for presence in the user's saved episodes. Must not be None.
|
1063
|
-
|
1169
|
+
|
1064
1170
|
Returns:
|
1065
1171
|
A JSON-compatible object (typically a list of booleans) indicating whether each episode ID is present in the user's saved episodes.
|
1066
|
-
|
1172
|
+
|
1067
1173
|
Raises:
|
1068
1174
|
ValueError: Raised if the 'ids' parameter is None.
|
1069
1175
|
HTTPError: Raised if the HTTP request to the remote service fails with a non-success status code.
|
1070
|
-
|
1176
|
+
|
1071
1177
|
Tags:
|
1072
1178
|
check, status, async_job, ai, management
|
1073
1179
|
"""
|
1074
1180
|
if ids is None:
|
1075
1181
|
raise ValueError("Missing required parameter 'ids'")
|
1076
1182
|
url = f"{self.base_url}/me/episodes/contains"
|
1077
|
-
query_params = {k: v for k, v in [(
|
1183
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
1078
1184
|
response = self._get(url, params=query_params)
|
1079
1185
|
response.raise_for_status()
|
1080
1186
|
return response.json()
|
@@ -1082,22 +1188,24 @@ class SpotifyApp(APIApplication):
|
|
1082
1188
|
def get_users_saved_shows(self, limit=None, offset=None) -> Any:
|
1083
1189
|
"""
|
1084
1190
|
Retrieves the current user's saved shows from the Spotify API with optional pagination.
|
1085
|
-
|
1191
|
+
|
1086
1192
|
Args:
|
1087
1193
|
limit: Optional; maximum number of shows to return. Must be a positive integer or None for default behavior.
|
1088
1194
|
offset: Optional; the index of the first show to return. Must be a non-negative integer or None for default behavior.
|
1089
|
-
|
1195
|
+
|
1090
1196
|
Returns:
|
1091
1197
|
A JSON-decoded object containing the list of saved shows and associated metadata.
|
1092
|
-
|
1198
|
+
|
1093
1199
|
Raises:
|
1094
1200
|
HTTPError: Raised if the HTTP request to the Spotify API returns an unsuccessful status code.
|
1095
|
-
|
1201
|
+
|
1096
1202
|
Tags:
|
1097
1203
|
get, list, shows, spotify, user-content
|
1098
1204
|
"""
|
1099
1205
|
url = f"{self.base_url}/me/shows"
|
1100
|
-
query_params = {
|
1206
|
+
query_params = {
|
1207
|
+
k: v for k, v in [("limit", limit), ("offset", offset)] if v is not None
|
1208
|
+
}
|
1101
1209
|
response = self._get(url, params=query_params)
|
1102
1210
|
response.raise_for_status()
|
1103
1211
|
return response.json()
|
@@ -1105,24 +1213,24 @@ class SpotifyApp(APIApplication):
|
|
1105
1213
|
def check_users_saved_shows(self, ids) -> Any:
|
1106
1214
|
"""
|
1107
1215
|
Checks if the specified shows are saved in the current user's library.
|
1108
|
-
|
1216
|
+
|
1109
1217
|
Args:
|
1110
1218
|
ids: A comma-separated string or list of show IDs to check for presence in the user's library.
|
1111
|
-
|
1219
|
+
|
1112
1220
|
Returns:
|
1113
1221
|
A JSON-compatible object (typically a list of booleans) indicating, for each show ID, whether it is saved in the user's library.
|
1114
|
-
|
1222
|
+
|
1115
1223
|
Raises:
|
1116
1224
|
ValueError: If the required 'ids' parameter is not provided.
|
1117
1225
|
requests.HTTPError: If the HTTP request to the API fails or returns an error status code.
|
1118
|
-
|
1226
|
+
|
1119
1227
|
Tags:
|
1120
1228
|
check, library, status, async-job, ai
|
1121
1229
|
"""
|
1122
1230
|
if ids is None:
|
1123
1231
|
raise ValueError("Missing required parameter 'ids'")
|
1124
1232
|
url = f"{self.base_url}/me/shows/contains"
|
1125
|
-
query_params = {k: v for k, v in [(
|
1233
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
1126
1234
|
response = self._get(url, params=query_params)
|
1127
1235
|
response.raise_for_status()
|
1128
1236
|
return response.json()
|
@@ -1130,17 +1238,17 @@ class SpotifyApp(APIApplication):
|
|
1130
1238
|
def get_users_profile(self, user_id) -> Any:
|
1131
1239
|
"""
|
1132
1240
|
Retrieves the profile information for a specific user by user ID.
|
1133
|
-
|
1241
|
+
|
1134
1242
|
Args:
|
1135
1243
|
user_id: The unique identifier of the user whose profile information is to be retrieved.
|
1136
|
-
|
1244
|
+
|
1137
1245
|
Returns:
|
1138
1246
|
A JSON-decoded object containing the user's profile information.
|
1139
|
-
|
1247
|
+
|
1140
1248
|
Raises:
|
1141
1249
|
ValueError: Raised if the 'user_id' parameter is not provided (i.e., is None).
|
1142
1250
|
requests.exceptions.HTTPError: Raised if the HTTP request to fetch the user's profile fails (non-success status code).
|
1143
|
-
|
1251
|
+
|
1144
1252
|
Tags:
|
1145
1253
|
get, profile, user, api
|
1146
1254
|
"""
|
@@ -1155,48 +1263,52 @@ class SpotifyApp(APIApplication):
|
|
1155
1263
|
def get_list_users_playlists(self, user_id, limit=None, offset=None) -> Any:
|
1156
1264
|
"""
|
1157
1265
|
Retrieves a list of playlists for a specified user.
|
1158
|
-
|
1266
|
+
|
1159
1267
|
Args:
|
1160
1268
|
user_id: The ID of the user whose playlists to retrieve. Required.
|
1161
1269
|
limit: The maximum number of playlists to return. Optional.
|
1162
1270
|
offset: The index of the first playlist to return. Used for pagination. Optional.
|
1163
|
-
|
1271
|
+
|
1164
1272
|
Returns:
|
1165
1273
|
A JSON object containing the user's playlists data.
|
1166
|
-
|
1274
|
+
|
1167
1275
|
Raises:
|
1168
1276
|
ValueError: Raised when the required parameter 'user_id' is None.
|
1169
1277
|
HTTPError: Raised when the HTTP request fails.
|
1170
|
-
|
1278
|
+
|
1171
1279
|
Tags:
|
1172
1280
|
retrieve, list, playlists, user, pagination, api
|
1173
1281
|
"""
|
1174
1282
|
if user_id is None:
|
1175
1283
|
raise ValueError("Missing required parameter 'user_id'")
|
1176
1284
|
url = f"{self.base_url}/users/{user_id}/playlists"
|
1177
|
-
query_params = {
|
1285
|
+
query_params = {
|
1286
|
+
k: v for k, v in [("limit", limit), ("offset", offset)] if v is not None
|
1287
|
+
}
|
1178
1288
|
response = self._get(url, params=query_params)
|
1179
1289
|
response.raise_for_status()
|
1180
1290
|
return response.json()
|
1181
1291
|
|
1182
|
-
def create_playlist(
|
1292
|
+
def create_playlist(
|
1293
|
+
self, user_id, name, public=None, collaborative=None, description=None
|
1294
|
+
) -> Any:
|
1183
1295
|
"""
|
1184
1296
|
Creates a new playlist for a specified user with optional visibility, collaboration, and description settings.
|
1185
|
-
|
1297
|
+
|
1186
1298
|
Args:
|
1187
1299
|
user_id: str. The unique identifier of the user for whom the playlist is to be created.
|
1188
1300
|
name: str. The name of the new playlist.
|
1189
1301
|
public: Optional[bool]. If True, the playlist is public; if False, it is private. If None, the default visibility is used.
|
1190
1302
|
collaborative: Optional[bool]. If True, the playlist can be edited by other users. If None, the playlist is not collaborative.
|
1191
1303
|
description: Optional[str]. An optional description for the playlist.
|
1192
|
-
|
1304
|
+
|
1193
1305
|
Returns:
|
1194
1306
|
dict. A dictionary containing the created playlist's details as returned by the API.
|
1195
|
-
|
1307
|
+
|
1196
1308
|
Raises:
|
1197
1309
|
ValueError: If either 'user_id' or 'name' is not provided.
|
1198
1310
|
requests.HTTPError: If the HTTP request to create the playlist fails.
|
1199
|
-
|
1311
|
+
|
1200
1312
|
Tags:
|
1201
1313
|
create, playlist, api, management, important
|
1202
1314
|
"""
|
@@ -1205,10 +1317,10 @@ class SpotifyApp(APIApplication):
|
|
1205
1317
|
if name is None:
|
1206
1318
|
raise ValueError("Missing required parameter 'name'")
|
1207
1319
|
request_body = {
|
1208
|
-
|
1209
|
-
|
1210
|
-
|
1211
|
-
|
1320
|
+
"name": name,
|
1321
|
+
"public": public,
|
1322
|
+
"collaborative": collaborative,
|
1323
|
+
"description": description,
|
1212
1324
|
}
|
1213
1325
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
1214
1326
|
url = f"{self.base_url}/users/{user_id}/playlists"
|
@@ -1220,25 +1332,25 @@ class SpotifyApp(APIApplication):
|
|
1220
1332
|
def follow_playlist(self, playlist_id, public=None) -> Any:
|
1221
1333
|
"""
|
1222
1334
|
Follows a Spotify playlist on behalf of the current user.
|
1223
|
-
|
1335
|
+
|
1224
1336
|
Args:
|
1225
1337
|
playlist_id: str. The Spotify ID of the playlist to follow. Must not be None.
|
1226
1338
|
public: Optional[bool]. Whether the playlist should be public (visible on the user's profile). If None, defaults to the server-side default.
|
1227
|
-
|
1339
|
+
|
1228
1340
|
Returns:
|
1229
1341
|
Any. The JSON response from the Spotify API confirming the follow action.
|
1230
|
-
|
1342
|
+
|
1231
1343
|
Raises:
|
1232
1344
|
ValueError: If 'playlist_id' is None.
|
1233
1345
|
HTTPError: If the HTTP request fails or the API returns an error status.
|
1234
|
-
|
1346
|
+
|
1235
1347
|
Tags:
|
1236
1348
|
follow, playlist, api, async-job
|
1237
1349
|
"""
|
1238
1350
|
if playlist_id is None:
|
1239
1351
|
raise ValueError("Missing required parameter 'playlist_id'")
|
1240
1352
|
request_body = {
|
1241
|
-
|
1353
|
+
"public": public,
|
1242
1354
|
}
|
1243
1355
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
1244
1356
|
url = f"{self.base_url}/playlists/{playlist_id}/followers"
|
@@ -1250,17 +1362,17 @@ class SpotifyApp(APIApplication):
|
|
1250
1362
|
def unfollow_playlist(self, playlist_id) -> Any:
|
1251
1363
|
"""
|
1252
1364
|
Unfollows the specified playlist by deleting the current user's following relationship.
|
1253
|
-
|
1365
|
+
|
1254
1366
|
Args:
|
1255
1367
|
playlist_id: The unique identifier of the playlist to unfollow. Must not be None.
|
1256
|
-
|
1368
|
+
|
1257
1369
|
Returns:
|
1258
1370
|
The API response as a JSON-compatible object containing details of the unfollow operation.
|
1259
|
-
|
1371
|
+
|
1260
1372
|
Raises:
|
1261
1373
|
ValueError: If 'playlist_id' is None.
|
1262
1374
|
requests.HTTPError: If the API request fails and returns an unsuccessful HTTP status code.
|
1263
|
-
|
1375
|
+
|
1264
1376
|
Tags:
|
1265
1377
|
unfollow, playlist-management, delete, async-job
|
1266
1378
|
"""
|
@@ -1275,23 +1387,27 @@ class SpotifyApp(APIApplication):
|
|
1275
1387
|
def get_featured_playlists(self, locale=None, limit=None, offset=None) -> Any:
|
1276
1388
|
"""
|
1277
1389
|
Retrieves a list of Spotify's featured playlists with optional localization, result limiting, and pagination.
|
1278
|
-
|
1390
|
+
|
1279
1391
|
Args:
|
1280
1392
|
locale: Optional; a string specifying the language and country (e.g., 'en_US') to localize the playlist names and descriptions. If None, the server default is used.
|
1281
1393
|
limit: Optional; an integer specifying the maximum number of playlists to return. If None, the server default is used.
|
1282
1394
|
offset: Optional; an integer specifying the index of the first playlist to return (for pagination). If None, the server default is used.
|
1283
|
-
|
1395
|
+
|
1284
1396
|
Returns:
|
1285
1397
|
A dictionary containing the JSON response from the Spotify Web API with details about the featured playlists.
|
1286
|
-
|
1398
|
+
|
1287
1399
|
Raises:
|
1288
1400
|
requests.HTTPError: If the HTTP request to the Spotify API fails or returns an unsuccessful status code.
|
1289
|
-
|
1401
|
+
|
1290
1402
|
Tags:
|
1291
1403
|
get, list, playlists, featured, api, music
|
1292
1404
|
"""
|
1293
1405
|
url = f"{self.base_url}/browse/featured-playlists"
|
1294
|
-
query_params = {
|
1406
|
+
query_params = {
|
1407
|
+
k: v
|
1408
|
+
for k, v in [("locale", locale), ("limit", limit), ("offset", offset)]
|
1409
|
+
if v is not None
|
1410
|
+
}
|
1295
1411
|
response = self._get(url, params=query_params)
|
1296
1412
|
response.raise_for_status()
|
1297
1413
|
return response.json()
|
@@ -1299,23 +1415,27 @@ class SpotifyApp(APIApplication):
|
|
1299
1415
|
def get_categories(self, locale=None, limit=None, offset=None) -> Any:
|
1300
1416
|
"""
|
1301
1417
|
Retrieves a list of category objects from the API with optional locale, limit, and offset filters.
|
1302
|
-
|
1418
|
+
|
1303
1419
|
Args:
|
1304
1420
|
locale: Optional; str. Locale identifier (e.g., 'en_US') to localize the category names returned.
|
1305
1421
|
limit: Optional; int. Maximum number of categories to return in the response.
|
1306
1422
|
offset: Optional; int. The index of the first category to return, used for pagination.
|
1307
|
-
|
1423
|
+
|
1308
1424
|
Returns:
|
1309
1425
|
dict. The JSON response from the API containing category data.
|
1310
|
-
|
1426
|
+
|
1311
1427
|
Raises:
|
1312
1428
|
requests.HTTPError: If the HTTP request to the API endpoint returns an unsuccessful status code.
|
1313
|
-
|
1429
|
+
|
1314
1430
|
Tags:
|
1315
1431
|
get, list, categories, api
|
1316
1432
|
"""
|
1317
1433
|
url = f"{self.base_url}/browse/categories"
|
1318
|
-
query_params = {
|
1434
|
+
query_params = {
|
1435
|
+
k: v
|
1436
|
+
for k, v in [("locale", locale), ("limit", limit), ("offset", offset)]
|
1437
|
+
if v is not None
|
1438
|
+
}
|
1319
1439
|
response = self._get(url, params=query_params)
|
1320
1440
|
response.raise_for_status()
|
1321
1441
|
return response.json()
|
@@ -1323,25 +1443,25 @@ class SpotifyApp(APIApplication):
|
|
1323
1443
|
def get_a_category(self, category_id, locale=None) -> Any:
|
1324
1444
|
"""
|
1325
1445
|
Retrieve detailed information about a specific category by its ID, optionally localized to a given locale.
|
1326
|
-
|
1446
|
+
|
1327
1447
|
Args:
|
1328
1448
|
category_id: str. The unique identifier of the category to retrieve.
|
1329
1449
|
locale: Optional[str]. The locale code to use for localization of the category information. If None, the default locale is used.
|
1330
|
-
|
1450
|
+
|
1331
1451
|
Returns:
|
1332
1452
|
dict. A JSON object containing the category details as returned by the API.
|
1333
|
-
|
1453
|
+
|
1334
1454
|
Raises:
|
1335
1455
|
ValueError: If 'category_id' is None.
|
1336
1456
|
requests.HTTPError: If the HTTP request to the API fails or returns an unsuccessful status code.
|
1337
|
-
|
1457
|
+
|
1338
1458
|
Tags:
|
1339
1459
|
get, category, api
|
1340
1460
|
"""
|
1341
1461
|
if category_id is None:
|
1342
1462
|
raise ValueError("Missing required parameter 'category_id'")
|
1343
1463
|
url = f"{self.base_url}/browse/categories/{category_id}"
|
1344
|
-
query_params = {k: v for k, v in [(
|
1464
|
+
query_params = {k: v for k, v in [("locale", locale)] if v is not None}
|
1345
1465
|
response = self._get(url, params=query_params)
|
1346
1466
|
response.raise_for_status()
|
1347
1467
|
return response.json()
|
@@ -1349,26 +1469,28 @@ class SpotifyApp(APIApplication):
|
|
1349
1469
|
def get_a_categories_playlists(self, category_id, limit=None, offset=None) -> Any:
|
1350
1470
|
"""
|
1351
1471
|
Retrieves playlists associated with a specified category from the API.
|
1352
|
-
|
1472
|
+
|
1353
1473
|
Args:
|
1354
1474
|
category_id: str. The unique identifier for the category whose playlists are to be fetched.
|
1355
1475
|
limit: Optional[int]. The maximum number of playlists to return. If None, the default API value is used.
|
1356
1476
|
offset: Optional[int]. The index of the first playlist to return. Used for pagination. If None, the default API value is used.
|
1357
|
-
|
1477
|
+
|
1358
1478
|
Returns:
|
1359
1479
|
dict. The JSON response containing playlist data for the specified category.
|
1360
|
-
|
1480
|
+
|
1361
1481
|
Raises:
|
1362
1482
|
ValueError: If 'category_id' is None.
|
1363
1483
|
requests.HTTPError: If the API request fails or returns a non-success status code.
|
1364
|
-
|
1484
|
+
|
1365
1485
|
Tags:
|
1366
1486
|
get, list, playlists, categories, api, management
|
1367
1487
|
"""
|
1368
1488
|
if category_id is None:
|
1369
1489
|
raise ValueError("Missing required parameter 'category_id'")
|
1370
1490
|
url = f"{self.base_url}/browse/categories/{category_id}/playlists"
|
1371
|
-
query_params = {
|
1491
|
+
query_params = {
|
1492
|
+
k: v for k, v in [("limit", limit), ("offset", offset)] if v is not None
|
1493
|
+
}
|
1372
1494
|
response = self._get(url, params=query_params)
|
1373
1495
|
response.raise_for_status()
|
1374
1496
|
return response.json()
|
@@ -1376,17 +1498,17 @@ class SpotifyApp(APIApplication):
|
|
1376
1498
|
def get_playlist_cover(self, playlist_id) -> Any:
|
1377
1499
|
"""
|
1378
1500
|
Retrieves the cover image(s) for a specified playlist by its unique ID.
|
1379
|
-
|
1501
|
+
|
1380
1502
|
Args:
|
1381
1503
|
playlist_id: The unique identifier of the playlist for which to fetch cover images.
|
1382
|
-
|
1504
|
+
|
1383
1505
|
Returns:
|
1384
1506
|
The JSON response containing playlist cover image metadata as returned by the API.
|
1385
|
-
|
1507
|
+
|
1386
1508
|
Raises:
|
1387
1509
|
ValueError: Raised when the required parameter 'playlist_id' is None.
|
1388
1510
|
HTTPError: Raised if the HTTP request to retrieve the cover images fails.
|
1389
|
-
|
1511
|
+
|
1390
1512
|
Tags:
|
1391
1513
|
get, playlist, cover-image, api
|
1392
1514
|
"""
|
@@ -1401,22 +1523,24 @@ class SpotifyApp(APIApplication):
|
|
1401
1523
|
def get_new_releases(self, limit=None, offset=None) -> Any:
|
1402
1524
|
"""
|
1403
1525
|
Retrieves a list of new music releases with optional pagination parameters.
|
1404
|
-
|
1526
|
+
|
1405
1527
|
Args:
|
1406
1528
|
limit: Optional; int. The maximum number of items to return. If not specified, the server default is used.
|
1407
1529
|
offset: Optional; int. The index of the first item to return. Used for pagination. If not specified, the server default is used.
|
1408
|
-
|
1530
|
+
|
1409
1531
|
Returns:
|
1410
1532
|
dict. A JSON object containing metadata and a list of new releases.
|
1411
|
-
|
1533
|
+
|
1412
1534
|
Raises:
|
1413
1535
|
requests.HTTPError: If the HTTP request to fetch new releases returns an unsuccessful status code.
|
1414
|
-
|
1536
|
+
|
1415
1537
|
Tags:
|
1416
1538
|
get, list, browse, music, async-job, api
|
1417
1539
|
"""
|
1418
1540
|
url = f"{self.base_url}/browse/new-releases"
|
1419
|
-
query_params = {
|
1541
|
+
query_params = {
|
1542
|
+
k: v for k, v in [("limit", limit), ("offset", offset)] if v is not None
|
1543
|
+
}
|
1420
1544
|
response = self._get(url, params=query_params)
|
1421
1545
|
response.raise_for_status()
|
1422
1546
|
return response.json()
|
@@ -1424,26 +1548,30 @@ class SpotifyApp(APIApplication):
|
|
1424
1548
|
def get_followed(self, type, after=None, limit=None) -> Any:
|
1425
1549
|
"""
|
1426
1550
|
Retrieves the list of entities the current user is following, with support for pagination and limiting results.
|
1427
|
-
|
1551
|
+
|
1428
1552
|
Args:
|
1429
1553
|
type: str. The type of entity to return (e.g., 'artist', 'user'). Required.
|
1430
1554
|
after: str or None. The cursor value to fetch items after a specific entity for pagination. Optional.
|
1431
1555
|
limit: int or None. The maximum number of items to return. Optional.
|
1432
|
-
|
1556
|
+
|
1433
1557
|
Returns:
|
1434
1558
|
dict. A JSON-decoded response containing the list of followed entities and pagination details.
|
1435
|
-
|
1559
|
+
|
1436
1560
|
Raises:
|
1437
1561
|
ValueError: If the 'type' parameter is not provided.
|
1438
1562
|
HTTPError: If the HTTP request to the API fails (raised by requests.Response.raise_for_status()).
|
1439
|
-
|
1563
|
+
|
1440
1564
|
Tags:
|
1441
1565
|
get, list, follow-management, api
|
1442
1566
|
"""
|
1443
1567
|
if type is None:
|
1444
1568
|
raise ValueError("Missing required parameter 'type'")
|
1445
1569
|
url = f"{self.base_url}/me/following"
|
1446
|
-
query_params = {
|
1570
|
+
query_params = {
|
1571
|
+
k: v
|
1572
|
+
for k, v in [("type", type), ("after", after), ("limit", limit)]
|
1573
|
+
if v is not None
|
1574
|
+
}
|
1447
1575
|
response = self._get(url, params=query_params)
|
1448
1576
|
response.raise_for_status()
|
1449
1577
|
return response.json()
|
@@ -1451,18 +1579,18 @@ class SpotifyApp(APIApplication):
|
|
1451
1579
|
def follow_artists_users(self, type, ids) -> Any:
|
1452
1580
|
"""
|
1453
1581
|
Follows one or more artists or users on behalf of the current user.
|
1454
|
-
|
1582
|
+
|
1455
1583
|
Args:
|
1456
1584
|
type: str. The type of entity to follow. Valid values are typically 'artist' or 'user'.
|
1457
1585
|
ids: str or list of str. The Spotify IDs of the artists or users to follow. Can be a single ID or a comma-separated/list of IDs.
|
1458
|
-
|
1586
|
+
|
1459
1587
|
Returns:
|
1460
1588
|
dict. The response from the API as a parsed JSON object containing the result of the follow operation.
|
1461
|
-
|
1589
|
+
|
1462
1590
|
Raises:
|
1463
1591
|
ValueError: If 'type' or 'ids' is None, indicating a missing required parameter.
|
1464
1592
|
HTTPError: If the API request fails or returns an error status code.
|
1465
|
-
|
1593
|
+
|
1466
1594
|
Tags:
|
1467
1595
|
follow, users, artists, api
|
1468
1596
|
"""
|
@@ -1471,11 +1599,13 @@ class SpotifyApp(APIApplication):
|
|
1471
1599
|
if ids is None:
|
1472
1600
|
raise ValueError("Missing required parameter 'ids'")
|
1473
1601
|
request_body = {
|
1474
|
-
|
1602
|
+
"ids": ids,
|
1475
1603
|
}
|
1476
1604
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
1477
1605
|
url = f"{self.base_url}/me/following"
|
1478
|
-
query_params = {
|
1606
|
+
query_params = {
|
1607
|
+
k: v for k, v in [("type", type), ("ids", ids)] if v is not None
|
1608
|
+
}
|
1479
1609
|
response = self._put(url, data=request_body, params=query_params)
|
1480
1610
|
response.raise_for_status()
|
1481
1611
|
return response.json()
|
@@ -1483,18 +1613,18 @@ class SpotifyApp(APIApplication):
|
|
1483
1613
|
def check_current_user_follows(self, type, ids) -> Any:
|
1484
1614
|
"""
|
1485
1615
|
Check if the current user follows specific Spotify users or artists.
|
1486
|
-
|
1616
|
+
|
1487
1617
|
Args:
|
1488
1618
|
type: str. The type of entity to check, either 'artist' or 'user'.
|
1489
1619
|
ids: str or list of str. The Spotify IDs of the users or artists to check, separated by commas if a string.
|
1490
|
-
|
1620
|
+
|
1491
1621
|
Returns:
|
1492
1622
|
list of bool. A list indicating, for each provided ID, whether the current user is following the corresponding user or artist.
|
1493
|
-
|
1623
|
+
|
1494
1624
|
Raises:
|
1495
1625
|
ValueError: If the 'type' or 'ids' parameter is missing or None.
|
1496
1626
|
requests.HTTPError: If the HTTP request to the API fails or returns an error status.
|
1497
|
-
|
1627
|
+
|
1498
1628
|
Tags:
|
1499
1629
|
check, follows, spotify, user, artist, api
|
1500
1630
|
"""
|
@@ -1503,7 +1633,9 @@ class SpotifyApp(APIApplication):
|
|
1503
1633
|
if ids is None:
|
1504
1634
|
raise ValueError("Missing required parameter 'ids'")
|
1505
1635
|
url = f"{self.base_url}/me/following/contains"
|
1506
|
-
query_params = {
|
1636
|
+
query_params = {
|
1637
|
+
k: v for k, v in [("type", type), ("ids", ids)] if v is not None
|
1638
|
+
}
|
1507
1639
|
response = self._get(url, params=query_params)
|
1508
1640
|
response.raise_for_status()
|
1509
1641
|
return response.json()
|
@@ -1511,18 +1643,18 @@ class SpotifyApp(APIApplication):
|
|
1511
1643
|
def check_if_user_follows_playlist(self, playlist_id, ids) -> Any:
|
1512
1644
|
"""
|
1513
1645
|
Checks if one or more users follow a specified playlist.
|
1514
|
-
|
1646
|
+
|
1515
1647
|
Args:
|
1516
1648
|
playlist_id: The unique identifier of the playlist to check.
|
1517
1649
|
ids: A comma-separated list or iterable of user IDs to be checked for following the playlist.
|
1518
|
-
|
1650
|
+
|
1519
1651
|
Returns:
|
1520
1652
|
A JSON-compatible object indicating, for each user ID, whether that user is following the playlist.
|
1521
|
-
|
1653
|
+
|
1522
1654
|
Raises:
|
1523
1655
|
ValueError: If 'playlist_id' or 'ids' is None.
|
1524
1656
|
requests.HTTPError: If the API request fails or returns an error response.
|
1525
|
-
|
1657
|
+
|
1526
1658
|
Tags:
|
1527
1659
|
check, playlist, followers, api
|
1528
1660
|
"""
|
@@ -1531,7 +1663,7 @@ class SpotifyApp(APIApplication):
|
|
1531
1663
|
if ids is None:
|
1532
1664
|
raise ValueError("Missing required parameter 'ids'")
|
1533
1665
|
url = f"{self.base_url}/playlists/{playlist_id}/followers/contains"
|
1534
|
-
query_params = {k: v for k, v in [(
|
1666
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
1535
1667
|
response = self._get(url, params=query_params)
|
1536
1668
|
response.raise_for_status()
|
1537
1669
|
return response.json()
|
@@ -1539,24 +1671,24 @@ class SpotifyApp(APIApplication):
|
|
1539
1671
|
def get_several_audio_features(self, ids) -> Any:
|
1540
1672
|
"""
|
1541
1673
|
Retrieves audio feature information for multiple tracks using their IDs.
|
1542
|
-
|
1674
|
+
|
1543
1675
|
Args:
|
1544
1676
|
ids: A comma-separated string or list of track IDs for which to retrieve audio features.
|
1545
|
-
|
1677
|
+
|
1546
1678
|
Returns:
|
1547
1679
|
A JSON-decoded object containing audio features for the specified tracks.
|
1548
|
-
|
1680
|
+
|
1549
1681
|
Raises:
|
1550
1682
|
ValueError: If the 'ids' parameter is None.
|
1551
1683
|
requests.HTTPError: If the HTTP request to the audio features endpoint fails.
|
1552
|
-
|
1684
|
+
|
1553
1685
|
Tags:
|
1554
1686
|
get, audio-features, batch, ai
|
1555
1687
|
"""
|
1556
1688
|
if ids is None:
|
1557
1689
|
raise ValueError("Missing required parameter 'ids'")
|
1558
1690
|
url = f"{self.base_url}/audio-features"
|
1559
|
-
query_params = {k: v for k, v in [(
|
1691
|
+
query_params = {k: v for k, v in [("ids", ids)] if v is not None}
|
1560
1692
|
response = self._get(url, params=query_params)
|
1561
1693
|
response.raise_for_status()
|
1562
1694
|
return response.json()
|
@@ -1564,17 +1696,17 @@ class SpotifyApp(APIApplication):
|
|
1564
1696
|
def get_audio_features(self, id) -> Any:
|
1565
1697
|
"""
|
1566
1698
|
Retrieves audio feature information for a given identifier from the API.
|
1567
|
-
|
1699
|
+
|
1568
1700
|
Args:
|
1569
1701
|
id: The identifier of the audio resource for which to fetch features.
|
1570
|
-
|
1702
|
+
|
1571
1703
|
Returns:
|
1572
1704
|
A dictionary containing the audio feature data for the specified resource.
|
1573
|
-
|
1705
|
+
|
1574
1706
|
Raises:
|
1575
1707
|
ValueError: Raised if the 'id' parameter is None.
|
1576
1708
|
requests.HTTPError: Raised if the HTTP request to the API fails with a bad status code.
|
1577
|
-
|
1709
|
+
|
1578
1710
|
Tags:
|
1579
1711
|
get, audio-features, api, fetch
|
1580
1712
|
"""
|
@@ -1589,17 +1721,17 @@ class SpotifyApp(APIApplication):
|
|
1589
1721
|
def get_audio_analysis(self, id) -> Any:
|
1590
1722
|
"""
|
1591
1723
|
Retrieves the audio analysis data for a specified audio ID from the API.
|
1592
|
-
|
1724
|
+
|
1593
1725
|
Args:
|
1594
1726
|
id: The unique identifier of the audio resource to analyze. Must not be None.
|
1595
|
-
|
1727
|
+
|
1596
1728
|
Returns:
|
1597
1729
|
A JSON object containing audio analysis data for the specified audio ID.
|
1598
|
-
|
1730
|
+
|
1599
1731
|
Raises:
|
1600
1732
|
ValueError: If the 'id' parameter is None.
|
1601
1733
|
requests.HTTPError: If the HTTP request to the audio analysis endpoint fails (e.g., network error or non-2xx response).
|
1602
|
-
|
1734
|
+
|
1603
1735
|
Tags:
|
1604
1736
|
get, audio-analysis, api, fetch
|
1605
1737
|
"""
|
@@ -1611,10 +1743,59 @@ class SpotifyApp(APIApplication):
|
|
1611
1743
|
response.raise_for_status()
|
1612
1744
|
return response.json()
|
1613
1745
|
|
1614
|
-
def get_recommendations(
|
1746
|
+
def get_recommendations(
|
1747
|
+
self,
|
1748
|
+
limit=None,
|
1749
|
+
market=None,
|
1750
|
+
seed_artists=None,
|
1751
|
+
seed_genres=None,
|
1752
|
+
seed_tracks=None,
|
1753
|
+
min_acousticness=None,
|
1754
|
+
max_acousticness=None,
|
1755
|
+
target_acousticness=None,
|
1756
|
+
min_danceability=None,
|
1757
|
+
max_danceability=None,
|
1758
|
+
target_danceability=None,
|
1759
|
+
min_duration_ms=None,
|
1760
|
+
max_duration_ms=None,
|
1761
|
+
target_duration_ms=None,
|
1762
|
+
min_energy=None,
|
1763
|
+
max_energy=None,
|
1764
|
+
target_energy=None,
|
1765
|
+
min_instrumentalness=None,
|
1766
|
+
max_instrumentalness=None,
|
1767
|
+
target_instrumentalness=None,
|
1768
|
+
min_key=None,
|
1769
|
+
max_key=None,
|
1770
|
+
target_key=None,
|
1771
|
+
min_liveness=None,
|
1772
|
+
max_liveness=None,
|
1773
|
+
target_liveness=None,
|
1774
|
+
min_loudness=None,
|
1775
|
+
max_loudness=None,
|
1776
|
+
target_loudness=None,
|
1777
|
+
min_mode=None,
|
1778
|
+
max_mode=None,
|
1779
|
+
target_mode=None,
|
1780
|
+
min_popularity=None,
|
1781
|
+
max_popularity=None,
|
1782
|
+
target_popularity=None,
|
1783
|
+
min_speechiness=None,
|
1784
|
+
max_speechiness=None,
|
1785
|
+
target_speechiness=None,
|
1786
|
+
min_tempo=None,
|
1787
|
+
max_tempo=None,
|
1788
|
+
target_tempo=None,
|
1789
|
+
min_time_signature=None,
|
1790
|
+
max_time_signature=None,
|
1791
|
+
target_time_signature=None,
|
1792
|
+
min_valence=None,
|
1793
|
+
max_valence=None,
|
1794
|
+
target_valence=None,
|
1795
|
+
) -> Any:
|
1615
1796
|
"""
|
1616
1797
|
Retrieves track recommendations based on a combination of seed values and audio feature constraints.
|
1617
|
-
|
1798
|
+
|
1618
1799
|
Args:
|
1619
1800
|
limit: Optional; maximum number of recommendations to return.
|
1620
1801
|
market: Optional; an ISO 3166-1 alpha-2 country code to filter the response.
|
@@ -1663,36 +1844,90 @@ class SpotifyApp(APIApplication):
|
|
1663
1844
|
min_valence: Optional; minimum valence value (float) of tracks to return.
|
1664
1845
|
max_valence: Optional; maximum valence value (float) of tracks to return.
|
1665
1846
|
target_valence: Optional; target valence value (float) for recommended tracks.
|
1666
|
-
|
1847
|
+
|
1667
1848
|
Returns:
|
1668
1849
|
A JSON object containing a list of recommended tracks matching the provided seeds and filter criteria.
|
1669
|
-
|
1850
|
+
|
1670
1851
|
Raises:
|
1671
1852
|
requests.HTTPError: If the HTTP request returned an unsuccessful status code.
|
1672
1853
|
requests.RequestException: If a network-related error occurs during the request.
|
1673
|
-
|
1854
|
+
|
1674
1855
|
Tags:
|
1675
1856
|
get, recommendations, ai, music, filter
|
1676
1857
|
"""
|
1677
1858
|
url = f"{self.base_url}/recommendations"
|
1678
|
-
query_params = {
|
1859
|
+
query_params = {
|
1860
|
+
k: v
|
1861
|
+
for k, v in [
|
1862
|
+
("limit", limit),
|
1863
|
+
("market", market),
|
1864
|
+
("seed_artists", seed_artists),
|
1865
|
+
("seed_genres", seed_genres),
|
1866
|
+
("seed_tracks", seed_tracks),
|
1867
|
+
("min_acousticness", min_acousticness),
|
1868
|
+
("max_acousticness", max_acousticness),
|
1869
|
+
("target_acousticness", target_acousticness),
|
1870
|
+
("min_danceability", min_danceability),
|
1871
|
+
("max_danceability", max_danceability),
|
1872
|
+
("target_danceability", target_danceability),
|
1873
|
+
("min_duration_ms", min_duration_ms),
|
1874
|
+
("max_duration_ms", max_duration_ms),
|
1875
|
+
("target_duration_ms", target_duration_ms),
|
1876
|
+
("min_energy", min_energy),
|
1877
|
+
("max_energy", max_energy),
|
1878
|
+
("target_energy", target_energy),
|
1879
|
+
("min_instrumentalness", min_instrumentalness),
|
1880
|
+
("max_instrumentalness", max_instrumentalness),
|
1881
|
+
("target_instrumentalness", target_instrumentalness),
|
1882
|
+
("min_key", min_key),
|
1883
|
+
("max_key", max_key),
|
1884
|
+
("target_key", target_key),
|
1885
|
+
("min_liveness", min_liveness),
|
1886
|
+
("max_liveness", max_liveness),
|
1887
|
+
("target_liveness", target_liveness),
|
1888
|
+
("min_loudness", min_loudness),
|
1889
|
+
("max_loudness", max_loudness),
|
1890
|
+
("target_loudness", target_loudness),
|
1891
|
+
("min_mode", min_mode),
|
1892
|
+
("max_mode", max_mode),
|
1893
|
+
("target_mode", target_mode),
|
1894
|
+
("min_popularity", min_popularity),
|
1895
|
+
("max_popularity", max_popularity),
|
1896
|
+
("target_popularity", target_popularity),
|
1897
|
+
("min_speechiness", min_speechiness),
|
1898
|
+
("max_speechiness", max_speechiness),
|
1899
|
+
("target_speechiness", target_speechiness),
|
1900
|
+
("min_tempo", min_tempo),
|
1901
|
+
("max_tempo", max_tempo),
|
1902
|
+
("target_tempo", target_tempo),
|
1903
|
+
("min_time_signature", min_time_signature),
|
1904
|
+
("max_time_signature", max_time_signature),
|
1905
|
+
("target_time_signature", target_time_signature),
|
1906
|
+
("min_valence", min_valence),
|
1907
|
+
("max_valence", max_valence),
|
1908
|
+
("target_valence", target_valence),
|
1909
|
+
]
|
1910
|
+
if v is not None
|
1911
|
+
}
|
1679
1912
|
response = self._get(url, params=query_params)
|
1680
1913
|
response.raise_for_status()
|
1681
1914
|
return response.json()
|
1682
1915
|
|
1683
|
-
def get_recommendation_genres(
|
1916
|
+
def get_recommendation_genres(
|
1917
|
+
self,
|
1918
|
+
) -> Any:
|
1684
1919
|
"""
|
1685
1920
|
Retrieves a list of available genre seeds for recommendations from the remote API.
|
1686
|
-
|
1921
|
+
|
1687
1922
|
Args:
|
1688
1923
|
None: This function takes no arguments
|
1689
|
-
|
1924
|
+
|
1690
1925
|
Returns:
|
1691
1926
|
dict: A JSON object containing available genre seeds for recommendations.
|
1692
|
-
|
1927
|
+
|
1693
1928
|
Raises:
|
1694
1929
|
requests.exceptions.HTTPError: If the HTTP request to the API fails or returns an error status code.
|
1695
|
-
|
1930
|
+
|
1696
1931
|
Tags:
|
1697
1932
|
get, list, api, recommendation, genres
|
1698
1933
|
"""
|
@@ -1702,25 +1937,31 @@ class SpotifyApp(APIApplication):
|
|
1702
1937
|
response.raise_for_status()
|
1703
1938
|
return response.json()
|
1704
1939
|
|
1705
|
-
def get_information_about_the_users_current_playback(
|
1940
|
+
def get_information_about_the_users_current_playback(
|
1941
|
+
self, market=None, additional_types=None
|
1942
|
+
) -> Any:
|
1706
1943
|
"""
|
1707
1944
|
Retrieves information about the user's current playback state from the music service.
|
1708
|
-
|
1945
|
+
|
1709
1946
|
Args:
|
1710
1947
|
market: Optional; a string specifying an ISO 3166-1 alpha-2 country code to filter the response content. Defaults to None.
|
1711
1948
|
additional_types: Optional; a comma-separated string specifying additional item types to include in the response. Defaults to None.
|
1712
|
-
|
1949
|
+
|
1713
1950
|
Returns:
|
1714
1951
|
A JSON object containing the user's current playback information, such as track, device, and playback state.
|
1715
|
-
|
1952
|
+
|
1716
1953
|
Raises:
|
1717
1954
|
requests.exceptions.HTTPError: If the HTTP request to the music service API fails or returns an error status code.
|
1718
|
-
|
1955
|
+
|
1719
1956
|
Tags:
|
1720
1957
|
get, playback, user, status, api
|
1721
1958
|
"""
|
1722
1959
|
url = f"{self.base_url}/me/player"
|
1723
|
-
query_params = {
|
1960
|
+
query_params = {
|
1961
|
+
k: v
|
1962
|
+
for k, v in [("market", market), ("additional_types", additional_types)]
|
1963
|
+
if v is not None
|
1964
|
+
}
|
1724
1965
|
response = self._get(url, params=query_params)
|
1725
1966
|
response.raise_for_status()
|
1726
1967
|
return response.json()
|
@@ -1728,26 +1969,26 @@ class SpotifyApp(APIApplication):
|
|
1728
1969
|
def transfer_a_users_playback(self, device_ids, play=None) -> Any:
|
1729
1970
|
"""
|
1730
1971
|
Transfers the playback of a user's current session to one or more specified devices.
|
1731
|
-
|
1972
|
+
|
1732
1973
|
Args:
|
1733
1974
|
device_ids: list or str. A list of device IDs (or a single device ID) to which playback should be transferred. This parameter is required.
|
1734
1975
|
play: bool or None. Whether playback should start on the new device(s) after transfer. If None, the playback state is not changed. Optional.
|
1735
|
-
|
1976
|
+
|
1736
1977
|
Returns:
|
1737
1978
|
dict. A JSON response from the server, typically containing the status or details of the playback transfer.
|
1738
|
-
|
1979
|
+
|
1739
1980
|
Raises:
|
1740
1981
|
ValueError: Raised if 'device_ids' is None.
|
1741
1982
|
requests.HTTPError: Raised if the underlying HTTP request fails or returns an error status code.
|
1742
|
-
|
1983
|
+
|
1743
1984
|
Tags:
|
1744
1985
|
transfer, playback, management, api-call
|
1745
1986
|
"""
|
1746
1987
|
if device_ids is None:
|
1747
1988
|
raise ValueError("Missing required parameter 'device_ids'")
|
1748
1989
|
request_body = {
|
1749
|
-
|
1750
|
-
|
1990
|
+
"device_ids": device_ids,
|
1991
|
+
"play": play,
|
1751
1992
|
}
|
1752
1993
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
1753
1994
|
url = f"{self.base_url}/me/player"
|
@@ -1756,19 +1997,21 @@ class SpotifyApp(APIApplication):
|
|
1756
1997
|
response.raise_for_status()
|
1757
1998
|
return response.json()
|
1758
1999
|
|
1759
|
-
def get_a_users_available_devices(
|
2000
|
+
def get_a_users_available_devices(
|
2001
|
+
self,
|
2002
|
+
) -> Any:
|
1760
2003
|
"""
|
1761
2004
|
Retrieves the list of devices available to the current user for playback control.
|
1762
|
-
|
2005
|
+
|
1763
2006
|
Args:
|
1764
2007
|
None: This function takes no arguments
|
1765
|
-
|
2008
|
+
|
1766
2009
|
Returns:
|
1767
2010
|
dict: A JSON object containing information about the user's available playback devices.
|
1768
|
-
|
2011
|
+
|
1769
2012
|
Raises:
|
1770
2013
|
requests.HTTPError: If the HTTP request to the devices endpoint fails or returns a non-success status code.
|
1771
|
-
|
2014
|
+
|
1772
2015
|
Tags:
|
1773
2016
|
get, list, devices, user, management
|
1774
2017
|
"""
|
@@ -1778,58 +2021,66 @@ class SpotifyApp(APIApplication):
|
|
1778
2021
|
response.raise_for_status()
|
1779
2022
|
return response.json()
|
1780
2023
|
|
1781
|
-
def get_the_users_currently_playing_track(
|
2024
|
+
def get_the_users_currently_playing_track(
|
2025
|
+
self, market=None, additional_types=None
|
2026
|
+
) -> Any:
|
1782
2027
|
"""
|
1783
2028
|
Retrieves information about the track currently being played by the user.
|
1784
|
-
|
2029
|
+
|
1785
2030
|
Args:
|
1786
2031
|
market: Optional; a string specifying the market (country code) to filter the track data, ensuring results are relevant to a particular geographic location. Defaults to None.
|
1787
2032
|
additional_types: Optional; a string or comma-separated list specifying additional item types (such as 'episode') to include in the response. Defaults to None.
|
1788
|
-
|
2033
|
+
|
1789
2034
|
Returns:
|
1790
2035
|
dict: A dictionary containing details about the currently playing track, or None if no data is available.
|
1791
|
-
|
2036
|
+
|
1792
2037
|
Raises:
|
1793
2038
|
requests.HTTPError: If the underlying HTTP request fails or returns an unsuccessful status code.
|
1794
|
-
|
2039
|
+
|
1795
2040
|
Tags:
|
1796
2041
|
get, track, player, user, async_job
|
1797
2042
|
"""
|
1798
2043
|
url = f"{self.base_url}/me/player/currently-playing"
|
1799
|
-
query_params = {
|
2044
|
+
query_params = {
|
2045
|
+
k: v
|
2046
|
+
for k, v in [("market", market), ("additional_types", additional_types)]
|
2047
|
+
if v is not None
|
2048
|
+
}
|
1800
2049
|
response = self._get(url, params=query_params)
|
1801
2050
|
response.raise_for_status()
|
1802
2051
|
return response.json()
|
1803
2052
|
|
1804
|
-
def start_a_users_playback(
|
2053
|
+
def start_a_users_playback(
|
2054
|
+
self, device_id=None, context_uri=None, uris=None, offset=None, position_ms=None
|
2055
|
+
) -> Any:
|
1805
2056
|
"""
|
1806
2057
|
Starts or resumes playback of a user's Spotify player on the specified device, context, or track list.
|
1807
|
-
|
2058
|
+
|
1808
2059
|
Args:
|
1809
2060
|
device_id: Optional[str]. The Spotify device ID on which playback should start. If not specified, the user's current active device is used.
|
1810
2061
|
context_uri: Optional[str]. Spotify URI of the context to play (album, playlist, or artist). Mutually exclusive with 'uris'.
|
1811
2062
|
uris: Optional[list[str]]. List of Spotify track URIs to play. Mutually exclusive with 'context_uri'.
|
1812
2063
|
offset: Optional[dict or int or str]. Indicates from which position in 'uris' or 'context_uri' playback should start. Can be a dict specifying 'position' or 'uri', or an integer index.
|
1813
2064
|
position_ms: Optional[int]. Start playback at this position in milliseconds.
|
1814
|
-
|
2065
|
+
|
1815
2066
|
Returns:
|
1816
2067
|
Any. The JSON-parsed response from the Spotify Web API containing the result of the playback request.
|
1817
|
-
|
2068
|
+
|
1818
2069
|
Raises:
|
1819
2070
|
requests.HTTPError: If the underlying HTTP request fails or an error response is returned from the Spotify Web API.
|
1820
|
-
|
2071
|
+
|
1821
2072
|
Tags:
|
1822
2073
|
start, playback, ai, management, async_job
|
1823
2074
|
"""
|
1824
2075
|
request_body = {
|
1825
|
-
|
1826
|
-
|
1827
|
-
|
1828
|
-
|
2076
|
+
"context_uri": context_uri,
|
2077
|
+
"uris": uris,
|
2078
|
+
"offset": offset,
|
2079
|
+
"position_ms": position_ms,
|
1829
2080
|
}
|
1830
2081
|
request_body = {k: v for k, v in request_body.items() if v is not None}
|
1831
2082
|
url = f"{self.base_url}/me/player/play"
|
1832
|
-
query_params = {k: v for k, v in [(
|
2083
|
+
query_params = {k: v for k, v in [("device_id", device_id)] if v is not None}
|
1833
2084
|
response = self._put(url, data=request_body, params=query_params)
|
1834
2085
|
response.raise_for_status()
|
1835
2086
|
return response.json()
|
@@ -1837,21 +2088,21 @@ class SpotifyApp(APIApplication):
|
|
1837
2088
|
def pause_a_users_playback(self, device_id=None) -> Any:
|
1838
2089
|
"""
|
1839
2090
|
Pauses the current playback for the authenticated user.
|
1840
|
-
|
2091
|
+
|
1841
2092
|
Args:
|
1842
2093
|
device_id: Optional string representing the Spotify device ID on which playback should be paused. If not provided, the user's currently active device is targeted.
|
1843
|
-
|
2094
|
+
|
1844
2095
|
Returns:
|
1845
2096
|
The JSON response from the Spotify API. This will typically be an empty object if the request was successful.
|
1846
|
-
|
2097
|
+
|
1847
2098
|
Raises:
|
1848
2099
|
HTTPError: Raised when the Spotify API returns an error response, such as when the user doesn't have an active device, the user doesn't have a premium account, or there's an authentication issue.
|
1849
|
-
|
2100
|
+
|
1850
2101
|
Tags:
|
1851
2102
|
pause, playback, control, spotify
|
1852
2103
|
"""
|
1853
2104
|
url = f"{self.base_url}/me/player/pause"
|
1854
|
-
query_params = {k: v for k, v in [(
|
2105
|
+
query_params = {k: v for k, v in [("device_id", device_id)] if v is not None}
|
1855
2106
|
response = self._put(url, data={}, params=query_params)
|
1856
2107
|
response.raise_for_status()
|
1857
2108
|
return response.json()
|
@@ -1859,21 +2110,21 @@ class SpotifyApp(APIApplication):
|
|
1859
2110
|
def skip_users_playback_to_next_track(self, device_id=None) -> Any:
|
1860
2111
|
"""
|
1861
2112
|
Skips the user's playback to the next track on the current or specified device.
|
1862
|
-
|
2113
|
+
|
1863
2114
|
Args:
|
1864
2115
|
device_id: Optional; the ID of the device on which to skip to the next track. If None, the currently active device is used.
|
1865
|
-
|
2116
|
+
|
1866
2117
|
Returns:
|
1867
2118
|
dict: The response from the API after attempting to skip to the next track.
|
1868
|
-
|
2119
|
+
|
1869
2120
|
Raises:
|
1870
2121
|
requests.HTTPError: If the HTTP request to skip to the next track fails with an unsuccessful status code.
|
1871
|
-
|
2122
|
+
|
1872
2123
|
Tags:
|
1873
2124
|
skip, playback-control, user, spotify-api
|
1874
2125
|
"""
|
1875
2126
|
url = f"{self.base_url}/me/player/next"
|
1876
|
-
query_params = {k: v for k, v in [(
|
2127
|
+
query_params = {k: v for k, v in [("device_id", device_id)] if v is not None}
|
1877
2128
|
response = self._post(url, data={}, params=query_params)
|
1878
2129
|
response.raise_for_status()
|
1879
2130
|
return response.json()
|
@@ -1881,47 +2132,53 @@ class SpotifyApp(APIApplication):
|
|
1881
2132
|
def skip_users_playback_to_previous_track(self, device_id=None) -> Any:
|
1882
2133
|
"""
|
1883
2134
|
Skips the user's playback to the previous track on the active or specified device.
|
1884
|
-
|
2135
|
+
|
1885
2136
|
Args:
|
1886
2137
|
device_id: Optional; string representing the device ID to control. If not provided, defaults to the user's currently active device.
|
1887
|
-
|
2138
|
+
|
1888
2139
|
Returns:
|
1889
2140
|
The JSON response from the API after attempting to skip to the previous track.
|
1890
|
-
|
2141
|
+
|
1891
2142
|
Raises:
|
1892
2143
|
requests.HTTPError: If the HTTP request to the playback API fails or returns an error status.
|
1893
|
-
|
2144
|
+
|
1894
2145
|
Tags:
|
1895
2146
|
playback-control, skip, previous-track, user, api
|
1896
2147
|
"""
|
1897
2148
|
url = f"{self.base_url}/me/player/previous"
|
1898
|
-
query_params = {k: v for k, v in [(
|
2149
|
+
query_params = {k: v for k, v in [("device_id", device_id)] if v is not None}
|
1899
2150
|
response = self._post(url, data={}, params=query_params)
|
1900
2151
|
response.raise_for_status()
|
1901
2152
|
return response.json()
|
1902
2153
|
|
1903
|
-
def seek_to_position_in_currently_playing_track(
|
2154
|
+
def seek_to_position_in_currently_playing_track(
|
2155
|
+
self, position_ms, device_id=None
|
2156
|
+
) -> Any:
|
1904
2157
|
"""
|
1905
2158
|
Seeks to the specified position in the currently playing track for the user.
|
1906
|
-
|
2159
|
+
|
1907
2160
|
Args:
|
1908
2161
|
position_ms: int. The position in milliseconds to seek to within the currently playing track. Must not be None.
|
1909
2162
|
device_id: Optional[str]. The ID of the target device on which to seek. If not specified, the currently active device is used.
|
1910
|
-
|
2163
|
+
|
1911
2164
|
Returns:
|
1912
2165
|
dict. The JSON response from the API after seeking to the specified position.
|
1913
|
-
|
2166
|
+
|
1914
2167
|
Raises:
|
1915
2168
|
ValueError: If 'position_ms' is None.
|
1916
2169
|
requests.exceptions.HTTPError: If the HTTP request to seek fails with a bad status code.
|
1917
|
-
|
2170
|
+
|
1918
2171
|
Tags:
|
1919
2172
|
seek, player-control, api
|
1920
2173
|
"""
|
1921
2174
|
if position_ms is None:
|
1922
2175
|
raise ValueError("Missing required parameter 'position_ms'")
|
1923
2176
|
url = f"{self.base_url}/me/player/seek"
|
1924
|
-
query_params = {
|
2177
|
+
query_params = {
|
2178
|
+
k: v
|
2179
|
+
for k, v in [("position_ms", position_ms), ("device_id", device_id)]
|
2180
|
+
if v is not None
|
2181
|
+
}
|
1925
2182
|
response = self._put(url, data={}, params=query_params)
|
1926
2183
|
response.raise_for_status()
|
1927
2184
|
return response.json()
|
@@ -1929,25 +2186,29 @@ class SpotifyApp(APIApplication):
|
|
1929
2186
|
def set_repeat_mode_on_users_playback(self, state, device_id=None) -> Any:
|
1930
2187
|
"""
|
1931
2188
|
Sets the repeat mode for the current user's playback on Spotify, optionally targeting a specific device.
|
1932
|
-
|
2189
|
+
|
1933
2190
|
Args:
|
1934
2191
|
state: str. The desired repeat mode. Valid values include 'track', 'context', or 'off'.
|
1935
2192
|
device_id: Optional[str]. The Spotify device ID to target. If not specified, applies to the user's currently active device.
|
1936
|
-
|
2193
|
+
|
1937
2194
|
Returns:
|
1938
2195
|
dict. The JSON response from the Spotify Web API after updating the repeat mode.
|
1939
|
-
|
2196
|
+
|
1940
2197
|
Raises:
|
1941
2198
|
ValueError: Raised if the required 'state' parameter is not provided.
|
1942
2199
|
requests.HTTPError: Raised if the HTTP request to the Spotify API fails (e.g., due to a bad request or authorization error).
|
1943
|
-
|
2200
|
+
|
1944
2201
|
Tags:
|
1945
2202
|
set, playback, repeat, management
|
1946
2203
|
"""
|
1947
2204
|
if state is None:
|
1948
2205
|
raise ValueError("Missing required parameter 'state'")
|
1949
2206
|
url = f"{self.base_url}/me/player/repeat"
|
1950
|
-
query_params = {
|
2207
|
+
query_params = {
|
2208
|
+
k: v
|
2209
|
+
for k, v in [("state", state), ("device_id", device_id)]
|
2210
|
+
if v is not None
|
2211
|
+
}
|
1951
2212
|
response = self._put(url, data={}, params=query_params)
|
1952
2213
|
response.raise_for_status()
|
1953
2214
|
return response.json()
|
@@ -1955,25 +2216,29 @@ class SpotifyApp(APIApplication):
|
|
1955
2216
|
def set_volume_for_users_playback(self, volume_percent, device_id=None) -> Any:
|
1956
2217
|
"""
|
1957
2218
|
Set the playback volume for the current user's active device.
|
1958
|
-
|
2219
|
+
|
1959
2220
|
Args:
|
1960
2221
|
volume_percent: int. The desired volume level as a percentage (0-100).
|
1961
2222
|
device_id: str, optional. The unique identifier for the target device. If not specified, the user's currently active device is used.
|
1962
|
-
|
2223
|
+
|
1963
2224
|
Returns:
|
1964
2225
|
dict. The JSON response from the API containing the result of the volume change operation.
|
1965
|
-
|
2226
|
+
|
1966
2227
|
Raises:
|
1967
2228
|
ValueError: If 'volume_percent' is None.
|
1968
2229
|
requests.HTTPError: If the HTTP request to the API fails or returns an error response.
|
1969
|
-
|
2230
|
+
|
1970
2231
|
Tags:
|
1971
2232
|
set, volume, playback, user-management
|
1972
2233
|
"""
|
1973
2234
|
if volume_percent is None:
|
1974
2235
|
raise ValueError("Missing required parameter 'volume_percent'")
|
1975
2236
|
url = f"{self.base_url}/me/player/volume"
|
1976
|
-
query_params = {
|
2237
|
+
query_params = {
|
2238
|
+
k: v
|
2239
|
+
for k, v in [("volume_percent", volume_percent), ("device_id", device_id)]
|
2240
|
+
if v is not None
|
2241
|
+
}
|
1977
2242
|
response = self._put(url, data={}, params=query_params)
|
1978
2243
|
response.raise_for_status()
|
1979
2244
|
return response.json()
|
@@ -1981,25 +2246,29 @@ class SpotifyApp(APIApplication):
|
|
1981
2246
|
def toggle_shuffle_for_users_playback(self, state, device_id=None) -> Any:
|
1982
2247
|
"""
|
1983
2248
|
Toggles the shuffle state for the user's playback on the specified device.
|
1984
|
-
|
2249
|
+
|
1985
2250
|
Args:
|
1986
2251
|
state: bool. Whether to enable (True) or disable (False) shuffle playback.
|
1987
2252
|
device_id: str or None. The Spotify device ID on which to set shuffle mode. If None, the active device is used.
|
1988
|
-
|
2253
|
+
|
1989
2254
|
Returns:
|
1990
2255
|
dict. The JSON response from the server containing the playback state information.
|
1991
|
-
|
2256
|
+
|
1992
2257
|
Raises:
|
1993
2258
|
ValueError: If the required parameter 'state' is None.
|
1994
2259
|
HTTPError: If the server returns an unsuccessful status code.
|
1995
|
-
|
2260
|
+
|
1996
2261
|
Tags:
|
1997
2262
|
toggle, shuffle, playback, user, management, spotify
|
1998
2263
|
"""
|
1999
2264
|
if state is None:
|
2000
2265
|
raise ValueError("Missing required parameter 'state'")
|
2001
2266
|
url = f"{self.base_url}/me/player/shuffle"
|
2002
|
-
query_params = {
|
2267
|
+
query_params = {
|
2268
|
+
k: v
|
2269
|
+
for k, v in [("state", state), ("device_id", device_id)]
|
2270
|
+
if v is not None
|
2271
|
+
}
|
2003
2272
|
response = self._put(url, data={}, params=query_params)
|
2004
2273
|
response.raise_for_status()
|
2005
2274
|
return response.json()
|
@@ -2007,40 +2276,46 @@ class SpotifyApp(APIApplication):
|
|
2007
2276
|
def get_recently_played(self, limit=None, after=None, before=None) -> Any:
|
2008
2277
|
"""
|
2009
2278
|
Retrieves the current user's recently played tracks from the Spotify API, optionally filtered by time or limited in count.
|
2010
|
-
|
2279
|
+
|
2011
2280
|
Args:
|
2012
2281
|
limit: Optional; int or None. Maximum number of items to return (default set by API).
|
2013
2282
|
after: Optional; int, Unix timestamp in milliseconds or None. Returns items played after this time.
|
2014
2283
|
before: Optional; int, Unix timestamp in milliseconds or None. Returns items played before this time.
|
2015
|
-
|
2284
|
+
|
2016
2285
|
Returns:
|
2017
2286
|
dict: A JSON object containing the list of recently played track objects and related metadata.
|
2018
|
-
|
2287
|
+
|
2019
2288
|
Raises:
|
2020
2289
|
requests.exceptions.HTTPError: If the HTTP request returned an unsuccessful status code.
|
2021
|
-
|
2290
|
+
|
2022
2291
|
Tags:
|
2023
2292
|
get, list, spotify-api, user-library, recently-played
|
2024
2293
|
"""
|
2025
2294
|
url = f"{self.base_url}/me/player/recently-played"
|
2026
|
-
query_params = {
|
2295
|
+
query_params = {
|
2296
|
+
k: v
|
2297
|
+
for k, v in [("limit", limit), ("after", after), ("before", before)]
|
2298
|
+
if v is not None
|
2299
|
+
}
|
2027
2300
|
response = self._get(url, params=query_params)
|
2028
2301
|
response.raise_for_status()
|
2029
2302
|
return response.json()
|
2030
2303
|
|
2031
|
-
def get_queue(
|
2304
|
+
def get_queue(
|
2305
|
+
self,
|
2306
|
+
) -> Any:
|
2032
2307
|
"""
|
2033
2308
|
Retrieves the current playback queue for the user from the music player API.
|
2034
|
-
|
2309
|
+
|
2035
2310
|
Args:
|
2036
2311
|
None: This function takes no arguments
|
2037
|
-
|
2312
|
+
|
2038
2313
|
Returns:
|
2039
2314
|
dict: The JSON response containing the user's current playback queue.
|
2040
|
-
|
2315
|
+
|
2041
2316
|
Raises:
|
2042
2317
|
requests.HTTPError: If the HTTP request to the player queue endpoint returns an unsuccessful status code.
|
2043
|
-
|
2318
|
+
|
2044
2319
|
Tags:
|
2045
2320
|
get, queue, api, player
|
2046
2321
|
"""
|
@@ -2053,42 +2328,46 @@ class SpotifyApp(APIApplication):
|
|
2053
2328
|
def add_to_queue(self, uri, device_id=None) -> Any:
|
2054
2329
|
"""
|
2055
2330
|
Adds an item to the user's playback queue on the specified device using its URI.
|
2056
|
-
|
2331
|
+
|
2057
2332
|
Args:
|
2058
2333
|
uri: str. The Spotify URI of the item to add to the queue. Must not be None.
|
2059
2334
|
device_id: Optional[str]. The ID of the target device for playback. If None, uses the user's currently active device.
|
2060
|
-
|
2335
|
+
|
2061
2336
|
Returns:
|
2062
2337
|
dict. The JSON response from the Spotify API containing the result of the queue addition.
|
2063
|
-
|
2338
|
+
|
2064
2339
|
Raises:
|
2065
2340
|
ValueError: If the 'uri' parameter is None.
|
2066
2341
|
requests.HTTPError: If the HTTP request to the Spotify API fails.
|
2067
|
-
|
2342
|
+
|
2068
2343
|
Tags:
|
2069
2344
|
add, queue, spotify, api, player
|
2070
2345
|
"""
|
2071
2346
|
if uri is None:
|
2072
2347
|
raise ValueError("Missing required parameter 'uri'")
|
2073
2348
|
url = f"{self.base_url}/me/player/queue"
|
2074
|
-
query_params = {
|
2349
|
+
query_params = {
|
2350
|
+
k: v for k, v in [("uri", uri), ("device_id", device_id)] if v is not None
|
2351
|
+
}
|
2075
2352
|
response = self._post(url, data={}, params=query_params)
|
2076
2353
|
response.raise_for_status()
|
2077
2354
|
return response.json()
|
2078
2355
|
|
2079
|
-
def get_available_markets(
|
2356
|
+
def get_available_markets(
|
2357
|
+
self,
|
2358
|
+
) -> Any:
|
2080
2359
|
"""
|
2081
2360
|
Retrieves a list of available markets from the API endpoint.
|
2082
|
-
|
2361
|
+
|
2083
2362
|
Args:
|
2084
2363
|
None: This function takes no arguments
|
2085
|
-
|
2364
|
+
|
2086
2365
|
Returns:
|
2087
2366
|
A JSON-decoded response containing information about available markets.
|
2088
|
-
|
2367
|
+
|
2089
2368
|
Raises:
|
2090
2369
|
requests.HTTPError: If the HTTP request to the API endpoint fails or an error status code is returned.
|
2091
|
-
|
2370
|
+
|
2092
2371
|
Tags:
|
2093
2372
|
get, markets, api, list, fetch
|
2094
2373
|
"""
|
@@ -2101,23 +2380,31 @@ class SpotifyApp(APIApplication):
|
|
2101
2380
|
def get_users_top_artists(self, time_range=None, limit=None, offset=None) -> Any:
|
2102
2381
|
"""
|
2103
2382
|
Retrieves the current user's top artists from the API, supporting optional filtering by time range, result limit, and pagination offset.
|
2104
|
-
|
2383
|
+
|
2105
2384
|
Args:
|
2106
2385
|
time_range: Optional; a string indicating the time range over which to retrieve top artists (e.g., 'short_term', 'medium_term', 'long_term'). If None, the API default is used.
|
2107
2386
|
limit: Optional; an integer specifying the maximum number of artists to return. If None, the API default is used.
|
2108
2387
|
offset: Optional; an integer specifying the index of the first artist to return for pagination. If None, the API default is used.
|
2109
|
-
|
2388
|
+
|
2110
2389
|
Returns:
|
2111
2390
|
A JSON-deserialized object containing the user's top artists and related metadata as returned by the API.
|
2112
|
-
|
2391
|
+
|
2113
2392
|
Raises:
|
2114
2393
|
requests.HTTPError: If the API request fails or returns an unsuccessful HTTP status code.
|
2115
|
-
|
2394
|
+
|
2116
2395
|
Tags:
|
2117
2396
|
get, list, artists, user, ai, batch
|
2118
2397
|
"""
|
2119
2398
|
url = f"{self.base_url}/me/top/artists"
|
2120
|
-
query_params = {
|
2399
|
+
query_params = {
|
2400
|
+
k: v
|
2401
|
+
for k, v in [
|
2402
|
+
("time_range", time_range),
|
2403
|
+
("limit", limit),
|
2404
|
+
("offset", offset),
|
2405
|
+
]
|
2406
|
+
if v is not None
|
2407
|
+
}
|
2121
2408
|
response = self._get(url, params=query_params)
|
2122
2409
|
response.raise_for_status()
|
2123
2410
|
return response.json()
|
@@ -2125,23 +2412,31 @@ class SpotifyApp(APIApplication):
|
|
2125
2412
|
def get_users_top_tracks(self, time_range=None, limit=None, offset=None) -> Any:
|
2126
2413
|
"""
|
2127
2414
|
Retrieves the current user's top tracks from the service within an optional time range, with pagination support.
|
2128
|
-
|
2415
|
+
|
2129
2416
|
Args:
|
2130
2417
|
time_range: Optional; str. Specifies the time range for top tracks (e.g., 'short_term', 'medium_term', 'long_term').
|
2131
2418
|
limit: Optional; int. The maximum number of tracks to return.
|
2132
2419
|
offset: Optional; int. The index of the first track to return, used for pagination.
|
2133
|
-
|
2420
|
+
|
2134
2421
|
Returns:
|
2135
2422
|
dict. The JSON response containing the user's top tracks and associated metadata.
|
2136
|
-
|
2423
|
+
|
2137
2424
|
Raises:
|
2138
2425
|
requests.HTTPError: If the HTTP request fails or returns an unsuccessful status code.
|
2139
|
-
|
2426
|
+
|
2140
2427
|
Tags:
|
2141
2428
|
get, list, user, tracks, ai
|
2142
2429
|
"""
|
2143
2430
|
url = f"{self.base_url}/me/top/tracks"
|
2144
|
-
query_params = {
|
2431
|
+
query_params = {
|
2432
|
+
k: v
|
2433
|
+
for k, v in [
|
2434
|
+
("time_range", time_range),
|
2435
|
+
("limit", limit),
|
2436
|
+
("offset", offset),
|
2437
|
+
]
|
2438
|
+
if v is not None
|
2439
|
+
}
|
2145
2440
|
response = self._get(url, params=query_params)
|
2146
2441
|
response.raise_for_status()
|
2147
2442
|
return response.json()
|
@@ -2227,5 +2522,5 @@ class SpotifyApp(APIApplication):
|
|
2227
2522
|
self.add_to_queue,
|
2228
2523
|
self.get_available_markets,
|
2229
2524
|
self.get_users_top_artists,
|
2230
|
-
self.get_users_top_tracks
|
2525
|
+
self.get_users_top_tracks,
|
2231
2526
|
]
|