universal-mcp 0.1.9rc1__py3-none-any.whl → 0.1.10__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.
Files changed (29) hide show
  1. universal_mcp/applications/application.py +19 -30
  2. universal_mcp/applications/cal_com_v2/app.py +1676 -1021
  3. universal_mcp/applications/clickup/app.py +1496 -846
  4. universal_mcp/applications/falai/README.md +42 -0
  5. universal_mcp/applications/falai/__init__.py +0 -0
  6. universal_mcp/applications/falai/app.py +332 -0
  7. universal_mcp/applications/gong/README.md +88 -0
  8. universal_mcp/applications/gong/__init__.py +0 -0
  9. universal_mcp/applications/gong/app.py +2297 -0
  10. universal_mcp/applications/hashnode/app.py +12 -8
  11. universal_mcp/applications/hashnode/prompt.md +2 -0
  12. universal_mcp/applications/heygen/README.md +69 -0
  13. universal_mcp/applications/heygen/__init__.py +0 -0
  14. universal_mcp/applications/heygen/app.py +956 -0
  15. universal_mcp/applications/mailchimp/app.py +3848 -1794
  16. universal_mcp/applications/replicate/README.md +47 -35
  17. universal_mcp/applications/replicate/__init__.py +0 -0
  18. universal_mcp/applications/replicate/app.py +215 -204
  19. universal_mcp/applications/retell_ai/app.py +84 -67
  20. universal_mcp/applications/rocketlane/app.py +49 -35
  21. universal_mcp/applications/spotify/app.py +723 -428
  22. universal_mcp/applications/supabase/app.py +909 -583
  23. universal_mcp/servers/server.py +50 -0
  24. universal_mcp/stores/store.py +2 -3
  25. universal_mcp/utils/docstring_parser.py +67 -36
  26. {universal_mcp-0.1.9rc1.dist-info → universal_mcp-0.1.10.dist-info}/METADATA +5 -1
  27. {universal_mcp-0.1.9rc1.dist-info → universal_mcp-0.1.10.dist-info}/RECORD +29 -19
  28. {universal_mcp-0.1.9rc1.dist-info → universal_mcp-0.1.10.dist-info}/WHEEL +0 -0
  29. {universal_mcp-0.1.9rc1.dist-info → universal_mcp-0.1.10.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='spotify', integration=integration, **kwargs)
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 [('market', market)] if v is not None}
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 = {k: v for k, v in [('ids', ids), ('market', market)] if v is not None}
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 = {k: v for k, v in [('market', market), ('limit', limit), ('offset', offset)] if v is not None}
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 [('ids', ids)] if v is not None}
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(self, id, include_groups=None, market=None, limit=None, offset=None) -> Any:
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 = {k: v for k, v in [('include_groups', include_groups), ('market', market), ('limit', limit), ('offset', offset)] if v is not None}
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 [('market', market)] if v is not None}
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 [('market', market)] if v is not None}
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 = {k: v for k, v in [('market', market), ('ids', ids)] if v is not None}
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 = {k: v for k, v in [('market', market), ('limit', limit), ('offset', offset)] if v is not None}
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 [('market', market)] if v is not None}
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 = {k: v for k, v in [('ids', ids), ('market', market)] if v is not None}
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 [('market', market)] if v is not None}
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 = {k: v for k, v in [('ids', ids), ('market', market)] if v is not None}
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 = {k: v for k, v in [('market', market), ('limit', limit), ('offset', offset)] if v is not None}
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 = {k: v for k, v in [('limit', limit), ('offset', offset)] if v is not None}
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 [('ids', ids)] if v is not None}
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 [('ids', ids)] if v is not None}
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 [('ids', ids)] if v is not None}
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 [('market', market)] if v is not None}
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 = {k: v for k, v in [('ids', ids), ('market', market)] if v is not None}
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 [('market', market)] if v is not None}
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 = {k: v for k, v in [('market', market), ('ids', ids)] if v is not None}
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(self, q, type, market=None, limit=None, offset=None, include_external=None) -> Any:
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 = {k: v for k, v in [('q', q), ('type', type), ('market', market), ('limit', limit), ('offset', offset), ('include_external', include_external)] if v is not None}
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(self, ) -> Any:
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(self, playlist_id, market=None, fields=None, additional_types=None) -> Any:
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 = {k: v for k, v in [('market', market), ('fields', fields), ('additional_types', additional_types)] if v is not None}
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(self, playlist_id, name=None, public=None, collaborative=None, description=None) -> Any:
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
- 'name': name,
743
- 'public': public,
744
- 'collaborative': collaborative,
745
- 'description': description,
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(self, playlist_id, market=None, fields=None, limit=None, offset=None, additional_types=None) -> Any:
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 = {k: v for k, v in [('market', market), ('fields', fields), ('limit', limit), ('offset', offset), ('additional_types', additional_types)] if v is not None}
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
- 'uris': uris,
807
- 'position': position,
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 = {k: v for k, v in [('position', position), ('uris', uris)] if v is not None}
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(self, playlist_id, uris=None, range_start=None, insert_before=None, range_length=None, snapshot_id=None) -> Any:
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
- 'uris': uris,
842
- 'range_start': range_start,
843
- 'insert_before': insert_before,
844
- 'range_length': range_length,
845
- 'snapshot_id': snapshot_id,
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 [('uris', uris)] if v is not None}
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 = {k: v for k, v in [('limit', limit), ('offset', offset)] if v is not None}
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 = {k: v for k, v in [('limit', limit), ('offset', offset), ('market', market)] if v is not None}
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 [('ids', ids)] if v is not None}
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 = {k: v for k, v in [('market', market), ('limit', limit), ('offset', offset)] if v is not None}
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
- 'ids': ids,
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 [('ids', ids)] if v is not None}
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 [('ids', ids)] if v is not None}
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 = {k: v for k, v in [('market', market), ('limit', limit), ('offset', offset)] if v is not None}
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
- 'ids': ids,
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 [('ids', ids)] if v is not None}
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 [('ids', ids)] if v is not None}
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 = {k: v for k, v in [('limit', limit), ('offset', offset)] if v is not None}
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 [('ids', ids)] if v is not None}
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 = {k: v for k, v in [('limit', limit), ('offset', offset)] if v is not None}
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(self, user_id, name, public=None, collaborative=None, description=None) -> Any:
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
- 'name': name,
1209
- 'public': public,
1210
- 'collaborative': collaborative,
1211
- 'description': description,
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
- 'public': public,
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 = {k: v for k, v in [('locale', locale), ('limit', limit), ('offset', offset)] if v is not None}
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 = {k: v for k, v in [('locale', locale), ('limit', limit), ('offset', offset)] if v is not None}
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 [('locale', locale)] if v is not None}
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 = {k: v for k, v in [('limit', limit), ('offset', offset)] if v is not None}
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 = {k: v for k, v in [('limit', limit), ('offset', offset)] if v is not None}
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 = {k: v for k, v in [('type', type), ('after', after), ('limit', limit)] if v is not None}
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
- 'ids': ids,
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 = {k: v for k, v in [('type', type), ('ids', ids)] if v is not None}
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 = {k: v for k, v in [('type', type), ('ids', ids)] if v is not None}
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 [('ids', ids)] if v is not None}
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 [('ids', ids)] if v is not None}
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(self, limit=None, market=None, seed_artists=None, seed_genres=None, seed_tracks=None, min_acousticness=None, max_acousticness=None, target_acousticness=None, min_danceability=None, max_danceability=None, target_danceability=None, min_duration_ms=None, max_duration_ms=None, target_duration_ms=None, min_energy=None, max_energy=None, target_energy=None, min_instrumentalness=None, max_instrumentalness=None, target_instrumentalness=None, min_key=None, max_key=None, target_key=None, min_liveness=None, max_liveness=None, target_liveness=None, min_loudness=None, max_loudness=None, target_loudness=None, min_mode=None, max_mode=None, target_mode=None, min_popularity=None, max_popularity=None, target_popularity=None, min_speechiness=None, max_speechiness=None, target_speechiness=None, min_tempo=None, max_tempo=None, target_tempo=None, min_time_signature=None, max_time_signature=None, target_time_signature=None, min_valence=None, max_valence=None, target_valence=None) -> Any:
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 = {k: v for k, v in [('limit', limit), ('market', market), ('seed_artists', seed_artists), ('seed_genres', seed_genres), ('seed_tracks', seed_tracks), ('min_acousticness', min_acousticness), ('max_acousticness', max_acousticness), ('target_acousticness', target_acousticness), ('min_danceability', min_danceability), ('max_danceability', max_danceability), ('target_danceability', target_danceability), ('min_duration_ms', min_duration_ms), ('max_duration_ms', max_duration_ms), ('target_duration_ms', target_duration_ms), ('min_energy', min_energy), ('max_energy', max_energy), ('target_energy', target_energy), ('min_instrumentalness', min_instrumentalness), ('max_instrumentalness', max_instrumentalness), ('target_instrumentalness', target_instrumentalness), ('min_key', min_key), ('max_key', max_key), ('target_key', target_key), ('min_liveness', min_liveness), ('max_liveness', max_liveness), ('target_liveness', target_liveness), ('min_loudness', min_loudness), ('max_loudness', max_loudness), ('target_loudness', target_loudness), ('min_mode', min_mode), ('max_mode', max_mode), ('target_mode', target_mode), ('min_popularity', min_popularity), ('max_popularity', max_popularity), ('target_popularity', target_popularity), ('min_speechiness', min_speechiness), ('max_speechiness', max_speechiness), ('target_speechiness', target_speechiness), ('min_tempo', min_tempo), ('max_tempo', max_tempo), ('target_tempo', target_tempo), ('min_time_signature', min_time_signature), ('max_time_signature', max_time_signature), ('target_time_signature', target_time_signature), ('min_valence', min_valence), ('max_valence', max_valence), ('target_valence', target_valence)] if v is not None}
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(self, ) -> Any:
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(self, market=None, additional_types=None) -> Any:
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 = {k: v for k, v in [('market', market), ('additional_types', additional_types)] if v is not None}
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
- 'device_ids': device_ids,
1750
- 'play': play,
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(self, ) -> Any:
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(self, market=None, additional_types=None) -> Any:
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 = {k: v for k, v in [('market', market), ('additional_types', additional_types)] if v is not None}
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(self, device_id=None, context_uri=None, uris=None, offset=None, position_ms=None) -> Any:
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
- 'context_uri': context_uri,
1826
- 'uris': uris,
1827
- 'offset': offset,
1828
- 'position_ms': position_ms,
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 [('device_id', device_id)] if v is not None}
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 [('device_id', device_id)] if v is not None}
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 [('device_id', device_id)] if v is not None}
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 [('device_id', device_id)] if v is not None}
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(self, position_ms, device_id=None) -> Any:
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 = {k: v for k, v in [('position_ms', position_ms), ('device_id', device_id)] if v is not None}
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 = {k: v for k, v in [('state', state), ('device_id', device_id)] if v is not None}
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 = {k: v for k, v in [('volume_percent', volume_percent), ('device_id', device_id)] if v is not None}
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 = {k: v for k, v in [('state', state), ('device_id', device_id)] if v is not None}
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 = {k: v for k, v in [('limit', limit), ('after', after), ('before', before)] if v is not None}
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(self, ) -> Any:
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 = {k: v for k, v in [('uri', uri), ('device_id', device_id)] if v is not None}
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(self, ) -> Any:
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 = {k: v for k, v in [('time_range', time_range), ('limit', limit), ('offset', offset)] if v is not None}
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 = {k: v for k, v in [('time_range', time_range), ('limit', limit), ('offset', offset)] if v is not None}
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
  ]