spotapi 2.0.0b2__tar.gz → 2.1.0__tar.gz

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 (312) hide show
  1. spotapi-2.1.0/.dockerignore +9 -0
  2. spotapi-2.1.0/.env.example +4 -0
  3. spotapi-2.1.0/.github/workflows/docs.yml +21 -0
  4. spotapi-2.1.0/.github/workflows/publish.yml +74 -0
  5. spotapi-2.1.0/.github/workflows/spotify-public.yml +62 -0
  6. {spotapi-2.0.0b2 → spotapi-2.1.0}/.gitignore +29 -1
  7. spotapi-2.1.0/.readthedocs.yaml +14 -0
  8. spotapi-2.1.0/CHANGELOG.md +126 -0
  9. spotapi-2.1.0/CONTRIBUTING.md +66 -0
  10. spotapi-2.1.0/Dockerfile.mcp +8 -0
  11. {spotapi-2.0.0b2 → spotapi-2.1.0}/LEGAL_NOTICE.md +0 -2
  12. spotapi-2.1.0/MIGRATION.md +97 -0
  13. {spotapi-2.0.0b2 → spotapi-2.1.0}/PKG-INFO +206 -178
  14. spotapi-2.1.0/README.md +247 -0
  15. spotapi-2.1.0/SPONSORSHIP.md +65 -0
  16. spotapi-2.1.0/assets/README.md +10 -0
  17. spotapi-2.1.0/assets/cli-demo.gif +0 -0
  18. spotapi-2.1.0/assets/logo-inverse.svg +38 -0
  19. spotapi-2.1.0/assets/logo-mono.svg +38 -0
  20. spotapi-2.1.0/assets/spotapi-color.svg +48 -0
  21. spotapi-2.1.0/assets/spotapi-inverse.svg +48 -0
  22. spotapi-2.1.0/assets/spotapi-mono.svg +48 -0
  23. spotapi-2.1.0/assets/spotapi-reversed.svg +48 -0
  24. spotapi-2.1.0/benchmarks/review.py +408 -0
  25. spotapi-2.1.0/docs/account.md +98 -0
  26. spotapi-2.1.0/docs/api-layout.md +76 -0
  27. spotapi-2.1.0/docs/catalogue.md +83 -0
  28. spotapi-2.1.0/docs/discovery.md +227 -0
  29. spotapi-2.1.0/docs/from-spotipy.md +84 -0
  30. spotapi-2.1.0/docs/index.md +72 -0
  31. spotapi-2.1.0/docs/player-coverage.md +103 -0
  32. spotapi-2.1.0/docs/player.md +165 -0
  33. spotapi-2.1.0/docs/quickstart.md +134 -0
  34. spotapi-2.1.0/docs/reference.md +79 -0
  35. spotapi-2.1.0/docs/release-checks.md +129 -0
  36. spotapi-2.1.0/docs/studio.md +92 -0
  37. spotapi-2.1.0/docs/stylesheets/extra.css +7 -0
  38. spotapi-2.1.0/docs/transport.md +83 -0
  39. spotapi-2.1.0/examples/__init__.py +1 -0
  40. spotapi-2.1.0/examples/credit_trail.py +48 -0
  41. spotapi-2.1.0/examples/credits.py +16 -0
  42. spotapi-2.1.0/examples/custom_transport.py +17 -0
  43. spotapi-2.1.0/examples/discover.py +8 -0
  44. spotapi-2.1.0/examples/export.py +16 -0
  45. spotapi-2.1.0/examples/lookup.py +17 -0
  46. spotapi-2.1.0/examples/lyrics.py +21 -0
  47. spotapi-2.1.0/examples/mix_map.py +66 -0
  48. spotapi-2.1.0/examples/overlap.py +31 -0
  49. spotapi-2.1.0/examples/pagination.py +23 -0
  50. spotapi-2.1.0/examples/player.py +35 -0
  51. spotapi-2.1.0/examples/playlist_crate.py +31 -0
  52. spotapi-2.1.0/examples/public_search.py +29 -0
  53. spotapi-2.1.0/examples/quickstart.py +16 -0
  54. spotapi-2.1.0/examples/studio/__init__.py +1 -0
  55. spotapi-2.1.0/examples/studio/__main__.py +5 -0
  56. spotapi-2.1.0/examples/studio/preview.png +0 -0
  57. spotapi-2.1.0/examples/taste.py +29 -0
  58. spotapi-2.1.0/mkdocs.yml +82 -0
  59. {spotapi-2.0.0b2 → spotapi-2.1.0}/pyproject.toml +63 -18
  60. spotapi-2.1.0/requirements-docs.txt +4 -0
  61. spotapi-2.1.0/requirements.txt +1 -0
  62. spotapi-2.1.0/spotapi/__init__.py +141 -0
  63. spotapi-2.1.0/spotapi/_decoding.py +211 -0
  64. spotapi-2.1.0/spotapi/_demo/__init__.py +1 -0
  65. spotapi-2.1.0/spotapi/_demo/details.py +323 -0
  66. spotapi-2.1.0/spotapi/_demo/discover.py +767 -0
  67. spotapi-2.1.0/spotapi/_parsing.py +40 -0
  68. spotapi-2.1.0/spotapi/_protocol/__init__.py +1 -0
  69. spotapi-2.1.0/spotapi/_protocol/bundles.py +69 -0
  70. spotapi-2.1.0/spotapi/_protocol/embeds.py +46 -0
  71. spotapi-2.1.0/spotapi/_protocol/protobuf.py +120 -0
  72. spotapi-2.1.0/spotapi/_protocol/routes.py +66 -0
  73. spotapi-2.1.0/spotapi/_protocol/totp.py +81 -0
  74. spotapi-2.1.0/spotapi/_studio/__init__.py +1 -0
  75. spotapi-2.1.0/spotapi/_studio/actions.py +110 -0
  76. spotapi-2.1.0/spotapi/_studio/app.js +1109 -0
  77. spotapi-2.1.0/spotapi/_studio/assets/logo.ico +0 -0
  78. spotapi-2.1.0/spotapi/_studio/assets/logo.png +0 -0
  79. spotapi-2.1.0/spotapi/_studio/assets/logo.svg +48 -0
  80. spotapi-2.1.0/spotapi/_studio/desktop.py +235 -0
  81. spotapi-2.1.0/spotapi/_studio/index.html +325 -0
  82. spotapi-2.1.0/spotapi/_studio/lyrics.py +91 -0
  83. spotapi-2.1.0/spotapi/_studio/service.py +636 -0
  84. spotapi-2.1.0/spotapi/_studio/style.css +1361 -0
  85. spotapi-2.1.0/spotapi/account.py +280 -0
  86. spotapi-2.1.0/spotapi/account_session.py +152 -0
  87. spotapi-2.1.0/spotapi/batch.py +52 -0
  88. spotapi-2.1.0/spotapi/blend.py +70 -0
  89. spotapi-2.1.0/spotapi/cache.py +173 -0
  90. spotapi-2.1.0/spotapi/captcha.py +42 -0
  91. spotapi-2.1.0/spotapi/catalogue.py +1514 -0
  92. spotapi-2.1.0/spotapi/charts.py +22 -0
  93. spotapi-2.1.0/spotapi/cli.py +302 -0
  94. spotapi-2.1.0/spotapi/client.py +637 -0
  95. spotapi-2.1.0/spotapi/command_state.py +70 -0
  96. spotapi-2.1.0/spotapi/connect.py +55 -0
  97. spotapi-2.1.0/spotapi/connection/__init__.py +12 -0
  98. spotapi-2.1.0/spotapi/connection/client.py +8 -0
  99. spotapi-2.1.0/spotapi/connection/http.py +680 -0
  100. spotapi-2.1.0/spotapi/connection/types.py +84 -0
  101. spotapi-2.1.0/spotapi/connection/websocket.py +519 -0
  102. spotapi-2.1.0/spotapi/datastruct/__init__.py +7 -0
  103. spotapi-2.1.0/spotapi/datastruct/event_handler.py +167 -0
  104. spotapi-2.1.0/spotapi/datastruct/object_dict.py +196 -0
  105. spotapi-2.1.0/spotapi/datastruct/pool.py +235 -0
  106. spotapi-2.1.0/spotapi/devices.py +192 -0
  107. spotapi-2.1.0/spotapi/embeds.py +55 -0
  108. spotapi-2.1.0/spotapi/history.py +97 -0
  109. spotapi-2.1.0/spotapi/library.py +291 -0
  110. spotapi-2.1.0/spotapi/login.py +123 -0
  111. spotapi-2.1.0/spotapi/lyrics.py +75 -0
  112. spotapi-2.1.0/spotapi/mcp.py +157 -0
  113. spotapi-2.1.0/spotapi/media.py +140 -0
  114. spotapi-2.1.0/spotapi/models/__init__.py +118 -0
  115. spotapi-2.1.0/spotapi/models/account.py +122 -0
  116. spotapi-2.1.0/spotapi/models/batch.py +33 -0
  117. spotapi-2.1.0/spotapi/models/blend.py +42 -0
  118. spotapi-2.1.0/spotapi/models/catalogue/__init__.py +65 -0
  119. spotapi-2.1.0/spotapi/models/catalogue/album.py +71 -0
  120. spotapi-2.1.0/spotapi/models/catalogue/album_details.py +242 -0
  121. spotapi-2.1.0/spotapi/models/catalogue/artist.py +73 -0
  122. spotapi-2.1.0/spotapi/models/catalogue/artist_details.py +223 -0
  123. spotapi-2.1.0/spotapi/models/catalogue/common.py +95 -0
  124. spotapi-2.1.0/spotapi/models/catalogue/credits.py +39 -0
  125. spotapi-2.1.0/spotapi/models/catalogue/entities.py +194 -0
  126. spotapi-2.1.0/spotapi/models/catalogue/playlist.py +79 -0
  127. spotapi-2.1.0/spotapi/models/catalogue/playlist_details.py +52 -0
  128. spotapi-2.1.0/spotapi/models/catalogue/playlist_track.py +119 -0
  129. spotapi-2.1.0/spotapi/models/catalogue/podcast.py +55 -0
  130. spotapi-2.1.0/spotapi/models/catalogue/podcast_episode.py +136 -0
  131. spotapi-2.1.0/spotapi/models/catalogue/profile_attributes.py +35 -0
  132. spotapi-2.1.0/spotapi/models/catalogue/track.py +105 -0
  133. spotapi-2.1.0/spotapi/models/catalogue/track_details.py +206 -0
  134. spotapi-2.1.0/spotapi/models/discovery.py +213 -0
  135. spotapi-2.1.0/spotapi/models/embeds.py +44 -0
  136. spotapi-2.1.0/spotapi/models/history.py +76 -0
  137. spotapi-2.1.0/spotapi/models/library.py +148 -0
  138. spotapi-2.1.0/spotapi/models/lyrics.py +126 -0
  139. spotapi-2.1.0/spotapi/models/notifications.py +77 -0
  140. spotapi-2.1.0/spotapi/models/playback.py +292 -0
  141. spotapi-2.1.0/spotapi/models/profiles.py +20 -0
  142. spotapi-2.1.0/spotapi/models/search.py +91 -0
  143. spotapi-2.1.0/spotapi/models/sessions.py +11 -0
  144. spotapi-2.1.0/spotapi/models/stats.py +24 -0
  145. spotapi-2.1.0/spotapi/models/transcripts.py +64 -0
  146. spotapi-2.1.0/spotapi/notifications.py +88 -0
  147. spotapi-2.1.0/spotapi/operations.py +480 -0
  148. spotapi-2.1.0/spotapi/password.py +84 -0
  149. spotapi-2.1.0/spotapi/player.py +703 -0
  150. spotapi-2.1.0/spotapi/playlist.py +681 -0
  151. spotapi-2.1.0/spotapi/profiles.py +250 -0
  152. spotapi-2.1.0/spotapi/public.py +742 -0
  153. spotapi-2.1.0/spotapi/queries.py +409 -0
  154. spotapi-2.1.0/spotapi/query.py +613 -0
  155. spotapi-2.1.0/spotapi/resources.py +142 -0
  156. spotapi-2.1.0/spotapi/serialization.py +48 -0
  157. spotapi-2.1.0/spotapi/session.py +943 -0
  158. spotapi-2.1.0/spotapi/stats.py +108 -0
  159. spotapi-2.1.0/spotapi/status.py +769 -0
  160. spotapi-2.1.0/spotapi/sync.py +369 -0
  161. spotapi-2.1.0/spotapi/transcripts.py +37 -0
  162. spotapi-2.1.0/spotapi/types/__init__.py +44 -0
  163. spotapi-2.1.0/spotapi/types/exceptions.py +48 -0
  164. {spotapi-2.0.0b2/spotapi/v2 → spotapi-2.1.0/spotapi}/types/logger.py +254 -176
  165. spotapi-2.1.0/spotapi/utils/__init__.py +6 -0
  166. spotapi-2.1.0/spotapi/utils/cache.py +149 -0
  167. spotapi-2.1.0/spotapi/utils/random.py +28 -0
  168. spotapi-2.1.0/tests/README.md +29 -0
  169. spotapi-2.1.0/tests/conftest.py +39 -0
  170. spotapi-2.1.0/tests/fixtures/connect/message-1.json +100 -0
  171. spotapi-2.1.0/tests/fixtures/connect/message-2.json +382 -0
  172. spotapi-2.1.0/tests/fixtures/connect/message-3.json +393 -0
  173. spotapi-2.1.0/tests/fixtures/connect/message-4.json +146 -0
  174. spotapi-2.1.0/tests/test_account.py +276 -0
  175. spotapi-2.1.0/tests/test_account_content.py +461 -0
  176. spotapi-2.1.0/tests/test_artist_details_model.py +27 -0
  177. spotapi-2.1.0/tests/test_auth_recovery.py +233 -0
  178. spotapi-2.1.0/tests/test_authorized_requests.py +101 -0
  179. spotapi-2.1.0/tests/test_bundle_cache.py +209 -0
  180. spotapi-2.1.0/tests/test_catalogue_lifecycle.py +178 -0
  181. spotapi-2.1.0/tests/test_cli.py +128 -0
  182. spotapi-2.1.0/tests/test_data_contracts.py +218 -0
  183. spotapi-2.1.0/tests/test_discover_demo.py +196 -0
  184. spotapi-2.1.0/tests/test_discovery_parser.py +22 -0
  185. spotapi-2.1.0/tests/test_feature_parity.py +388 -0
  186. spotapi-2.1.0/tests/test_lifecycle.py +317 -0
  187. spotapi-2.1.0/tests/test_listening.py +167 -0
  188. spotapi-2.1.0/tests/test_live.py +103 -0
  189. spotapi-2.1.0/tests/test_live_account.py +39 -0
  190. spotapi-2.1.0/tests/test_live_catalogue.py +152 -0
  191. spotapi-2.1.0/tests/test_live_controls.py +199 -0
  192. spotapi-2.1.0/tests/test_live_discovery.py +35 -0
  193. spotapi-2.1.0/tests/test_live_player.py +38 -0
  194. spotapi-2.1.0/tests/test_live_playlists.py +124 -0
  195. spotapi-2.1.0/tests/test_live_studio.py +45 -0
  196. spotapi-2.1.0/tests/test_mutations.py +178 -0
  197. spotapi-2.1.0/tests/test_native_websocket.py +109 -0
  198. spotapi-2.1.0/tests/test_operations.py +74 -0
  199. spotapi-2.1.0/tests/test_optional_features.py +282 -0
  200. spotapi-2.1.0/tests/test_player.py +966 -0
  201. spotapi-2.1.0/tests/test_protobuf.py +35 -0
  202. spotapi-2.1.0/tests/test_public_api.py +627 -0
  203. spotapi-2.1.0/tests/test_public_catalogue.py +204 -0
  204. spotapi-2.1.0/tests/test_queries_parsing.py +132 -0
  205. spotapi-2.1.0/tests/test_review_regressions.py +174 -0
  206. spotapi-2.1.0/tests/test_routes.py +38 -0
  207. spotapi-2.1.0/tests/test_search_models.py +26 -0
  208. spotapi-2.1.0/tests/test_studio.py +272 -0
  209. spotapi-2.1.0/tests/test_studio_browser.py +258 -0
  210. spotapi-2.1.0/tests/test_transport.py +295 -0
  211. spotapi-2.1.0/tests/test_websocket_lifecycle.py +194 -0
  212. spotapi-2.0.0b2/CHANGELOG.md +0 -90
  213. spotapi-2.0.0b2/CONTRIBUTING.md +0 -247
  214. spotapi-2.0.0b2/MIGRATION.md +0 -182
  215. spotapi-2.0.0b2/README.md +0 -239
  216. spotapi-2.0.0b2/docs/album.md +0 -59
  217. spotapi-2.0.0b2/docs/artist.md +0 -107
  218. spotapi-2.0.0b2/docs/creator.md +0 -56
  219. spotapi-2.0.0b2/docs/family.md +0 -62
  220. spotapi-2.0.0b2/docs/language.md +0 -90
  221. spotapi-2.0.0b2/docs/login.md +0 -103
  222. spotapi-2.0.0b2/docs/password.md +0 -38
  223. spotapi-2.0.0b2/docs/player.md +0 -183
  224. spotapi-2.0.0b2/docs/playlist.md +0 -179
  225. spotapi-2.0.0b2/docs/public.md +0 -143
  226. spotapi-2.0.0b2/docs/song.md +0 -126
  227. spotapi-2.0.0b2/docs/status.md +0 -148
  228. spotapi-2.0.0b2/docs/user.md +0 -67
  229. spotapi-2.0.0b2/docs/websocket.md +0 -29
  230. spotapi-2.0.0b2/example.py +0 -119
  231. spotapi-2.0.0b2/image.png +0 -0
  232. spotapi-2.0.0b2/requirements.txt +0 -2
  233. spotapi-2.0.0b2/setup.py +0 -61
  234. spotapi-2.0.0b2/spotapi/sync/__init__.py +0 -25
  235. spotapi-2.0.0b2/spotapi/sync/_tests/.env.sample +0 -3
  236. spotapi-2.0.0b2/spotapi/sync/_tests/__init__.py +0 -1
  237. spotapi-2.0.0b2/spotapi/sync/_tests/annotations_test.py +0 -222
  238. spotapi-2.0.0b2/spotapi/sync/_tests/client_refresh_test.py +0 -224
  239. spotapi-2.0.0b2/spotapi/sync/_tests/features/artist_test.py +0 -196
  240. spotapi-2.0.0b2/spotapi/sync/_tests/features/event_test.py +0 -53
  241. spotapi-2.0.0b2/spotapi/sync/_tests/features/player_test.py +0 -112
  242. spotapi-2.0.0b2/spotapi/sync/_tests/features/private_playlist_test.py +0 -70
  243. spotapi-2.0.0b2/spotapi/sync/_tests/features/public_playlist_test.py +0 -32
  244. spotapi-2.0.0b2/spotapi/sync/_tests/features/session.py +0 -36
  245. spotapi-2.0.0b2/spotapi/sync/_tests/features/song_test.py +0 -67
  246. spotapi-2.0.0b2/spotapi/sync/_tests/features/status_test.py +0 -126
  247. spotapi-2.0.0b2/spotapi/sync/_tests/features/user_test.py +0 -63
  248. spotapi-2.0.0b2/spotapi/sync/album.py +0 -96
  249. spotapi-2.0.0b2/spotapi/sync/artist.py +0 -287
  250. spotapi-2.0.0b2/spotapi/sync/client.py +0 -314
  251. spotapi-2.0.0b2/spotapi/sync/creator.py +0 -203
  252. spotapi-2.0.0b2/spotapi/sync/exceptions/__init__.py +0 -1
  253. spotapi-2.0.0b2/spotapi/sync/exceptions/errors.py +0 -111
  254. spotapi-2.0.0b2/spotapi/sync/family.py +0 -162
  255. spotapi-2.0.0b2/spotapi/sync/http/__init__.py +0 -2
  256. spotapi-2.0.0b2/spotapi/sync/http/data.py +0 -43
  257. spotapi-2.0.0b2/spotapi/sync/http/request.py +0 -248
  258. spotapi-2.0.0b2/spotapi/sync/login.py +0 -356
  259. spotapi-2.0.0b2/spotapi/sync/password.py +0 -97
  260. spotapi-2.0.0b2/spotapi/sync/player.py +0 -348
  261. spotapi-2.0.0b2/spotapi/sync/playlist.py +0 -417
  262. spotapi-2.0.0b2/spotapi/sync/podcast.py +0 -129
  263. spotapi-2.0.0b2/spotapi/sync/public.py +0 -117
  264. spotapi-2.0.0b2/spotapi/sync/solvers/__init__.py +0 -15
  265. spotapi-2.0.0b2/spotapi/sync/solvers/capmonster.py +0 -145
  266. spotapi-2.0.0b2/spotapi/sync/solvers/capsolver.py +0 -144
  267. spotapi-2.0.0b2/spotapi/sync/song.py +0 -288
  268. spotapi-2.0.0b2/spotapi/sync/status.py +0 -226
  269. spotapi-2.0.0b2/spotapi/sync/types/__init__.py +0 -2
  270. spotapi-2.0.0b2/spotapi/sync/types/alias.py +0 -29
  271. spotapi-2.0.0b2/spotapi/sync/types/annotations.py +0 -201
  272. spotapi-2.0.0b2/spotapi/sync/types/data.py +0 -413
  273. spotapi-2.0.0b2/spotapi/sync/types/interfaces.py +0 -57
  274. spotapi-2.0.0b2/spotapi/sync/user.py +0 -128
  275. spotapi-2.0.0b2/spotapi/sync/utils/__init__.py +0 -3
  276. spotapi-2.0.0b2/spotapi/sync/utils/logger.py +0 -91
  277. spotapi-2.0.0b2/spotapi/sync/utils/saver.py +0 -357
  278. spotapi-2.0.0b2/spotapi/sync/utils/strings.py +0 -130
  279. spotapi-2.0.0b2/spotapi/sync/websocket.py +0 -167
  280. spotapi-2.0.0b2/spotapi/v2/__init__.py +0 -11
  281. spotapi-2.0.0b2/spotapi/v2/client.py +0 -101
  282. spotapi-2.0.0b2/spotapi/v2/connection/__init__.py +0 -12
  283. spotapi-2.0.0b2/spotapi/v2/connection/http.py +0 -288
  284. spotapi-2.0.0b2/spotapi/v2/connection/types.py +0 -76
  285. spotapi-2.0.0b2/spotapi/v2/connection/websocket.py +0 -199
  286. spotapi-2.0.0b2/spotapi/v2/datastruct/__init__.py +0 -9
  287. spotapi-2.0.0b2/spotapi/v2/datastruct/event_handler.py +0 -62
  288. spotapi-2.0.0b2/spotapi/v2/datastruct/object_dict.py +0 -176
  289. spotapi-2.0.0b2/spotapi/v2/datastruct/pool.py +0 -155
  290. spotapi-2.0.0b2/spotapi/v2/playlist.py +0 -225
  291. spotapi-2.0.0b2/spotapi/v2/public.py +0 -370
  292. spotapi-2.0.0b2/spotapi/v2/query.py +0 -117
  293. spotapi-2.0.0b2/spotapi/v2/session.py +0 -392
  294. spotapi-2.0.0b2/spotapi/v2/specialized/__init__.py +0 -3
  295. spotapi-2.0.0b2/spotapi/v2/specialized/data_wrappers/__init__.py +0 -165
  296. spotapi-2.0.0b2/spotapi/v2/specialized/data_wrappers/album.py +0 -93
  297. spotapi-2.0.0b2/spotapi/v2/specialized/data_wrappers/artist.py +0 -66
  298. spotapi-2.0.0b2/spotapi/v2/specialized/data_wrappers/common.py +0 -139
  299. spotapi-2.0.0b2/spotapi/v2/specialized/data_wrappers/playlist.py +0 -81
  300. spotapi-2.0.0b2/spotapi/v2/specialized/data_wrappers/podcast.py +0 -75
  301. spotapi-2.0.0b2/spotapi/v2/specialized/data_wrappers/profile_attributes.py +0 -29
  302. spotapi-2.0.0b2/spotapi/v2/specialized/data_wrappers/track.py +0 -113
  303. spotapi-2.0.0b2/spotapi/v2/specialized/totp.py +0 -66
  304. spotapi-2.0.0b2/spotapi/v2/types/__init__.py +0 -12
  305. spotapi-2.0.0b2/spotapi/v2/types/exceptions.py +0 -27
  306. spotapi-2.0.0b2/spotapi/v2/utils/__init__.py +0 -12
  307. spotapi-2.0.0b2/spotapi/v2/utils/cache.py +0 -62
  308. spotapi-2.0.0b2/spotapi/v2/utils/random.py +0 -22
  309. spotapi-2.0.0b2/spotapi/v2/utils/strings.py +0 -130
  310. {spotapi-2.0.0b2 → spotapi-2.1.0}/CODE_OF_CONDUCT.md +0 -0
  311. {spotapi-2.0.0b2 → spotapi-2.1.0}/LICENSE +0 -0
  312. {spotapi-2.0.0b2/spotapi/v2 → spotapi-2.1.0/spotapi}/py.typed +0 -0
@@ -0,0 +1,9 @@
1
+ *
2
+ !spotapi/
3
+ !spotapi/**
4
+ !pyproject.toml
5
+ !README.md
6
+ !LICENSE
7
+ !Dockerfile.mcp
8
+ spotapi/**/__pycache__/
9
+ spotapi/**/*.pyc
@@ -0,0 +1,4 @@
1
+ # Optional personal session. Never commit a real cookie.
2
+ SPOTIFY_COOKIE=""
3
+
4
+ # Live tests: pytest --live=read (reads), pytest --live=all (playback and temporary-playlist changes).
@@ -0,0 +1,21 @@
1
+ name: Documentation
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+ - uses: actions/setup-python@v5
14
+ with:
15
+ python-version: "3.12"
16
+ - run: python -m pip install -r requirements-docs.txt
17
+ - run: python -m mkdocs build --strict
18
+ - uses: actions/upload-artifact@v4
19
+ with:
20
+ name: documentation-site
21
+ path: site/
@@ -0,0 +1,74 @@
1
+ name: Publish a tagged release
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+
7
+ jobs:
8
+ build:
9
+ runs-on: ubuntu-latest
10
+ steps:
11
+ - uses: actions/checkout@v4
12
+ - uses: actions/setup-python@v5
13
+ with:
14
+ python-version: "3.11"
15
+ - name: Check the tag matches package metadata
16
+ run: |
17
+ python - <<'PY'
18
+ import os, tomllib
19
+ from pathlib import Path
20
+ version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
21
+ assert os.environ["GITHUB_REF_NAME"] == f"v{version}", "Tag and package versions differ"
22
+ PY
23
+ - run: python -m pip install build twine
24
+ - run: python -m pip install -e '.[dev,demo]'
25
+ - run: python -m playwright install --with-deps chromium
26
+ - run: python -m pytest -m 'not live' -q
27
+ - run: python -m pyright
28
+ - run: python -m ruff check .
29
+ - run: python -m black --check .
30
+ - run: python -m build
31
+ - run: python -m twine check dist/*
32
+ - run: python -m pip install --force-reinstall --no-deps dist/*.whl
33
+ - name: Smoke-test the installed wheel outside the checkout
34
+ working-directory: /tmp
35
+ run: |
36
+ spotapi --help
37
+ spotapi discover --help
38
+ spotapi studio --help
39
+ python -I - <<'PY'
40
+ import os
41
+ from importlib.util import find_spec
42
+ from pathlib import Path
43
+ import spotapi
44
+ from spotapi import Private, Public
45
+ from spotapi.models import PlaylistTrack
46
+ assert not Path(spotapi.__file__).resolve().is_relative_to(Path(os.environ["GITHUB_WORKSPACE"]).resolve())
47
+ assert find_spec("spotapi.v2") is None
48
+ assert callable(Private.from_cookies)
49
+ assert find_spec("spotapi._demo.discover") is not None
50
+ assert find_spec("spotapi._demo.details") is not None
51
+ from spotapi._studio.desktop import page
52
+ assert "STUDIO_SCRIPT" not in page()
53
+ from importlib.resources import files
54
+ for asset in ("logo.svg", "logo.png", "logo.ico"):
55
+ assert files("spotapi._studio").joinpath("assets", asset).is_file()
56
+ assert Public.parse_url("spotify:track:abc").id == "abc"
57
+ PY
58
+ - uses: actions/upload-artifact@v4
59
+ with:
60
+ name: python-distributions
61
+ path: dist/
62
+
63
+ publish:
64
+ needs: build
65
+ runs-on: ubuntu-latest
66
+ environment: pypi
67
+ permissions:
68
+ id-token: write
69
+ steps:
70
+ - uses: actions/download-artifact@v4
71
+ with:
72
+ name: python-distributions
73
+ path: dist/
74
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,62 @@
1
+ name: Spotify API checks
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+ schedule:
7
+ - cron: "17 8 * * *" # Daily contract check; reports upstream breaking changes
8
+ workflow_dispatch:
9
+
10
+ jobs:
11
+ offline:
12
+ runs-on: ${{ matrix.os }}
13
+ timeout-minutes: 15
14
+ strategy:
15
+ fail-fast: false
16
+ matrix:
17
+ os: [ubuntu-latest]
18
+ python: ["3.11", "3.12", "3.13"]
19
+ include:
20
+ - os: windows-latest
21
+ python: "3.12"
22
+ - os: macos-latest
23
+ python: "3.12"
24
+ steps:
25
+ - uses: actions/checkout@v4
26
+ - uses: actions/setup-python@v5
27
+ with:
28
+ python-version: ${{ matrix.python }}
29
+ - run: python -m pip install -e '.[dev,demo]'
30
+ - run: python -m coverage run -m pytest -m 'not live'
31
+ - run: python -m coverage report
32
+ - run: python -m coverage xml
33
+ - uses: actions/upload-artifact@v4
34
+ with:
35
+ name: coverage-${{ matrix.os }}-python-${{ matrix.python }}
36
+ path: coverage.xml
37
+ - run: python -m pyright
38
+ - run: python -m ruff check .
39
+ - run: python -m black --check .
40
+
41
+ public-api:
42
+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
43
+ runs-on: ubuntu-latest
44
+ timeout-minutes: 15
45
+ steps:
46
+ - uses: actions/checkout@v4
47
+ - uses: actions/setup-python@v5
48
+ with:
49
+ python-version: "3.12"
50
+ - run: python -m pip install -e '.[dev]'
51
+ - run: python -m pytest --live=read -m live -vv
52
+
53
+ studio-ui:
54
+ runs-on: ubuntu-latest
55
+ steps:
56
+ - uses: actions/checkout@v4
57
+ - uses: actions/setup-python@v5
58
+ with:
59
+ python-version: "3.12"
60
+ - run: python -m pip install -e '.[dev]'
61
+ - run: python -m playwright install --with-deps chromium
62
+ - run: python -m pytest tests/test_studio.py tests/test_studio_browser.py -q
@@ -163,4 +163,32 @@ cython_debug/
163
163
  #.idea/
164
164
  main.py
165
165
  build.bat
166
- sessions.json
166
+ sessions.json
167
+
168
+ # Local planning, review notes, and exploratory captures
169
+ /docs/growth-and-coverage.md
170
+ /docs/research/
171
+ /ARCHITECTURE_REVIEW.md
172
+ /PUBLIC_FEATURES.md
173
+ /REVIEW_REPORT.md
174
+ /V2_REVIEW.md
175
+ /docs/independent-review.md
176
+ /docs/release-audit.md
177
+ /benchmarks/*.json
178
+
179
+ # Local credentials and tool artifacts
180
+ .env.*
181
+ !.env.example
182
+ .ruff_cache/
183
+ .idea/
184
+ .DS_Store
185
+ Thumbs.db
186
+
187
+ # Session-specific audit notes (keep contributor guides and regression tests)
188
+ /docs/code-quality-review.md
189
+
190
+ # Generated anonymous demo snapshots
191
+ /credit-atlas.html
192
+
193
+ # Optional public metadata response cache
194
+ .spotapi-cache/
@@ -0,0 +1,14 @@
1
+ version: 2
2
+
3
+ build:
4
+ os: ubuntu-24.04
5
+ tools:
6
+ python: "3.12"
7
+
8
+ mkdocs:
9
+ configuration: mkdocs.yml
10
+ fail_on_warning: true
11
+
12
+ python:
13
+ install:
14
+ - requirements: requirements-docs.txt
@@ -0,0 +1,126 @@
1
+ # Changelog
2
+
3
+ ## 2.1.0 - 2026-11-13
4
+
5
+ ### Added
6
+
7
+ - Launch the packaged desktop application with `spotapi studio` after installing
8
+ `spotapi[studio]`; its frontend and icons ship in the wheel.
9
+ - Keep first results and sign-in visible in Studio's minimum-size window,
10
+ with independently scrollable navigation.
11
+ - Launch the packaged terminal browser with `spotapi discover` and the demo extra.
12
+ - Read artist Discovered On playlists, concerts, similar albums and image palettes.
13
+ - Read typed podcast captions, explicit embed snapshots and public media assets.
14
+ - Export JSON-safe models, collect ordered partial-failure batches, optionally
15
+ cache anonymous responses and reuse the async core from `SyncCatalogue`.
16
+ - Optional browser login, OS-keyring sessions and read-only MCP integration.
17
+ - Read the Docs configuration, generated API reference and a Spotipy migration guide.
18
+
19
+ ### Changed
20
+
21
+ - Discover the main and search-route bundles first, loading other routes on demand
22
+ with eight continuously scheduled workers and build-specific hash caching.
23
+ - Managed account scopes accept explicit proxy and language options.
24
+ - Keep sponsorship placements below usage material, with optional integration
25
+ partnerships and privately quoted scope.
26
+ - Require `wreq` 0.12.3 or newer within the compatible 0.12 release line for
27
+ corrected coroutine cancellation; 0.13 remains excluded because it changes
28
+ binary response types.
29
+
30
+ ### Fixed
31
+
32
+ - Dealer disconnects wake command waiters and clear readiness; temporary device
33
+ loss no longer discards a valid late ACK. Quiet dealers allow one snapshot
34
+ refresh within the existing deadline; old snapshots cannot prove success.
35
+ - Playback restoration preserves its original target and primary error, and
36
+ does not confirm a seek that failed. Commands are never silently replayed.
37
+ - Failed route downloads can be retried rather than becoming permanent misses.
38
+ - Anonymous embed fallback preserves proxies and cannot downgrade borrowed scopes.
39
+ - Sync shutdown rejects nested event loops before losing resource ownership.
40
+ - Discover releases cached images when feed shutdown fails, and Escape/Down
41
+ return keyboard focus from search to results.
42
+
43
+ ## 2.0.0
44
+
45
+ - Use `spotapi` for all async imports. The synchronous release remains available as `spotapi==1.2.8`.
46
+ - Install the `spotapi` command for anonymous track search and JSON resource lookups.
47
+ - Open a managed account session with `Private.from_cookies()`.
48
+ - Follow, unfollow and check artists by ID, URI or URL through `account.library`.
49
+ - Fetch multiple tracks, albums or artists through one catalogue client.
50
+ - Move exact playlist occurrences by UID, including duplicate tracks.
51
+ - Set or clear a custom JPEG playlist cover.
52
+ - Stream typed audiobook chapter pages for available titles.
53
+ - Browse Studio lyrics through LRCLIB and seek from timed lines on the matching track.
54
+
55
+ ### Added
56
+
57
+ - Typed async catalogue search, lookups, credits, discovery and lazy pagination.
58
+ - `Public` for self-cleaning one-shot calls and `Catalogue` for connection reuse.
59
+ - Cookie-authenticated account, library, rankings, profiles and notifications.
60
+ - Existing-player controls, async listeners, occurrence-aware queue editing,
61
+ sleep timers and entitled lyrics.
62
+ - Playlist metadata editing and removal by exact occurrence UID.
63
+ - A provider-neutral async CAPTCHA protocol for explicit account operations.
64
+ - Optional Studio and terminal examples; their dependencies stay outside the core.
65
+ - Offline lifecycle and contract tests, opt-in live checks, and release workflows.
66
+
67
+ ### Changed
68
+
69
+ - Authenticated feature requests use `authorized=True`; credential assembly,
70
+ renewal, destination validation and redirect policy live in `AsyncClient`.
71
+ - Identical artwork color and contrast-role shapes share `RGBA` and
72
+ `ContrastPalette` value types instead of nine duplicate dataclasses.
73
+ - Result types live in the `models` package, grouped by domain; importing them
74
+ does not load the native HTTP transport. Old implementation paths were removed.
75
+ - Internal endpoint templates, protobuf, bundle parsing and TOTP helpers live
76
+ in `_protocol`; repeated resource paths share one escaping implementation.
77
+
78
+ - Advanced searches use immutable `SearchOptions` with snake_case fields and
79
+ `options=`; native GraphQL variable names remain internal to serialization.
80
+ - Direct transport access is `client.transport` and `client.websocket`.
81
+ - Authenticated profile attributes expose Python field names; see the migration guide.
82
+
83
+ - Python 3.11+ and async/await are required. See [migration](MIGRATION.md) for
84
+ compatibility changes and v1 features that have not been ported.
85
+ - Hatch and `pyproject.toml` define package metadata; `requirements.txt` retains
86
+ the same tested transport pin.
87
+ - Known reads opt into bounded retries. Mutations are not replayed after
88
+ ambiguous failures; account CSRF rotation is handled explicitly.
89
+ - Query hashes use a build-bound disk cache. Cached startup fetches the main
90
+ bundle rather than every chunk, and discards unneeded source after parsing.
91
+ - Clients own refresh, socket and callback tasks and release them on shutdown.
92
+ - Logging defaults to the standard library without configuring application sinks.
93
+
94
+ ### Fixed
95
+
96
+ - Directly constructed authentication sessions attach to their owning client,
97
+ so safe request renewal and shutdown behave consistently across factories.
98
+ - `max_attempts=1` also prevents a second request after an authorization failure.
99
+ - HEAD, 204 and 205 responses may be empty even with a JSON Content-Type.
100
+ - Accepted cleanup statuses use `expected_statuses`, preserving normal
101
+ authorization handling without duplicating status checks in features.
102
+
103
+ - Thread-local implicit query owners no longer share a slotted registry across threads.
104
+ - Managed authorization rebuilds fresh credential headers after renewal; custom header names and JSON media types are case-insensitive.
105
+ - The model decoder recognizes native GraphQL `__typename` fields consistently with search preflight.
106
+ - Profile options, profile attributes and notification identities/cursors reject malformed contracts.
107
+ - Exception logging respects the configured severity filter and synchronization.
108
+
109
+ - Playlist add/remove operations reject error unions such as `NotFound` instead
110
+ of interpreting a nonempty error object as success.
111
+ - Commands with `wait=True` require a matching dealer ACK or a fresh state proving
112
+ the result, even when the HTTP response contains no acknowledgement ID.
113
+ - Studio cancels timed-out sign-ins, prevents concurrent cookie imports, and
114
+ discards delayed data from the previous account.
115
+ - Library saves, pins and user follows validate Spotify's confirmation instead
116
+ of accepting nonempty error responses or incomplete mutation results.
117
+ - Playback restrictions, canonical playlist metadata reads, and optional model
118
+ fields are handled explicitly.
119
+
120
+ See the [release checks](docs/release-checks.md) and [player coverage](docs/player-coverage.md)
121
+ for supported workflows and known gaps.
122
+
123
+ ## v1 history
124
+
125
+ See the [repository history](https://github.com/Aran404/SpotAPI/commits/main/)
126
+ for changes predating the rewrite.
@@ -0,0 +1,66 @@
1
+ # Contributing
2
+
3
+ Use Python 3.11 or later and the v2 checkout.
4
+
5
+ ```bash
6
+ python -m pip install -e ".[dev,demo]"
7
+ python -m pytest -q
8
+ python -m pyright
9
+ python -m ruff check .
10
+ python -m black --check .
11
+ ```
12
+
13
+ The root Pyright configuration checks the library, examples and tests in
14
+ strict mode. Tests may inspect private members to verify lifecycle behavior.
15
+ Format with `python -m black .`; Ruff checks imports and code quality.
16
+ For branch coverage, use `python -m coverage run -m pytest -m "not live"`
17
+ and `python -m coverage report`. Offline CI publishes the XML report for each
18
+ Python version; inspect the baseline before setting a coverage threshold.
19
+
20
+ Tests run offline by default. For read-only Spotify contract checks:
21
+
22
+ ```bash
23
+ python -m pytest --live=read -vv
24
+ ```
25
+
26
+ The same command runs public and authenticated reads when `SPOTIFY_COOKIE` is set
27
+ in the environment or local `.env`. Use `--live=all` to include explicit playback
28
+ changes; it is one mode switch, not a second environment flag.
29
+ Live tests depend on Spotify and may fail when upstream contracts change.
30
+ Never run mutating checks in ordinary CI. Personal playback checks restore their baseline in `finally`.
31
+
32
+ Use real Spotify JSON key spelling in fixtures, including `items`. Test
33
+ ownership, cancellation, partial payloads, and retry safety when changing
34
+ network behavior. Keep optional metadata optional. A new background task
35
+ needs an owner, a retained reference, observable failures, and shutdown.
36
+
37
+ The package uses Hatch and `pyproject.toml` as its packaging source of truth.
38
+ Keep `requirements.txt` consistent with the tested wreq pin. Check a wheel
39
+ with `python -m pip wheel . --no-deps` when changing packaging.
40
+
41
+ Benchmark with `python benchmarks/review.py --output benchmarks/local.json`.
42
+ Add `--live` for network measurements. Publish raw samples and distinguish
43
+ new sessions, warm sessions, disk caches, network latency, and model overhead.
44
+ Do not infer network speedups from the offline ownership comparison.
45
+
46
+ See the [API layout](docs/api-layout.md) for module responsibilities and
47
+ ownership. Follow the [code of conduct](CODE_OF_CONDUCT.md).
48
+
49
+
50
+ ## Documentation
51
+
52
+ The site uses MkDocs Material and source-generated Python API references.
53
+ Read the Docs reads `.readthedocs.yaml`; CI builds the same `mkdocs.yml` strictly.
54
+ Use Python 3.12 for the pinned documentation toolchain:
55
+
56
+ ```sh
57
+ python -m pip install -r requirements-docs.txt
58
+ python -m mkdocs build --strict
59
+ python -m mkdocs serve
60
+ ```
61
+
62
+ Local research, captured metadata and audit notes under `docs/research` are
63
+ excluded from the site and Git. Do not add credentials to examples or screenshots.
64
+ To activate hosting, import the public repository in Read the Docs, select main,
65
+ and confirm the actual project slug before advertising its public URL. The
66
+ configuration alone does not create an account, project, webhook or hosted site.
@@ -0,0 +1,8 @@
1
+ FROM python:3.12-slim
2
+ WORKDIR /app
3
+ COPY pyproject.toml README.md LICENSE ./
4
+ COPY spotapi ./spotapi
5
+ RUN pip install --no-cache-dir ".[mcp]" && useradd --create-home --uid 10001 spotapi
6
+ USER spotapi
7
+ ENV PYTHONUNBUFFERED=1
8
+ ENTRYPOINT ["spotapi-mcp"]
@@ -4,8 +4,6 @@ This repository is in no way affiliated with, authorized, maintained, sponsored
4
4
 
5
5
  Please note the following:
6
6
 
7
- ## Legal Notice
8
-
9
7
  ### **Affiliation Disclaimer**
10
8
  The project is intended for educational purposes only. The APIs, services, trademarks, and other intellectual property mentioned in this repository are the property of their respective owners, with no claim of ownership or affiliation by this project.
11
9
 
@@ -0,0 +1,97 @@
1
+ # Migrating to SpotAPI 2
2
+
3
+ SpotAPI 2 requires Python 3.11+ and uses `async`/`await` under `spotapi`.
4
+ For a synchronous application, install the legacy release in its own environment
5
+ with `python -m pip install "spotapi<2"`. SpotAPI 2 is a breaking upgrade.
6
+
7
+ | Old | New | Reason |
8
+ |---|---|---|
9
+ | `InclusionParameters(..., includePreReleases=True)` and `parameters=` | `SearchOptions(..., include_pre_releases=True)` and `options=` | Immutable Python options with explicit conversion to Spotify's wire variables |
10
+ | Empty `SEARCH_RAW_OPERATIONS` mapping | `SEARCH_DESKTOP_SECTIONS` | Every supported search category uses the consolidated desktop operation |
11
+ | `client.protocols.http` / `client.protocols.ws` | `client.transport` / `client.websocket` | Direct transport access without an intermediate tuple |
12
+ | Manually merged session credential headers | `client.get(url, authorized=True)` | Centralized credential construction, destination checks and safe renewal |
13
+ | Directly constructed `AuthSession(client)` is detached | It attaches to its client; one session per client | Consistent refresh and shutdown ownership |
14
+ | `max_attempts=1` can still replay after a 401 | It forbids renewal replay too | One attempt means one attempt for mutations |
15
+ | Non-success statuses always raise | `expected_statuses=(404,)` | Explicit endpoint-specific status handling without using the raw transport |
16
+ | `spotapi.playback`, `discovery`, `library_models` and models in feature modules | `spotapi.models` or its domain submodules | Result types are independent of feature clients |
17
+ | Separate artwork color/contrast-role classes | `RGBA` and `ContrastPalette` in `models.catalogue.common` | Identical value contracts share one implementation; nested field names stay unchanged |
18
+ | Public-looking `spotapi.protobuf`, `bundle_parsing`, `specialized.totp` helpers | Internal `spotapi._protocol` modules | Wire implementation details are not application-facing API |
19
+ | `Profile.accountId`, `avatarBackgroundColor`, `socialHandle` | `account_id`, `avatar_background_color`, `social_handle` | Python names at the model boundary; wire keys remain unchanged |
20
+ | `QueryWrapper` / `spotapi.v2.query_wrapper` | `Queries` / `spotapi.queries` | Name the persisted-query responsibility directly |
21
+ | Deep `specialized.data_wrappers` application imports | `from spotapi.models import ...` | Discoverable public model namespace |
22
+ | Extended searches return raw dictionaries through separate operations | Typed Audiobook/Episode/User/Author/Genre results from one `searchDesktop` request | Working anonymous search with stable return types |
23
+ | `Public.get(playlist_url)` returns raw data | `PlaylistDetails`; use `Queries` for raw operations | Metadata is typed; track occurrence pagination is explicit |
24
+ | `Public.get_podcast()` returns raw metadata | `PodcastDetails`; audiobooks use `get_audiobook()` | Respect Spotify's distinct podcast/audiobook entity types |
25
+ | `Public.get(show_url)` assumes a podcast | Detects Podcast or Audiobook from response typename | Audiobooks also use Spotify show URLs |
26
+ | PlaylistTrack requires presentation fields | Identity required; duration/artwork/ratings may be None | Legitimate partial Spotify payloads remain usable |
27
+ | Playlist attributes are opaque dictionaries | Typed key/value attributes | Standard dataclass JSON export stays plain and predictable |
28
+ | Query-cache format 1 | Format 2, rebuilt once | Discard incomplete hashes produced by the former JS/CSS chunk-map mix-up |
29
+ | v1 `Song().paginate_songs(...)` | `Public.search_tracks(...)` with `async for` | Async I/O and typed results |
30
+ | Nested raw search dictionaries | `result.tracks`, `track.name`, `artist.name` | Discoverable result models |
31
+ | `spotapi.v2` | `spotapi` | One import namespace for the async package |
32
+ | Public operations rely on an implicit loop pool | `Public` owns each operation; `async with Catalogue()` reuses a client | Deterministic cleanup and explicit connection reuse |
33
+ | `query_client_pool()` returns generic `Pool` | Shared owner with `acquire()`, `close()`, `closed` | Preserve borrowing/shutdown interface; generic-pool internals are no longer available |
34
+ | Global `connection.ClientPool` | `async with HTTPClient()` or `AsyncClient()` | Remove an unused, globally loop-bound pool above wreq's pool |
35
+ | Unknown POST/PUT/PATCH/DELETE replayed by default | One attempt by default | Ambiguous failures may already have applied mutations |
36
+ | Raw read-only POST inherits retries | Set `retry_safe=True` or explicit `max_attempts` | Make replay safety deliberate; built-in catalogue reads opt in automatically |
37
+ | Unknown Pathfinder operation inherits retries | One attempt unless explicit `max_attempts` is supplied | Operation names alone do not prove read semantics |
38
+ | Permanent HTTP wreq exceptions escape | `HTTPError` with original exception as cause | One library base (`SpotAPIError`); programmer errors and cancellation still propagate |
39
+ | WebSocket listeners continue after context exit | Pending listeners are cancelled and awaited | Connection-scoped ownership |
40
+ | Unlimited pending event callback tasks | 256 by default, configurable on `EventDispatcher(max_pending=...)` | Bound slow-listener memory; saturation is logged |
41
+ | Indefinitely old query-cache entries accepted | Build-bound cache, 24-hour expiry, validated hashes, bounded input | Stale or malformed caches become misses |
42
+ | `QueryCache.load()` / `save(hashes)` with a bare JSON mapping | Optional build version on load/save; versioned envelope on disk | Existing files are refreshed once; matching builds skip chunk downloads |
43
+ | `BundleSession.warm()` retains every JavaScript chunk | Retains the main bundle after extracting hashes; `load()` explicitly fetches all sources | Avoid retaining source no longer needed for requests or token renewal |
44
+ | `pytest` silently makes live requests | Use `pytest --live=read` explicitly | Reproducible offline contributor workflow |
45
+ | pyproject permits wreq upgrades while requirements pins 0.12.0 | Both pin 0.12.0 | Test and install the same transport version |
46
+ | Legacy `setup.py` with v1 metadata | Hatch / `pyproject.toml` only | Remove competing version and dependency metadata |
47
+
48
+ `ObjectDict` mapping keys remain original JSON keys. `data["items"]` and
49
+ `data._items` refer to the same key. When both `items` and `_items` exist,
50
+ use `data["_items"]` or `data.__items` for the latter. Methods such as
51
+ `items()` and `get()` retain normal dictionary meaning. Historical callers
52
+ with pre-escaped `_items` pages remain accepted by page parsers.
53
+
54
+ Search metadata is legitimately optional. Check `track.duration is not None`
55
+ before reading milliseconds, and check optional artist/publisher/artwork
56
+ objects before dereferencing them. `Public.get_track` returns `TrackDetails`;
57
+ `Public.get(url)` returns a union based on the resource identified by the URL.
58
+
59
+ Use `Public` for one-shot work. Lookups close before returning; page streams
60
+ close on exhaustion or `aclose()`. Wrap streams in `contextlib.aclosing` if
61
+ you may break early. Reuse `async with Catalogue() as spotify` for multiple
62
+ operations, proxy configuration, and raw queries through `spotify.queries`.
63
+ A catalogue cannot be reopened after closing. Injected `Queries` remain
64
+ owned by their caller. `close_query_clients()` only applies to lower-level
65
+ code using the implicit `Queries()` pool.
66
+
67
+ Authenticated playlist operations live in `spotapi.playlist` and accept an
68
+ authorized `AuthSession`. They deliberately use one attempt. Reconcile state
69
+ after ambiguous failures before deciding whether to retry yourself. The
70
+ low-level WebSocket API retains wreq's error types.
71
+
72
+
73
+ Player helpers now accept `AsyncClient.from_cookies(...)` clients (or an
74
+ explicit `AuthSession`). `PlayerStatus` is a scoped dealer observer, and
75
+ `Player` adds device selection and single-attempt control. Replace v1's
76
+ threaded `EventManager.subscribe` with async `@player.event` or
77
+ `@player.listen("track_change")` callbacks inside `player.connect()`.
78
+ Property reads use cached typed snapshots; `refresh()` performs an explicit
79
+ request. Volume is an integer percentage from 0 to 100. HOBS observer IDs and
80
+ full playback device IDs are separate arguments. See [the player guide](docs/player.md).
81
+
82
+ `await player.start()` manages reconnection and stops with `await player.close()`.
83
+ Use `wait_for(event, check=..., timeout=...)` for matching events. Connection
84
+ cleanup includes the owned control-only registration, observers, timers and
85
+ callbacks; the caller still owns the supplied authenticated client.
86
+
87
+ Queue edits preserve occurrence UIDs and use the last observed revision.
88
+ Library and history access are also reusable as `LikedTracks(client)` and
89
+ `ListeningHistory(client)`. Recents represent dated grouped contexts and saved
90
+ actions; they do not provide exact per-play timestamps.
91
+
92
+ Managed authorization accepts HTTPS Spotify hosts and disables redirects. Custom
93
+ headers must be a string mapping; replacing `Authorization` or `client-token`
94
+ (case-insensitively) is rejected. Use the raw `client.transport` only when an
95
+ integration deliberately needs to own its authentication/status policy. The
96
+ feature helpers' `http` attribute is the validated `AsyncClient`, not the raw
97
+ transport. See [request policy](docs/transport.md).