omnipython-applibs 0.1.2.dev16__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.
- appkit/__init__.py +52 -0
- appkit/__init__.pyi +17 -0
- appkit/data.py +149 -0
- appkit/data.pyi +25 -0
- appkit/foreground.py +357 -0
- appkit/foreground.pyi +45 -0
- appkit/home.py +19 -0
- appkit/home.pyi +8 -0
- appkit/hover.py +59 -0
- appkit/hover.pyi +13 -0
- appkit/index.py +199 -0
- appkit/index.pyi +30 -0
- appkit/launcher.py +1075 -0
- appkit/launcher.pyi +96 -0
- appkit/manifest.py +75 -0
- appkit/manifest.pyi +8 -0
- appkit/net.py +167 -0
- appkit/net.pyi +34 -0
- appkit/places.py +202 -0
- appkit/places.pyi +39 -0
- appkit/py.typed +0 -0
- appkit/scope.py +636 -0
- appkit/scope.pyi +110 -0
- appkit/shell.py +121 -0
- appkit/shell.pyi +32 -0
- appkit/worker.py +409 -0
- appkit/worker.pyi +83 -0
- controlkit/__init__.py +19 -0
- controlkit/__init__.pyi +10 -0
- controlkit/_draw.py +88 -0
- controlkit/_safe.py +29 -0
- controlkit/dotmatrix.py +101 -0
- controlkit/dotmatrix.pyi +23 -0
- controlkit/encoder.py +297 -0
- controlkit/encoder.pyi +55 -0
- controlkit/font5x7.py +22 -0
- controlkit/font5x7.pyi +11 -0
- controlkit/lamp_button.py +92 -0
- controlkit/lamp_button.pyi +40 -0
- controlkit/meter.py +86 -0
- controlkit/meter.pyi +30 -0
- controlkit/mock.py +116 -0
- controlkit/mock.pyi +35 -0
- controlkit/pad_grid.py +113 -0
- controlkit/pad_grid.pyi +41 -0
- controlkit/py.typed +0 -0
- controlkit/slider.py +185 -0
- controlkit/slider.pyi +49 -0
- controlkit/sprites.py +279 -0
- controlkit/sprites.pyi +22 -0
- controlkit/theme.py +120 -0
- controlkit/theme.pyi +15 -0
- deskkit/__init__.py +74 -0
- deskkit/__init__.pyi +18 -0
- deskkit/forecast.py +261 -0
- deskkit/forecast.pyi +40 -0
- deskkit/localtime.py +215 -0
- deskkit/localtime.pyi +33 -0
- deskkit/py.typed +0 -0
- deskkit/shell.py +113 -0
- deskkit/shell.pyi +33 -0
- omnipython_applibs-0.1.2.dev16.dist-info/METADATA +90 -0
- omnipython_applibs-0.1.2.dev16.dist-info/RECORD +143 -0
- omnipython_applibs-0.1.2.dev16.dist-info/WHEEL +5 -0
- omnipython_applibs-0.1.2.dev16.dist-info/licenses/LICENSE +21 -0
- omnipython_applibs-0.1.2.dev16.dist-info/top_level.txt +9 -0
- programkit/__init__.py +27 -0
- programkit/__init__.pyi +8 -0
- programkit/board.py +56 -0
- programkit/board.pyi +20 -0
- programkit/press.py +63 -0
- programkit/press.pyi +17 -0
- programkit/py.typed +0 -0
- programkit/rows.py +149 -0
- programkit/rows.pyi +34 -0
- sayso/__init__.py +109 -0
- sayso/__init__.pyi +124 -0
- sayso/auth.py +811 -0
- sayso/auth.pyi +102 -0
- sayso/client.py +1286 -0
- sayso/client.pyi +138 -0
- sayso/keepalive.py +371 -0
- sayso/keepalive.pyi +53 -0
- sayso/local.py +85 -0
- sayso/local.pyi +28 -0
- sayso/object_specs.py +706 -0
- sayso/object_specs.pyi +8 -0
- sayso/objects.py +411 -0
- sayso/objects.pyi +854 -0
- sayso/py.typed +0 -0
- sayso/schema_coverage.py +210 -0
- sayso/schema_coverage.pyi +13 -0
- sayso/transport.py +426 -0
- sayso/transport.pyi +47 -0
- songmodel/__init__.py +30 -0
- songmodel/__init__.pyi +9 -0
- songmodel/link.py +189 -0
- songmodel/link.pyi +53 -0
- songmodel/model.py +238 -0
- songmodel/model.pyi +40 -0
- songmodel/page.html +225 -0
- songmodel/page_data.py +236 -0
- songmodel/page_data.pyi +6 -0
- songmodel/py.typed +0 -0
- soundmodule/__init__.py +7 -0
- soundmodule/__init__.pyi +6 -0
- soundmodule/engine.py +1001 -0
- soundmodule/engine.pyi +196 -0
- soundmodule/names.py +298 -0
- soundmodule/names.pyi +30 -0
- soundmodule/pipes.py +105 -0
- soundmodule/pipes.pyi +31 -0
- soundmodule/py.typed +0 -0
- soundmodule/run.py +249 -0
- soundmodule/run.pyi +49 -0
- spectrum/__init__.py +72 -0
- spectrum/__init__.pyi +30 -0
- spectrum/analyzer.py +231 -0
- spectrum/analyzer.pyi +67 -0
- spectrum/fake_music.py +201 -0
- spectrum/fake_music.pyi +36 -0
- spectrum/pump_levels.py +126 -0
- spectrum/pump_levels.pyi +46 -0
- spectrum/py.typed +0 -0
- spectrum/spectrum_view.py +403 -0
- spectrum/spectrum_view.pyi +80 -0
- touchkit/__init__.py +4 -0
- touchkit/__init__.pyi +4 -0
- touchkit/cam.py +146 -0
- touchkit/cam.pyi +35 -0
- touchkit/clock.py +18 -0
- touchkit/clock.pyi +6 -0
- touchkit/ecp.py +134 -0
- touchkit/ecp.pyi +28 -0
- touchkit/net.py +347 -0
- touchkit/net.pyi +27 -0
- touchkit/py.typed +0 -0
- touchkit/settings.py +85 -0
- touchkit/settings.pyi +17 -0
- touchkit/shell.py +268 -0
- touchkit/shell.pyi +42 -0
- touchkit/ui.py +167 -0
- 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")
|