omnipython-applibs 0.1.2__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 (143) hide show
  1. appkit/__init__.py +52 -0
  2. appkit/__init__.pyi +17 -0
  3. appkit/data.py +149 -0
  4. appkit/data.pyi +25 -0
  5. appkit/foreground.py +357 -0
  6. appkit/foreground.pyi +45 -0
  7. appkit/home.py +19 -0
  8. appkit/home.pyi +8 -0
  9. appkit/hover.py +59 -0
  10. appkit/hover.pyi +13 -0
  11. appkit/index.py +199 -0
  12. appkit/index.pyi +30 -0
  13. appkit/launcher.py +1075 -0
  14. appkit/launcher.pyi +96 -0
  15. appkit/manifest.py +75 -0
  16. appkit/manifest.pyi +8 -0
  17. appkit/net.py +167 -0
  18. appkit/net.pyi +34 -0
  19. appkit/places.py +202 -0
  20. appkit/places.pyi +39 -0
  21. appkit/py.typed +0 -0
  22. appkit/scope.py +636 -0
  23. appkit/scope.pyi +110 -0
  24. appkit/shell.py +121 -0
  25. appkit/shell.pyi +32 -0
  26. appkit/worker.py +409 -0
  27. appkit/worker.pyi +83 -0
  28. controlkit/__init__.py +19 -0
  29. controlkit/__init__.pyi +10 -0
  30. controlkit/_draw.py +88 -0
  31. controlkit/_safe.py +29 -0
  32. controlkit/dotmatrix.py +101 -0
  33. controlkit/dotmatrix.pyi +23 -0
  34. controlkit/encoder.py +297 -0
  35. controlkit/encoder.pyi +55 -0
  36. controlkit/font5x7.py +22 -0
  37. controlkit/font5x7.pyi +11 -0
  38. controlkit/lamp_button.py +92 -0
  39. controlkit/lamp_button.pyi +40 -0
  40. controlkit/meter.py +86 -0
  41. controlkit/meter.pyi +30 -0
  42. controlkit/mock.py +116 -0
  43. controlkit/mock.pyi +35 -0
  44. controlkit/pad_grid.py +113 -0
  45. controlkit/pad_grid.pyi +41 -0
  46. controlkit/py.typed +0 -0
  47. controlkit/slider.py +185 -0
  48. controlkit/slider.pyi +49 -0
  49. controlkit/sprites.py +279 -0
  50. controlkit/sprites.pyi +22 -0
  51. controlkit/theme.py +120 -0
  52. controlkit/theme.pyi +15 -0
  53. deskkit/__init__.py +74 -0
  54. deskkit/__init__.pyi +18 -0
  55. deskkit/forecast.py +261 -0
  56. deskkit/forecast.pyi +40 -0
  57. deskkit/localtime.py +215 -0
  58. deskkit/localtime.pyi +33 -0
  59. deskkit/py.typed +0 -0
  60. deskkit/shell.py +113 -0
  61. deskkit/shell.pyi +33 -0
  62. omnipython_applibs-0.1.2.dist-info/METADATA +90 -0
  63. omnipython_applibs-0.1.2.dist-info/RECORD +143 -0
  64. omnipython_applibs-0.1.2.dist-info/WHEEL +5 -0
  65. omnipython_applibs-0.1.2.dist-info/licenses/LICENSE +21 -0
  66. omnipython_applibs-0.1.2.dist-info/top_level.txt +9 -0
  67. programkit/__init__.py +27 -0
  68. programkit/__init__.pyi +8 -0
  69. programkit/board.py +56 -0
  70. programkit/board.pyi +20 -0
  71. programkit/press.py +63 -0
  72. programkit/press.pyi +17 -0
  73. programkit/py.typed +0 -0
  74. programkit/rows.py +149 -0
  75. programkit/rows.pyi +34 -0
  76. sayso/__init__.py +109 -0
  77. sayso/__init__.pyi +124 -0
  78. sayso/auth.py +811 -0
  79. sayso/auth.pyi +102 -0
  80. sayso/client.py +1286 -0
  81. sayso/client.pyi +138 -0
  82. sayso/keepalive.py +371 -0
  83. sayso/keepalive.pyi +53 -0
  84. sayso/local.py +85 -0
  85. sayso/local.pyi +28 -0
  86. sayso/object_specs.py +706 -0
  87. sayso/object_specs.pyi +8 -0
  88. sayso/objects.py +411 -0
  89. sayso/objects.pyi +854 -0
  90. sayso/py.typed +0 -0
  91. sayso/schema_coverage.py +210 -0
  92. sayso/schema_coverage.pyi +13 -0
  93. sayso/transport.py +426 -0
  94. sayso/transport.pyi +47 -0
  95. songmodel/__init__.py +30 -0
  96. songmodel/__init__.pyi +9 -0
  97. songmodel/link.py +189 -0
  98. songmodel/link.pyi +53 -0
  99. songmodel/model.py +238 -0
  100. songmodel/model.pyi +40 -0
  101. songmodel/page.html +225 -0
  102. songmodel/page_data.py +236 -0
  103. songmodel/page_data.pyi +6 -0
  104. songmodel/py.typed +0 -0
  105. soundmodule/__init__.py +7 -0
  106. soundmodule/__init__.pyi +6 -0
  107. soundmodule/engine.py +1001 -0
  108. soundmodule/engine.pyi +196 -0
  109. soundmodule/names.py +298 -0
  110. soundmodule/names.pyi +30 -0
  111. soundmodule/pipes.py +105 -0
  112. soundmodule/pipes.pyi +31 -0
  113. soundmodule/py.typed +0 -0
  114. soundmodule/run.py +249 -0
  115. soundmodule/run.pyi +49 -0
  116. spectrum/__init__.py +72 -0
  117. spectrum/__init__.pyi +30 -0
  118. spectrum/analyzer.py +231 -0
  119. spectrum/analyzer.pyi +67 -0
  120. spectrum/fake_music.py +201 -0
  121. spectrum/fake_music.pyi +36 -0
  122. spectrum/pump_levels.py +126 -0
  123. spectrum/pump_levels.pyi +46 -0
  124. spectrum/py.typed +0 -0
  125. spectrum/spectrum_view.py +403 -0
  126. spectrum/spectrum_view.pyi +80 -0
  127. touchkit/__init__.py +4 -0
  128. touchkit/__init__.pyi +4 -0
  129. touchkit/cam.py +146 -0
  130. touchkit/cam.pyi +35 -0
  131. touchkit/clock.py +18 -0
  132. touchkit/clock.pyi +6 -0
  133. touchkit/ecp.py +134 -0
  134. touchkit/ecp.pyi +28 -0
  135. touchkit/net.py +347 -0
  136. touchkit/net.pyi +27 -0
  137. touchkit/py.typed +0 -0
  138. touchkit/settings.py +85 -0
  139. touchkit/settings.pyi +17 -0
  140. touchkit/shell.py +268 -0
  141. touchkit/shell.pyi +42 -0
  142. touchkit/ui.py +167 -0
  143. touchkit/ui.pyi +53 -0
sayso/client.py ADDED
@@ -0,0 +1,1286 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ from .auth import ClientCredentialsAuth
6
+ from .objects import (
7
+ Album,
8
+ AlbumPage,
9
+ Artist,
10
+ ArtistCursorPage,
11
+ ArtistPage,
12
+ AudioAnalysis,
13
+ AudioFeatures,
14
+ Audiobook,
15
+ AudiobookPage,
16
+ Category,
17
+ CategoryPage,
18
+ Chapter,
19
+ ChapterPage,
20
+ CurrentlyPlaying,
21
+ Device,
22
+ Episode,
23
+ EpisodePage,
24
+ FeaturedPlaylists,
25
+ Image,
26
+ Playlist,
27
+ PlaylistPage,
28
+ PlaylistTrackPage,
29
+ PlayHistoryCursorPage,
30
+ PrivateUser,
31
+ Queue,
32
+ Recommendations,
33
+ SavedAlbumPage,
34
+ SavedEpisodePage,
35
+ SavedShowPage,
36
+ SavedTrackPage,
37
+ SearchResults,
38
+ Show,
39
+ SnapshotResult,
40
+ TrackPage,
41
+ Track,
42
+ User,
43
+ set_client,
44
+ )
45
+ from .transport import (
46
+ API_BASE_URL,
47
+ TransportError,
48
+ build_url,
49
+ delete_json,
50
+ get_json,
51
+ post_json,
52
+ put_body,
53
+ put_json,
54
+ )
55
+ from .local import EarfulAdapter, discover as discover_local
56
+
57
+ # The most IDs or URIs one request takes, by client method, from the parameter
58
+ # descriptions in Spotify's Web API reference
59
+ # (https://developer.spotify.com/documentation/web-api/reference).
60
+ _MOST = {
61
+ "tracks": 50,
62
+ "albums": 20,
63
+ "artists": 50,
64
+ "episodes": 50,
65
+ "shows": 50,
66
+ "audiobooks": 50,
67
+ "chapters": 50,
68
+ "audio_features_many": 100,
69
+ "add_playlist_items": 100,
70
+ "add_playlist_tracks": 100,
71
+ "remove_playlist_items": 100,
72
+ "remove_playlist_tracks": 100,
73
+ "replace_playlist_items": 100,
74
+ "replace_playlist_tracks": 100,
75
+ "contains_saved_albums": 20,
76
+ "save_albums": 50,
77
+ "remove_saved_albums": 50,
78
+ "contains_saved_tracks": 50,
79
+ "save_tracks": 50,
80
+ "remove_saved_tracks": 50,
81
+ "contains_saved_episodes": 50,
82
+ "save_episodes": 50,
83
+ "remove_saved_episodes": 50,
84
+ "contains_saved_shows": 50,
85
+ "save_shows": 50,
86
+ "remove_saved_shows": 50,
87
+ "contains_saved_audiobooks": 50,
88
+ "save_audiobooks": 50,
89
+ "remove_saved_audiobooks": 50,
90
+ "library_contains": 40,
91
+ "save_library_items": 40,
92
+ "remove_library_items": 40,
93
+ "follows_artists": 50,
94
+ "follows_users": 50,
95
+ "follow_artists": 50,
96
+ "follow_users": 50,
97
+ "unfollow_artists": 50,
98
+ "unfollow_users": 50,
99
+ }
100
+
101
+ # The most seeds `recommendations` takes, artists, genres and tracks together.
102
+ _MOST_SEEDS = 5
103
+
104
+ # The largest playlist cover Spotify accepts, as Base64 text.
105
+ _MOST_COVER_BYTES = 256 * 1024
106
+
107
+ # Client methods whose endpoint Spotify removed for Development Mode apps, with
108
+ # the method to use instead, or None where there is none. From the February 2026
109
+ # migration guide
110
+ # (https://developer.spotify.com/documentation/web-api/tutorials/february-2026-migration-guide).
111
+ # Apps in Extended Quota Mode still have every one of them.
112
+ _REMOVED_ENDPOINTS = {
113
+ "tracks": ("GET /tracks", "track"),
114
+ "albums": ("GET /albums", "album"),
115
+ "artists": ("GET /artists", "artist"),
116
+ "episodes": ("GET /episodes", "episode"),
117
+ "shows": ("GET /shows", "show"),
118
+ "audiobooks": ("GET /audiobooks", "audiobook"),
119
+ "chapters": ("GET /chapters", "chapter"),
120
+ "artist_top_tracks": ("GET /artists/{id}/top-tracks", None),
121
+ "create_playlist": ("POST /users/{user_id}/playlists", "create_current_user_playlist"),
122
+ "playlist_tracks": ("GET /playlists/{playlist_id}/tracks", "playlist_items"),
123
+ "add_playlist_tracks": ("POST /playlists/{playlist_id}/tracks", "add_playlist_items"),
124
+ "remove_playlist_tracks": ("DELETE /playlists/{playlist_id}/tracks", "remove_playlist_items"),
125
+ "replace_playlist_tracks": ("PUT /playlists/{playlist_id}/tracks", "replace_playlist_items"),
126
+ "reorder_playlist_tracks": ("PUT /playlists/{playlist_id}/tracks", "reorder_playlist_items"),
127
+ "follow_playlist": ("PUT /playlists/{playlist_id}/followers", "save_library_items"),
128
+ "unfollow_playlist": ("DELETE /playlists/{playlist_id}/followers", "remove_library_items"),
129
+ "playlist_followers_contains": ("GET /playlists/{playlist_id}/followers/contains", "library_contains"),
130
+ "category": ("GET /browse/categories/{category_id}", None),
131
+ "categories": ("GET /browse/categories", None),
132
+ "new_releases": ("GET /browse/new-releases", None),
133
+ "user": ("GET /users/{user_id}", "me"),
134
+ "user_playlists": ("GET /users/{user_id}/playlists", "current_user_playlists"),
135
+ "contains_saved_albums": ("GET /me/albums/contains", "library_contains"),
136
+ "save_albums": ("PUT /me/albums", "save_library_items"),
137
+ "remove_saved_albums": ("DELETE /me/albums", "remove_library_items"),
138
+ "contains_saved_tracks": ("GET /me/tracks/contains", "library_contains"),
139
+ "save_tracks": ("PUT /me/tracks", "save_library_items"),
140
+ "remove_saved_tracks": ("DELETE /me/tracks", "remove_library_items"),
141
+ "contains_saved_episodes": ("GET /me/episodes/contains", "library_contains"),
142
+ "save_episodes": ("PUT /me/episodes", "save_library_items"),
143
+ "remove_saved_episodes": ("DELETE /me/episodes", "remove_library_items"),
144
+ "contains_saved_shows": ("GET /me/shows/contains", "library_contains"),
145
+ "save_shows": ("PUT /me/shows", "save_library_items"),
146
+ "remove_saved_shows": ("DELETE /me/shows", "remove_library_items"),
147
+ "contains_saved_audiobooks": ("GET /me/audiobooks/contains", "library_contains"),
148
+ "save_audiobooks": ("PUT /me/audiobooks", "save_library_items"),
149
+ "remove_saved_audiobooks": ("DELETE /me/audiobooks", "remove_library_items"),
150
+ "follows_artists": ("GET /me/following/contains", "library_contains"),
151
+ "follow_artists": ("PUT /me/following", "save_library_items"),
152
+ "unfollow_artists": ("DELETE /me/following", "remove_library_items"),
153
+ "follows_users": ("GET /me/following/contains", "library_contains"),
154
+ "follow_users": ("PUT /me/following", "save_library_items"),
155
+ "unfollow_users": ("DELETE /me/following", "remove_library_items"),
156
+ "available_markets": ("GET /markets", None),
157
+ }
158
+
159
+
160
+ class SpotifyClientError(Exception):
161
+ pass
162
+
163
+
164
+ class SpotifyClient:
165
+ API_BASE_URL = API_BASE_URL
166
+
167
+ def __init__(
168
+ self,
169
+ access_token=None,
170
+ client_id=None,
171
+ client_secret=None,
172
+ auth=None,
173
+ auto_set=True,
174
+ config_path=None,
175
+ scope=None,
176
+ authenticate_if_needed=True,
177
+ auth_state="sayso",
178
+ local_device=None,
179
+ ):
180
+ self.access_token = access_token
181
+ self.auth = auth
182
+ self.local = local_device if isinstance(local_device, EarfulAdapter) else (
183
+ EarfulAdapter(local_device) if local_device is not None else discover_local()
184
+ )
185
+
186
+ if self.auth is None and access_token is None:
187
+ if client_id is not None and client_secret is not None:
188
+ self.auth = ClientCredentialsAuth(client_id, client_secret)
189
+ else:
190
+ from .auth import auth_from_config
191
+
192
+ self.auth = auth_from_config(
193
+ config_path=config_path,
194
+ scope=scope,
195
+ authenticate_if_needed=authenticate_if_needed,
196
+ auth_state=auth_state,
197
+ )
198
+
199
+ if auto_set:
200
+ set_client(self)
201
+
202
+ def _get_json(self, path, query=None):
203
+ def request(token):
204
+ return get_json(path, access_token=token, query=query)
205
+
206
+ return self._request_with_retry(request)
207
+
208
+ def _put_json(self, path, data=None, query=None):
209
+ return self._request_json(put_json, path, data=data, query=query)
210
+
211
+ def _put_body(self, path, body, content_type, query=None):
212
+ def request(token):
213
+ return put_body(path, body, content_type, access_token=token, query=query)
214
+
215
+ return self._request_with_retry(request)
216
+
217
+ def _post_json(self, path, data=None, query=None):
218
+ return self._request_json(post_json, path, data=data, query=query)
219
+
220
+ def _delete_json(self, path, data=None, query=None):
221
+ return self._request_json(delete_json, path, data=data, query=query)
222
+
223
+ def _url(self, path, query=None):
224
+ return build_url(path, query=query, base_url=self.API_BASE_URL)
225
+
226
+ def _request_json(self, request, path, data=None, query=None):
227
+ def do_request(token):
228
+ return request(path, data=data, access_token=token, query=query)
229
+
230
+ return self._request_with_retry(do_request)
231
+
232
+ def _request_with_retry(self, request):
233
+ token = self._access_token()
234
+ if token is None:
235
+ raise SpotifyClientError("An access_token is required for Spotify Web API requests")
236
+
237
+ try:
238
+ return request(token)
239
+ except TransportError as error:
240
+ if error.status != 401 or self.auth is None:
241
+ raise
242
+
243
+ self.auth.refresh()
244
+ if self.access_token is not None and self.auth.access_token is not None:
245
+ self.access_token = self.auth.access_token
246
+
247
+ token = self._access_token()
248
+ if token is None:
249
+ raise SpotifyClientError("An access_token is required for Spotify Web API requests")
250
+
251
+ return request(token)
252
+
253
+ def _access_token(self):
254
+ if self.access_token is not None:
255
+ return self.access_token
256
+ if self.auth is not None:
257
+ return self.auth.token()
258
+ return None
259
+
260
+ def _local(self, device_id=None):
261
+ if self.local is None:
262
+ return None
263
+ if device_id is None or device_id == self.local.device_id or device_id == self.local.name:
264
+ return self.local
265
+ return None
266
+
267
+ def _one(self, cls, path, query=None):
268
+ return cls(self._get_json(path, query=query))
269
+
270
+ def _many(self, cls, field, path, ids, query=None):
271
+ query = self._query_with_ids(ids, query=query)
272
+ data = self._get_json(path, query=query)
273
+ values = data.get(field, ())
274
+ return [cls(item) for item in values]
275
+
276
+ def _page(self, cls, path, query=None):
277
+ return cls(self._get_json(path, query=query))
278
+
279
+ def _page_url(self, page_url, page_class):
280
+ if page_url is None:
281
+ return None
282
+ return page_class(self._get_json(page_url))
283
+
284
+ def next_page(self, page):
285
+ return self._page_url(page.next, page.__class__)
286
+
287
+ def previous_page(self, page):
288
+ return self._page_url(page.previous, page.__class__)
289
+
290
+ def _path_id(self, value):
291
+ return str(value)
292
+
293
+ def _most(self, method, values):
294
+ """`values`, as a string or a list, once it fits what `method` takes in one request."""
295
+ if isinstance(values, str):
296
+ count = values.count(",") + 1
297
+ else:
298
+ values = list(values)
299
+ count = len(values)
300
+ most = _MOST[method]
301
+ if count > most:
302
+ raise ValueError("%s() takes at most %d items in one request, and got %d" % (method, most, count))
303
+ return values
304
+
305
+ def _limit(self, limit, most=50):
306
+ """A page `limit`, once it is within what Spotify's Web API reference allows."""
307
+ if isinstance(limit, int) and not 0 <= limit <= most:
308
+ raise ValueError("limit must be from 0 to %d, and got %d" % (most, limit))
309
+ return limit
310
+
311
+ def track(self, object_id, market=None):
312
+ return self._one(Track, "/tracks/" + self._path_id(object_id), self._market_query(market))
313
+
314
+ def tracks(self, ids, market=None):
315
+ """Several tracks by ID.
316
+
317
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
318
+ reference. More raises `ValueError` before anything is sent.
319
+
320
+ Removed for Development Mode apps by Spotify's February 2026 changes
321
+ (`GET /tracks`): use `track`, once per ID.
322
+ """
323
+ return self._many(Track, "tracks", "/tracks", self._most("tracks", ids), self._market_query(market))
324
+
325
+ def album(self, object_id, market=None):
326
+ return self._one(Album, "/albums/" + self._path_id(object_id), self._market_query(market))
327
+
328
+ def albums(self, ids, market=None):
329
+ """Several albums by ID.
330
+
331
+ Takes at most 20 IDs in one request, the maximum in Spotify's Web API
332
+ reference. More raises `ValueError` before anything is sent.
333
+
334
+ Removed for Development Mode apps by Spotify's February 2026 changes
335
+ (`GET /albums`): use `album`, once per ID.
336
+ """
337
+ return self._many(Album, "albums", "/albums", self._most("albums", ids), self._market_query(market))
338
+
339
+ def album_tracks(self, object_id, market=None, limit=None, offset=None):
340
+ query = self._page_query(market=market, limit=limit, offset=offset)
341
+ return self._page(TrackPage, "/albums/" + self._path_id(object_id) + "/tracks", query)
342
+
343
+ def artist(self, object_id):
344
+ return self._one(Artist, "/artists/" + self._path_id(object_id))
345
+
346
+ def artists(self, ids):
347
+ """Several artists by ID.
348
+
349
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
350
+ reference. More raises `ValueError` before anything is sent.
351
+
352
+ Removed for Development Mode apps by Spotify's February 2026 changes
353
+ (`GET /artists`): use `artist`, once per ID.
354
+ """
355
+ return self._many(Artist, "artists", "/artists", self._most("artists", ids))
356
+
357
+ def artist_albums(self, object_id, include_groups=None, market=None, limit=None, offset=None):
358
+ query = self._page_query(market=market, limit=limit, offset=offset)
359
+ self._add_query(query, "include_groups", include_groups)
360
+ return self._page(AlbumPage, "/artists/" + self._path_id(object_id) + "/albums", query)
361
+
362
+ def artist_top_tracks(self, object_id, market=None):
363
+ """An artist's top tracks.
364
+
365
+ Removed for Development Mode apps by Spotify's February 2026 changes
366
+ (`GET /artists/{id}/top-tracks`), with no replacement.
367
+ """
368
+ data = self._get_json("/artists/" + self._path_id(object_id) + "/top-tracks", self._market_query(market))
369
+ tracks = data.get("tracks")
370
+ if tracks is None:
371
+ return ()
372
+ return [Track(item) for item in tracks]
373
+
374
+ def artist_related_artists(self, object_id):
375
+ data = self._get_json("/artists/" + self._path_id(object_id) + "/related-artists")
376
+ artists = data.get("artists")
377
+ if artists is None:
378
+ return ()
379
+ return [Artist(item) for item in artists]
380
+
381
+ def playlist(self, object_id, market=None, fields=None, additional_types=None):
382
+ query = {}
383
+ self._add_query(query, "market", market)
384
+ self._add_query(query, "fields", fields)
385
+ self._add_query(query, "additional_types", additional_types)
386
+ return self._one(Playlist, "/playlists/" + self._path_id(object_id), query)
387
+
388
+ def create_playlist(self, user_id, name, public=None, collaborative=None, description=None):
389
+ """Create a playlist for a user, by user ID.
390
+
391
+ Removed for Development Mode apps by Spotify's February 2026 changes
392
+ (`POST /users/{user_id}/playlists`): use `create_current_user_playlist`.
393
+ """
394
+ data = {"name": name}
395
+ self._add_query(data, "public", public)
396
+ self._add_query(data, "collaborative", collaborative)
397
+ self._add_query(data, "description", description)
398
+ return Playlist(self._post_json("/users/" + self._path_id(user_id) + "/playlists", data=data))
399
+
400
+ def create_current_user_playlist(self, name, public=None, collaborative=None, description=None):
401
+ data = {"name": name}
402
+ self._add_query(data, "public", public)
403
+ self._add_query(data, "collaborative", collaborative)
404
+ self._add_query(data, "description", description)
405
+ return Playlist(self._post_json("/me/playlists", data=data))
406
+
407
+ def update_playlist_details(self, object_id, name=None, public=None, collaborative=None, description=None):
408
+ data = {}
409
+ self._add_query(data, "name", name)
410
+ self._add_query(data, "public", public)
411
+ self._add_query(data, "collaborative", collaborative)
412
+ self._add_query(data, "description", description)
413
+ return self._put_json("/playlists/" + self._path_id(object_id), data=data)
414
+
415
+ def playlist_items(self, object_id, market=None, fields=None, limit=None, offset=None, additional_types=None):
416
+ query = self._page_query(market=market, limit=limit, offset=offset)
417
+ self._add_query(query, "fields", fields)
418
+ self._add_query(query, "additional_types", additional_types)
419
+ return self._page(PlaylistTrackPage, "/playlists/" + self._path_id(object_id) + "/items", query)
420
+
421
+ def playlist_tracks(self, object_id, market=None, fields=None, limit=None, offset=None, additional_types=None):
422
+ """A page of a playlist's entries, from the old `/tracks` path.
423
+
424
+ Removed for Development Mode apps by Spotify's February 2026 changes
425
+ (`GET /playlists/{playlist_id}/tracks`): use `playlist_items`.
426
+ """
427
+ query = self._page_query(market=market, limit=limit, offset=offset)
428
+ self._add_query(query, "fields", fields)
429
+ self._add_query(query, "additional_types", additional_types)
430
+ return self._page(PlaylistTrackPage, "/playlists/" + self._path_id(object_id) + "/tracks", query)
431
+
432
+ def add_playlist_items(self, object_id, uris, position=None):
433
+ """Add tracks or episodes to a playlist.
434
+
435
+ Takes at most 100 URIs in one request, the maximum in Spotify's Web API
436
+ reference. More raises `ValueError` before anything is sent.
437
+ """
438
+ data = {"uris": self._uri_list(self._most("add_playlist_items", uris))}
439
+ self._add_query(data, "position", position)
440
+ return self._snapshot(self._post_json("/playlists/" + self._path_id(object_id) + "/items", data=data))
441
+
442
+ def add_playlist_tracks(self, object_id, uris, position=None):
443
+ """Add tracks or episodes to a playlist, through the old `/tracks` path.
444
+
445
+ Takes at most 100 URIs in one request, the maximum in Spotify's Web API
446
+ reference. More raises `ValueError` before anything is sent.
447
+
448
+ Removed for Development Mode apps by Spotify's February 2026 changes
449
+ (`POST /playlists/{playlist_id}/tracks`): use `add_playlist_items`.
450
+ """
451
+ data = {"uris": self._uri_list(self._most("add_playlist_tracks", uris))}
452
+ self._add_query(data, "position", position)
453
+ return self._snapshot(self._post_json("/playlists/" + self._path_id(object_id) + "/tracks", data=data))
454
+
455
+ def remove_playlist_items(self, object_id, uris, snapshot_id=None):
456
+ """Remove tracks or episodes from a playlist.
457
+
458
+ Takes at most 100 URIs in one request, the maximum in Spotify's Web API
459
+ reference. More raises `ValueError` before anything is sent.
460
+ """
461
+ data = {
462
+ "items": [{"uri": uri} for uri in self._uri_list(self._most("remove_playlist_items", uris))],
463
+ }
464
+ self._add_query(data, "snapshot_id", snapshot_id)
465
+ return self._snapshot(self._delete_json("/playlists/" + self._path_id(object_id) + "/items", data=data))
466
+
467
+ def remove_playlist_tracks(self, object_id, uris, snapshot_id=None):
468
+ """Remove tracks or episodes from a playlist, through the old `/tracks` path.
469
+
470
+ Takes at most 100 URIs in one request, the maximum in Spotify's Web API
471
+ reference. More raises `ValueError` before anything is sent.
472
+
473
+ Removed for Development Mode apps by Spotify's February 2026 changes
474
+ (`DELETE /playlists/{playlist_id}/tracks`): use `remove_playlist_items`.
475
+ """
476
+ data = {
477
+ "tracks": [{"uri": uri} for uri in self._uri_list(self._most("remove_playlist_tracks", uris))],
478
+ }
479
+ self._add_query(data, "snapshot_id", snapshot_id)
480
+ return self._snapshot(self._delete_json("/playlists/" + self._path_id(object_id) + "/tracks", data=data))
481
+
482
+ def replace_playlist_items(self, object_id, uris):
483
+ """Replace everything in a playlist.
484
+
485
+ Takes at most 100 URIs in one request, the maximum in Spotify's Web API
486
+ reference. More raises `ValueError` before anything is sent.
487
+ """
488
+ return self._snapshot(
489
+ self._put_json(
490
+ "/playlists/" + self._path_id(object_id) + "/items",
491
+ data={"uris": self._uri_list(self._most("replace_playlist_items", uris))},
492
+ )
493
+ )
494
+
495
+ def replace_playlist_tracks(self, object_id, uris):
496
+ """Replace everything in a playlist, through the old `/tracks` path.
497
+
498
+ Takes at most 100 URIs in one request, the maximum in Spotify's Web API
499
+ reference. More raises `ValueError` before anything is sent.
500
+
501
+ Removed for Development Mode apps by Spotify's February 2026 changes
502
+ (`PUT /playlists/{playlist_id}/tracks`): use `replace_playlist_items`.
503
+ """
504
+ return self._snapshot(
505
+ self._put_json(
506
+ "/playlists/" + self._path_id(object_id) + "/tracks",
507
+ data={"uris": self._uri_list(self._most("replace_playlist_tracks", uris))},
508
+ )
509
+ )
510
+
511
+ def reorder_playlist_items(self, object_id, range_start, insert_before, range_length=None, snapshot_id=None):
512
+ data = {
513
+ "range_start": range_start,
514
+ "insert_before": insert_before,
515
+ }
516
+ self._add_query(data, "range_length", range_length)
517
+ self._add_query(data, "snapshot_id", snapshot_id)
518
+ return self._snapshot(self._put_json("/playlists/" + self._path_id(object_id) + "/items", data=data))
519
+
520
+ def reorder_playlist_tracks(self, object_id, range_start, insert_before, range_length=None, snapshot_id=None):
521
+ """Move a run of a playlist's entries, through the old `/tracks` path.
522
+
523
+ Removed for Development Mode apps by Spotify's February 2026 changes
524
+ (`PUT /playlists/{playlist_id}/tracks`): use `reorder_playlist_items`.
525
+ """
526
+ data = {
527
+ "range_start": range_start,
528
+ "insert_before": insert_before,
529
+ }
530
+ self._add_query(data, "range_length", range_length)
531
+ self._add_query(data, "snapshot_id", snapshot_id)
532
+ return self._snapshot(self._put_json("/playlists/" + self._path_id(object_id) + "/tracks", data=data))
533
+
534
+ def follow_playlist(self, object_id, public=None):
535
+ """Follow a playlist.
536
+
537
+ Removed for Development Mode apps by Spotify's February 2026 changes
538
+ (`PUT /playlists/{playlist_id}/followers`): use `save_library_items`.
539
+ """
540
+ data = {}
541
+ self._add_query(data, "public", public)
542
+ return self._put_json("/playlists/" + self._path_id(object_id) + "/followers", data=data)
543
+
544
+ def unfollow_playlist(self, object_id):
545
+ """Stop following a playlist.
546
+
547
+ Removed for Development Mode apps by Spotify's February 2026 changes
548
+ (`DELETE /playlists/{playlist_id}/followers`): use `remove_library_items`.
549
+ """
550
+ return self._delete_json("/playlists/" + self._path_id(object_id) + "/followers")
551
+
552
+ def playlist_followers_contains(self, object_id, ids):
553
+ """Whether each user follows a playlist.
554
+
555
+ Removed for Development Mode apps by Spotify's February 2026 changes
556
+ (`GET /playlists/{playlist_id}/followers/contains`): use `library_contains`.
557
+ """
558
+ return self._bools("/playlists/" + self._path_id(object_id) + "/followers/contains", ids)
559
+
560
+ def episode(self, object_id, market=None):
561
+ return self._one(Episode, "/episodes/" + self._path_id(object_id), self._market_query(market))
562
+
563
+ def episodes(self, ids, market=None):
564
+ """Several episodes by ID.
565
+
566
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
567
+ reference. More raises `ValueError` before anything is sent.
568
+
569
+ Removed for Development Mode apps by Spotify's February 2026 changes
570
+ (`GET /episodes`): use `episode`, once per ID.
571
+ """
572
+ return self._many(Episode, "episodes", "/episodes", self._most("episodes", ids), self._market_query(market))
573
+
574
+ def show(self, object_id, market=None):
575
+ return self._one(Show, "/shows/" + self._path_id(object_id), self._market_query(market))
576
+
577
+ def shows(self, ids, market=None):
578
+ """Several shows by ID.
579
+
580
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
581
+ reference. More raises `ValueError` before anything is sent.
582
+
583
+ Removed for Development Mode apps by Spotify's February 2026 changes
584
+ (`GET /shows`): use `show`, once per ID.
585
+ """
586
+ return self._many(Show, "shows", "/shows", self._most("shows", ids), self._market_query(market))
587
+
588
+ def show_episodes(self, object_id, market=None, limit=None, offset=None):
589
+ query = self._page_query(market=market, limit=limit, offset=offset)
590
+ return self._page(EpisodePage, "/shows/" + self._path_id(object_id) + "/episodes", query)
591
+
592
+ def audiobook(self, object_id, market=None):
593
+ return self._one(Audiobook, "/audiobooks/" + self._path_id(object_id), self._market_query(market))
594
+
595
+ def audiobooks(self, ids, market=None):
596
+ """Several audiobooks by ID.
597
+
598
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
599
+ reference. More raises `ValueError` before anything is sent.
600
+
601
+ Removed for Development Mode apps by Spotify's February 2026 changes
602
+ (`GET /audiobooks`): use `audiobook`, once per ID.
603
+ """
604
+ return self._many(Audiobook, "audiobooks", "/audiobooks", self._most("audiobooks", ids), self._market_query(market))
605
+
606
+ def audiobook_chapters(self, object_id, market=None, limit=None, offset=None):
607
+ query = self._page_query(market=market, limit=limit, offset=offset)
608
+ return self._page(ChapterPage, "/audiobooks/" + self._path_id(object_id) + "/chapters", query)
609
+
610
+ def chapter(self, object_id, market=None):
611
+ return self._one(Chapter, "/chapters/" + self._path_id(object_id), self._market_query(market))
612
+
613
+ def chapters(self, ids, market=None):
614
+ """Several chapters by ID.
615
+
616
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
617
+ reference. More raises `ValueError` before anything is sent.
618
+
619
+ Removed for Development Mode apps by Spotify's February 2026 changes
620
+ (`GET /chapters`): use `chapter`, once per ID.
621
+ """
622
+ return self._many(Chapter, "chapters", "/chapters", self._most("chapters", ids), self._market_query(market))
623
+
624
+ def audio_features(self, object_id):
625
+ return self._one(AudioFeatures, "/audio-features/" + self._path_id(object_id))
626
+
627
+ def audio_features_many(self, ids):
628
+ """Audio features for several tracks.
629
+
630
+ Takes at most 100 IDs in one request, the maximum in Spotify's Web API
631
+ reference. More raises `ValueError` before anything is sent.
632
+ """
633
+ return self._many(AudioFeatures, "audio_features", "/audio-features", self._most("audio_features_many", ids))
634
+
635
+ def audio_analysis(self, object_id):
636
+ return self._one(AudioAnalysis, "/audio-analysis/" + self._path_id(object_id))
637
+
638
+ def recommendations(self, seed_artists=None, seed_genres=None, seed_tracks=None, limit=None, market=None, **kwargs):
639
+ """Tracks recommended from seed artists, genres and tracks.
640
+
641
+ Takes at most 5 seeds in one request, counting all three kinds together,
642
+ and a `limit` up to 100, the maximums in Spotify's Web API reference. More
643
+ raises `ValueError` before anything is sent.
644
+ """
645
+ seeds = [self._join_optional(seed_artists), self._join_optional(seed_genres), self._join_optional(seed_tracks)]
646
+ count = sum(seed.count(",") + 1 for seed in seeds if seed)
647
+ if count > _MOST_SEEDS:
648
+ raise ValueError("recommendations() takes at most %d seeds in one request, and got %d" % (_MOST_SEEDS, count))
649
+ query = {}
650
+ self._add_query(query, "seed_artists", seeds[0])
651
+ self._add_query(query, "seed_genres", seeds[1])
652
+ self._add_query(query, "seed_tracks", seeds[2])
653
+ self._add_query(query, "limit", self._limit(limit, 100))
654
+ self._add_query(query, "market", market)
655
+
656
+ for key in kwargs:
657
+ self._add_query(query, key, kwargs[key])
658
+
659
+ return self._one(Recommendations, "/recommendations", query)
660
+
661
+ def category(self, object_id, country=None, locale=None):
662
+ """One browse category.
663
+
664
+ Removed for Development Mode apps by Spotify's February 2026 changes
665
+ (`GET /browse/categories/{category_id}`), with no replacement.
666
+ """
667
+ query = {}
668
+ self._add_query(query, "country", country)
669
+ self._add_query(query, "locale", locale)
670
+ return self._one(Category, "/browse/categories/" + self._path_id(object_id), query)
671
+
672
+ def categories(self, country=None, locale=None, limit=None, offset=None):
673
+ """A page of browse categories.
674
+
675
+ Removed for Development Mode apps by Spotify's February 2026 changes
676
+ (`GET /browse/categories`), with no replacement.
677
+ """
678
+ query = self._page_query(limit=limit, offset=offset)
679
+ self._add_query(query, "country", country)
680
+ self._add_query(query, "locale", locale)
681
+ data = self._get_json("/browse/categories", query=query)
682
+ return CategoryPage(data.get("categories", data))
683
+
684
+ def category_playlists(self, category_id, limit=None, offset=None):
685
+ query = self._page_query(limit=limit, offset=offset)
686
+ data = self._get_json("/browse/categories/" + self._path_id(category_id) + "/playlists", query=query)
687
+ return PlaylistPage(data.get("playlists", data))
688
+
689
+ def featured_playlists(self, country=None, locale=None, timestamp=None, limit=None, offset=None):
690
+ query = self._page_query(limit=limit, offset=offset)
691
+ self._add_query(query, "country", country)
692
+ self._add_query(query, "locale", locale)
693
+ self._add_query(query, "timestamp", timestamp)
694
+ return self._one(FeaturedPlaylists, "/browse/featured-playlists", query)
695
+
696
+ def new_releases(self, country=None, limit=None, offset=None):
697
+ """A page of new album releases.
698
+
699
+ Removed for Development Mode apps by Spotify's February 2026 changes
700
+ (`GET /browse/new-releases`), with no replacement.
701
+ """
702
+ query = self._page_query(limit=limit, offset=offset)
703
+ self._add_query(query, "country", country)
704
+ data = self._get_json("/browse/new-releases", query=query)
705
+ return AlbumPage(data.get("albums", data))
706
+
707
+ def search(self, q, item_types, market=None, limit=None, offset=None, include_external=None):
708
+ """Search the catalogue for albums, artists, playlists, tracks, shows, episodes or audiobooks.
709
+
710
+ Spotify's February 2026 changes cut the largest `limit` from 50 to 10 for
711
+ Development Mode apps. Page with `offset` to read more.
712
+ """
713
+ query = self._page_query(market=market, limit=limit, offset=offset)
714
+ self._add_query(query, "q", q)
715
+ self._add_query(query, "type", self._join_ids(item_types))
716
+ self._add_query(query, "include_external", include_external)
717
+ return self._one(SearchResults, "/search", query)
718
+
719
+ def me(self):
720
+ return self._one(PrivateUser, "/me")
721
+
722
+ def user(self, object_id):
723
+ """Another user's public profile.
724
+
725
+ Removed for Development Mode apps by Spotify's February 2026 changes
726
+ (`GET /users/{user_id}`): use `me` for the current user.
727
+ """
728
+ return self._one(User, "/users/" + self._path_id(object_id))
729
+
730
+ def current_playback(self, market=None, additional_types=None):
731
+ query = {}
732
+ self._add_query(query, "market", market)
733
+ self._add_query(query, "additional_types", additional_types)
734
+ return self._one(CurrentlyPlaying, "/me/player", query)
735
+
736
+ def currently_playing(self, market=None, additional_types=None):
737
+ query = {}
738
+ self._add_query(query, "market", market)
739
+ self._add_query(query, "additional_types", additional_types)
740
+ return self._one(CurrentlyPlaying, "/me/player/currently-playing", query)
741
+
742
+ def queue(self):
743
+ return self._one(Queue, "/me/player/queue")
744
+
745
+ def transfer_playback(self, device_ids, play=None):
746
+ data = {"device_ids": self._string_list(device_ids)}
747
+ self._add_query(data, "play", play)
748
+ return self._put_json("/me/player", data=data)
749
+
750
+ def play(self, device_id=None, context_uri=None, uris=None, offset=None, position_ms=None):
751
+ local = self._local(device_id)
752
+ if local is not None:
753
+ return local.play(context_uri=context_uri, uris=uris, position_ms=position_ms)
754
+ data = {}
755
+ self._add_query(data, "context_uri", context_uri)
756
+ if uris is not None:
757
+ data["uris"] = self._uri_list(uris)
758
+ self._add_query(data, "offset", offset)
759
+ self._add_query(data, "position_ms", position_ms)
760
+ return self._put_json("/me/player/play", data=data, query=self._device_query(device_id))
761
+
762
+ def pause(self, device_id=None):
763
+ local = self._local(device_id)
764
+ if local is not None:
765
+ return local.pause()
766
+ return self._put_json("/me/player/pause", query=self._device_query(device_id))
767
+
768
+ def next_track(self, device_id=None):
769
+ local = self._local(device_id)
770
+ if local is not None:
771
+ return local.next()
772
+ return self._post_json("/me/player/next", query=self._device_query(device_id))
773
+
774
+ def previous_track(self, device_id=None):
775
+ local = self._local(device_id)
776
+ if local is not None:
777
+ return local.previous()
778
+ return self._post_json("/me/player/previous", query=self._device_query(device_id))
779
+
780
+ def seek(self, position_ms, device_id=None):
781
+ local = self._local(device_id)
782
+ if local is not None:
783
+ return local.seek(position_ms)
784
+ query = {"position_ms": position_ms}
785
+ self._add_query(query, "device_id", device_id)
786
+ return self._put_json("/me/player/seek", query=query)
787
+
788
+ def repeat(self, state, device_id=None):
789
+ query = {"state": state}
790
+ self._add_query(query, "device_id", device_id)
791
+ return self._put_json("/me/player/repeat", query=query)
792
+
793
+ def shuffle(self, state, device_id=None):
794
+ query = {"state": bool_string(state)}
795
+ self._add_query(query, "device_id", device_id)
796
+ return self._put_json("/me/player/shuffle", query=query)
797
+
798
+ def volume(self, volume_percent, device_id=None):
799
+ local = self._local(device_id)
800
+ if local is not None:
801
+ return local.set_volume(volume_percent)
802
+ query = {"volume_percent": volume_percent}
803
+ self._add_query(query, "device_id", device_id)
804
+ return self._put_json("/me/player/volume", query=query)
805
+
806
+ def add_to_queue(self, uri, device_id=None):
807
+ query = {"uri": self._uri(uri)}
808
+ self._add_query(query, "device_id", device_id)
809
+ return self._post_json("/me/player/queue", query=query)
810
+
811
+ def devices(self):
812
+ data = self._get_json("/me/player/devices")
813
+ devices = data.get("devices")
814
+ result = [] if devices is None else [Device(item) for item in devices]
815
+ if self.local is not None and self.local.device_id is not None:
816
+ local_state = self.local.state()
817
+ if not any(getattr(item, "id", None) == self.local.device_id for item in result):
818
+ result.append(Device(local_state))
819
+ return result
820
+
821
+ def recently_played(self, limit=None, after=None, before=None):
822
+ query = {}
823
+ self._add_query(query, "limit", self._limit(limit))
824
+ self._add_query(query, "after", after)
825
+ self._add_query(query, "before", before)
826
+ return self._page(PlayHistoryCursorPage, "/me/player/recently-played", query)
827
+
828
+ def current_user_playlists(self, limit=None, offset=None):
829
+ return self._page(PlaylistPage, "/me/playlists", self._page_query(limit=limit, offset=offset))
830
+
831
+ def user_playlists(self, object_id, limit=None, offset=None):
832
+ """A page of another user's playlists.
833
+
834
+ Removed for Development Mode apps by Spotify's February 2026 changes
835
+ (`GET /users/{user_id}/playlists`): use `current_user_playlists` for the current user.
836
+ """
837
+ return self._page(
838
+ PlaylistPage,
839
+ "/users/" + self._path_id(object_id) + "/playlists",
840
+ self._page_query(limit=limit, offset=offset),
841
+ )
842
+
843
+ def saved_albums(self, market=None, limit=None, offset=None):
844
+ return self._page(SavedAlbumPage, "/me/albums", self._page_query(market=market, limit=limit, offset=offset))
845
+
846
+ def saved_tracks(self, market=None, limit=None, offset=None):
847
+ return self._page(SavedTrackPage, "/me/tracks", self._page_query(market=market, limit=limit, offset=offset))
848
+
849
+ def saved_episodes(self, market=None, limit=None, offset=None):
850
+ return self._page(SavedEpisodePage, "/me/episodes", self._page_query(market=market, limit=limit, offset=offset))
851
+
852
+ def saved_shows(self, limit=None, offset=None):
853
+ return self._page(SavedShowPage, "/me/shows", self._page_query(limit=limit, offset=offset))
854
+
855
+ def saved_audiobooks(self, limit=None, offset=None):
856
+ return self._page(AudiobookPage, "/me/audiobooks", self._page_query(limit=limit, offset=offset))
857
+
858
+ def contains_saved_albums(self, ids):
859
+ """Whether each of these albums is in the current user's library.
860
+
861
+ Takes at most 20 IDs in one request, the maximum in Spotify's Web API
862
+ reference. More raises `ValueError` before anything is sent.
863
+
864
+ Removed for Development Mode apps by Spotify's February 2026 changes
865
+ (`GET /me/albums/contains`): use `library_contains`.
866
+ """
867
+ return self._bools("/me/albums/contains", self._most("contains_saved_albums", ids))
868
+
869
+ def save_albums(self, ids):
870
+ """Save albums to the current user's library.
871
+
872
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
873
+ reference. More raises `ValueError` before anything is sent.
874
+
875
+ Removed for Development Mode apps by Spotify's February 2026 changes
876
+ (`PUT /me/albums`): use `save_library_items`.
877
+ """
878
+ return self._put_ids("/me/albums", self._most("save_albums", ids))
879
+
880
+ def remove_saved_albums(self, ids):
881
+ """Remove albums from the current user's library.
882
+
883
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
884
+ reference. More raises `ValueError` before anything is sent.
885
+
886
+ Removed for Development Mode apps by Spotify's February 2026 changes
887
+ (`DELETE /me/albums`): use `remove_library_items`.
888
+ """
889
+ return self._delete_ids("/me/albums", self._most("remove_saved_albums", ids))
890
+
891
+ def contains_saved_tracks(self, ids):
892
+ """Whether each of these tracks is in the current user's library.
893
+
894
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
895
+ reference. More raises `ValueError` before anything is sent.
896
+
897
+ Removed for Development Mode apps by Spotify's February 2026 changes
898
+ (`GET /me/tracks/contains`): use `library_contains`.
899
+ """
900
+ return self._bools("/me/tracks/contains", self._most("contains_saved_tracks", ids))
901
+
902
+ def save_tracks(self, ids):
903
+ """Save tracks to the current user's library.
904
+
905
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
906
+ reference. More raises `ValueError` before anything is sent.
907
+
908
+ Removed for Development Mode apps by Spotify's February 2026 changes
909
+ (`PUT /me/tracks`): use `save_library_items`.
910
+ """
911
+ return self._put_ids("/me/tracks", self._most("save_tracks", ids))
912
+
913
+ def remove_saved_tracks(self, ids):
914
+ """Remove tracks from the current user's library.
915
+
916
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
917
+ reference. More raises `ValueError` before anything is sent.
918
+
919
+ Removed for Development Mode apps by Spotify's February 2026 changes
920
+ (`DELETE /me/tracks`): use `remove_library_items`.
921
+ """
922
+ return self._delete_ids("/me/tracks", self._most("remove_saved_tracks", ids))
923
+
924
+ def contains_saved_episodes(self, ids):
925
+ """Whether each of these episodes is in the current user's library.
926
+
927
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
928
+ reference. More raises `ValueError` before anything is sent.
929
+
930
+ Removed for Development Mode apps by Spotify's February 2026 changes
931
+ (`GET /me/episodes/contains`): use `library_contains`.
932
+ """
933
+ return self._bools("/me/episodes/contains", self._most("contains_saved_episodes", ids))
934
+
935
+ def save_episodes(self, ids):
936
+ """Save episodes to the current user's library.
937
+
938
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
939
+ reference. More raises `ValueError` before anything is sent.
940
+
941
+ Removed for Development Mode apps by Spotify's February 2026 changes
942
+ (`PUT /me/episodes`): use `save_library_items`.
943
+ """
944
+ return self._put_ids("/me/episodes", self._most("save_episodes", ids))
945
+
946
+ def remove_saved_episodes(self, ids):
947
+ """Remove episodes from the current user's library.
948
+
949
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
950
+ reference. More raises `ValueError` before anything is sent.
951
+
952
+ Removed for Development Mode apps by Spotify's February 2026 changes
953
+ (`DELETE /me/episodes`): use `remove_library_items`.
954
+ """
955
+ return self._delete_ids("/me/episodes", self._most("remove_saved_episodes", ids))
956
+
957
+ def contains_saved_shows(self, ids):
958
+ """Whether each of these shows is in the current user's library.
959
+
960
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
961
+ reference. More raises `ValueError` before anything is sent.
962
+
963
+ Removed for Development Mode apps by Spotify's February 2026 changes
964
+ (`GET /me/shows/contains`): use `library_contains`.
965
+ """
966
+ return self._bools("/me/shows/contains", self._most("contains_saved_shows", ids))
967
+
968
+ def save_shows(self, ids):
969
+ """Save shows to the current user's library.
970
+
971
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
972
+ reference. More raises `ValueError` before anything is sent.
973
+
974
+ Removed for Development Mode apps by Spotify's February 2026 changes
975
+ (`PUT /me/shows`): use `save_library_items`.
976
+ """
977
+ return self._put_ids("/me/shows", self._most("save_shows", ids))
978
+
979
+ def remove_saved_shows(self, ids):
980
+ """Remove shows from the current user's library.
981
+
982
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
983
+ reference. More raises `ValueError` before anything is sent.
984
+
985
+ Removed for Development Mode apps by Spotify's February 2026 changes
986
+ (`DELETE /me/shows`): use `remove_library_items`.
987
+ """
988
+ return self._delete_ids("/me/shows", self._most("remove_saved_shows", ids))
989
+
990
+ def contains_saved_audiobooks(self, ids):
991
+ """Whether each of these audiobooks is in the current user's library.
992
+
993
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
994
+ reference. More raises `ValueError` before anything is sent.
995
+
996
+ Removed for Development Mode apps by Spotify's February 2026 changes
997
+ (`GET /me/audiobooks/contains`): use `library_contains`.
998
+ """
999
+ return self._bools("/me/audiobooks/contains", self._most("contains_saved_audiobooks", ids))
1000
+
1001
+ def save_audiobooks(self, ids):
1002
+ """Save audiobooks to the current user's library.
1003
+
1004
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
1005
+ reference. More raises `ValueError` before anything is sent.
1006
+
1007
+ Removed for Development Mode apps by Spotify's February 2026 changes
1008
+ (`PUT /me/audiobooks`): use `save_library_items`.
1009
+ """
1010
+ return self._put_ids("/me/audiobooks", self._most("save_audiobooks", ids))
1011
+
1012
+ def remove_saved_audiobooks(self, ids):
1013
+ """Remove audiobooks from the current user's library.
1014
+
1015
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
1016
+ reference. More raises `ValueError` before anything is sent.
1017
+
1018
+ Removed for Development Mode apps by Spotify's February 2026 changes
1019
+ (`DELETE /me/audiobooks`): use `remove_library_items`.
1020
+ """
1021
+ return self._delete_ids("/me/audiobooks", self._most("remove_saved_audiobooks", ids))
1022
+
1023
+ def library_contains(self, uris):
1024
+ """Whether each URI is saved or followed by the current user.
1025
+
1026
+ Takes at most 40 URIs in one request, the maximum in Spotify's Web API
1027
+ reference. More raises `ValueError` before anything is sent.
1028
+ """
1029
+ return tuple(bool(value) for value in self._get_json("/me/library/contains", query=self._query_with_uris(self._most("library_contains", uris))))
1030
+
1031
+ def save_library_items(self, uris):
1032
+ """Save or follow anything that has a Spotify URI.
1033
+
1034
+ Takes at most 40 URIs in one request, the maximum in Spotify's Web API
1035
+ reference. More raises `ValueError` before anything is sent.
1036
+ """
1037
+ return self._put_json("/me/library", query=self._query_with_uris(self._most("save_library_items", uris)))
1038
+
1039
+ def remove_library_items(self, uris):
1040
+ """Remove or stop following anything that has a Spotify URI.
1041
+
1042
+ Takes at most 40 URIs in one request, the maximum in Spotify's Web API
1043
+ reference. More raises `ValueError` before anything is sent.
1044
+ """
1045
+ return self._delete_json("/me/library", query=self._query_with_uris(self._most("remove_library_items", uris)))
1046
+
1047
+ def followed_artists(self, after=None, limit=None):
1048
+ query = {"type": "artist"}
1049
+ self._add_query(query, "after", after)
1050
+ self._add_query(query, "limit", self._limit(limit))
1051
+ data = self._get_json("/me/following", query=query)
1052
+ return ArtistCursorPage(data.get("artists", data))
1053
+
1054
+ def follows_artists(self, ids):
1055
+ """Whether the current user follows each artist.
1056
+
1057
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
1058
+ reference. More raises `ValueError` before anything is sent.
1059
+
1060
+ Removed for Development Mode apps by Spotify's February 2026 changes
1061
+ (`GET /me/following/contains`): use `library_contains`.
1062
+ """
1063
+ return self._following_bools("artist", self._most("follows_artists", ids))
1064
+
1065
+ def follows_users(self, ids):
1066
+ """Whether the current user follows each user.
1067
+
1068
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
1069
+ reference. More raises `ValueError` before anything is sent.
1070
+
1071
+ Removed for Development Mode apps by Spotify's February 2026 changes
1072
+ (`GET /me/following/contains`): use `library_contains`.
1073
+ """
1074
+ return self._following_bools("user", self._most("follows_users", ids))
1075
+
1076
+ def follow_artists(self, ids):
1077
+ """Follow artists.
1078
+
1079
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
1080
+ reference. More raises `ValueError` before anything is sent.
1081
+
1082
+ Removed for Development Mode apps by Spotify's February 2026 changes
1083
+ (`PUT /me/following`): use `save_library_items`.
1084
+ """
1085
+ return self._follow("artist", self._most("follow_artists", ids))
1086
+
1087
+ def follow_users(self, ids):
1088
+ """Follow users.
1089
+
1090
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
1091
+ reference. More raises `ValueError` before anything is sent.
1092
+
1093
+ Removed for Development Mode apps by Spotify's February 2026 changes
1094
+ (`PUT /me/following`): use `save_library_items`.
1095
+ """
1096
+ return self._follow("user", self._most("follow_users", ids))
1097
+
1098
+ def unfollow_artists(self, ids):
1099
+ """Stop following artists.
1100
+
1101
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
1102
+ reference. More raises `ValueError` before anything is sent.
1103
+
1104
+ Removed for Development Mode apps by Spotify's February 2026 changes
1105
+ (`DELETE /me/following`): use `remove_library_items`.
1106
+ """
1107
+ return self._unfollow("artist", self._most("unfollow_artists", ids))
1108
+
1109
+ def unfollow_users(self, ids):
1110
+ """Stop following users.
1111
+
1112
+ Takes at most 50 IDs in one request, the maximum in Spotify's Web API
1113
+ reference. More raises `ValueError` before anything is sent.
1114
+
1115
+ Removed for Development Mode apps by Spotify's February 2026 changes
1116
+ (`DELETE /me/following`): use `remove_library_items`.
1117
+ """
1118
+ return self._unfollow("user", self._most("unfollow_users", ids))
1119
+
1120
+ def top_artists(self, time_range=None, limit=None, offset=None):
1121
+ query = self._page_query(limit=limit, offset=offset)
1122
+ self._add_query(query, "time_range", time_range)
1123
+ return self._page(ArtistPage, "/me/top/artists", query)
1124
+
1125
+ def top_tracks(self, time_range=None, limit=None, offset=None):
1126
+ query = self._page_query(limit=limit, offset=offset)
1127
+ self._add_query(query, "time_range", time_range)
1128
+ return self._page(TrackPage, "/me/top/tracks", query)
1129
+
1130
+ def playlist_cover_image(self, object_id):
1131
+ data = self._get_json("/playlists/" + self._path_id(object_id) + "/images")
1132
+ return [Image(item) for item in data]
1133
+
1134
+ def set_playlist_cover_image(self, object_id, base64_jpeg):
1135
+ """Upload a playlist's cover, a JPEG as Base64 text.
1136
+
1137
+ Takes at most 256 KB of Base64, the maximum in Spotify's Web API
1138
+ reference. More raises `ValueError` before anything is sent.
1139
+ """
1140
+ if len(base64_jpeg) > _MOST_COVER_BYTES:
1141
+ raise ValueError(
1142
+ "set_playlist_cover_image() takes at most %d bytes of Base64, and got %d"
1143
+ % (_MOST_COVER_BYTES, len(base64_jpeg))
1144
+ )
1145
+ return self._put_body(
1146
+ "/playlists/" + self._path_id(object_id) + "/images",
1147
+ base64_jpeg,
1148
+ "image/jpeg",
1149
+ )
1150
+
1151
+ def available_markets(self):
1152
+ """The markets where Spotify is available.
1153
+
1154
+ Removed for Development Mode apps by Spotify's February 2026 changes
1155
+ (`GET /markets`), with no replacement.
1156
+ """
1157
+ data = self._get_json("/markets")
1158
+ markets = data.get("markets")
1159
+ if markets is None:
1160
+ return ()
1161
+ return markets
1162
+
1163
+ def recommendation_genres(self):
1164
+ data = self._get_json("/recommendations/available-genre-seeds")
1165
+ genres = data.get("genres")
1166
+ if genres is None:
1167
+ return ()
1168
+ return genres
1169
+
1170
+ def _market_query(self, market):
1171
+ if market is None:
1172
+ return None
1173
+ return {"market": market}
1174
+
1175
+ def _page_query(self, market=None, limit=None, offset=None):
1176
+ query = {}
1177
+ self._add_query(query, "market", market)
1178
+ self._add_query(query, "limit", self._limit(limit))
1179
+ self._add_query(query, "offset", offset)
1180
+ return query
1181
+
1182
+ def _device_query(self, device_id):
1183
+ if device_id is None:
1184
+ return None
1185
+ return {"device_id": device_id}
1186
+
1187
+ def _query_with_ids(self, ids, query=None):
1188
+ if query is None:
1189
+ query = {}
1190
+ else:
1191
+ query = dict(query)
1192
+ query["ids"] = self._join_ids(ids)
1193
+ return query
1194
+
1195
+ def _query_with_uris(self, uris, query=None):
1196
+ if query is None:
1197
+ query = {}
1198
+ else:
1199
+ query = dict(query)
1200
+ query["uris"] = self._join_uris(uris)
1201
+ return query
1202
+
1203
+ def _bools(self, path, ids, query=None):
1204
+ return tuple(bool(value) for value in self._get_json(path, query=self._query_with_ids(ids, query=query)))
1205
+
1206
+ def _following_bools(self, item_type, ids):
1207
+ query = {"type": item_type}
1208
+ return self._bools("/me/following/contains", ids, query=query)
1209
+
1210
+ def _put_ids(self, path, ids):
1211
+ return self._put_json(path, data={"ids": self._id_list(ids)})
1212
+
1213
+ def _delete_ids(self, path, ids):
1214
+ return self._delete_json(path, data={"ids": self._id_list(ids)})
1215
+
1216
+ def _follow(self, item_type, ids):
1217
+ return self._put_json("/me/following", data={"ids": self._id_list(ids)}, query={"type": item_type})
1218
+
1219
+ def _unfollow(self, item_type, ids):
1220
+ return self._delete_json("/me/following", data={"ids": self._id_list(ids)}, query={"type": item_type})
1221
+
1222
+ def _snapshot(self, data):
1223
+ if data is None:
1224
+ return None
1225
+ return SnapshotResult(data)
1226
+
1227
+ def _id_list(self, ids):
1228
+ if isinstance(ids, str):
1229
+ return [ids]
1230
+ return [self._id(value) for value in ids]
1231
+
1232
+ def _id(self, value):
1233
+ object_id = getattr(value, "id", None)
1234
+ if object_id is not None:
1235
+ return object_id
1236
+ return str(value)
1237
+
1238
+ def _uri_list(self, values):
1239
+ if isinstance(values, str):
1240
+ return [values]
1241
+ return [self._uri(value) for value in values]
1242
+
1243
+ def _uri(self, value):
1244
+ uri = getattr(value, "uri", None)
1245
+ if uri is not None:
1246
+ return uri
1247
+ return str(value)
1248
+
1249
+ def _string_list(self, values):
1250
+ if isinstance(values, str):
1251
+ return [values]
1252
+ return [str(value) for value in values]
1253
+
1254
+ def _join_ids(self, ids):
1255
+ if isinstance(ids, str):
1256
+ return ids
1257
+ return ",".join(str(value) for value in ids)
1258
+
1259
+ def _join_uris(self, uris):
1260
+ if isinstance(uris, str):
1261
+ return uris
1262
+ return ",".join(self._uri(value) for value in uris)
1263
+
1264
+ def _join_optional(self, values):
1265
+ if values is None:
1266
+ return None
1267
+ return self._join_ids(values)
1268
+
1269
+ def _add_query(self, query, field, value):
1270
+ if value is not None:
1271
+ query[field] = value
1272
+
1273
+
1274
+ def bool_string(value):
1275
+ if value:
1276
+ return "true"
1277
+ return "false"
1278
+
1279
+
1280
+ def snapshot_id(result):
1281
+ if result is None:
1282
+ return None
1283
+ value = getattr(result, "snapshot_id", None)
1284
+ if value is not None:
1285
+ return value
1286
+ return result.get("snapshot_id")