spotapi 2.1.0__tar.gz → 2.1.1__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 (275) hide show
  1. spotapi-2.1.1/.github/ISSUE_TEMPLATE/bug.yml +109 -0
  2. spotapi-2.1.1/.github/ISSUE_TEMPLATE/config.yml +11 -0
  3. spotapi-2.1.1/.github/ISSUE_TEMPLATE/feature.yml +66 -0
  4. spotapi-2.1.1/.github/pull_request_template.md +25 -0
  5. {spotapi-2.1.0 → spotapi-2.1.1}/.github/workflows/docs.yml +1 -0
  6. spotapi-2.1.1/.github/workflows/spotify-public.yml +119 -0
  7. {spotapi-2.1.0 → spotapi-2.1.1}/CHANGELOG.md +33 -0
  8. {spotapi-2.1.0 → spotapi-2.1.1}/CONTRIBUTING.md +19 -5
  9. spotapi-2.1.1/LEGAL_NOTICE.md +36 -0
  10. spotapi-2.1.1/MIGRATION.md +197 -0
  11. {spotapi-2.1.0 → spotapi-2.1.1}/PKG-INFO +108 -163
  12. spotapi-2.1.1/README.es.md +189 -0
  13. spotapi-2.1.1/README.fr.md +189 -0
  14. spotapi-2.1.1/README.md +189 -0
  15. spotapi-2.1.1/README.pt-BR.md +189 -0
  16. spotapi-2.1.1/SECURITY.md +25 -0
  17. spotapi-2.1.1/SPONSORSHIP.md +75 -0
  18. {spotapi-2.1.0 → spotapi-2.1.1}/assets/README.md +3 -0
  19. spotapi-2.1.1/assets/cli-connect-demo.gif +0 -0
  20. spotapi-2.1.1/assets/lyrics-sync-demo.gif +0 -0
  21. spotapi-2.1.1/assets/social-preview.png +0 -0
  22. spotapi-2.1.1/assets/studio-demo.gif +0 -0
  23. {spotapi-2.1.0 → spotapi-2.1.1}/docs/account.md +21 -0
  24. {spotapi-2.1.0 → spotapi-2.1.1}/docs/api-layout.md +2 -3
  25. {spotapi-2.1.0 → spotapi-2.1.1}/docs/catalogue.md +10 -0
  26. spotapi-2.1.1/docs/connect.md +163 -0
  27. {spotapi-2.1.0 → spotapi-2.1.1}/docs/discovery.md +20 -2
  28. {spotapi-2.1.0 → spotapi-2.1.1}/docs/index.md +3 -2
  29. spotapi-2.1.1/docs/player-coverage.md +54 -0
  30. {spotapi-2.1.0 → spotapi-2.1.1}/docs/player.md +43 -3
  31. {spotapi-2.1.0 → spotapi-2.1.1}/docs/quickstart.md +13 -4
  32. spotapi-2.1.1/docs/release-checks.md +78 -0
  33. {spotapi-2.1.0 → spotapi-2.1.1}/docs/studio.md +7 -23
  34. {spotapi-2.1.0 → spotapi-2.1.1}/docs/transport.md +10 -0
  35. spotapi-2.1.1/docs/troubleshooting.md +78 -0
  36. spotapi-2.1.1/examples/README.md +43 -0
  37. spotapi-2.1.1/examples/playlist_audit.py +178 -0
  38. spotapi-2.1.1/examples/skip_next.py +17 -0
  39. spotapi-2.1.1/examples/taste_lab/README.md +196 -0
  40. spotapi-2.1.1/examples/taste_lab/VALIDATION.md +82 -0
  41. spotapi-2.1.1/examples/taste_lab/__init__.py +1 -0
  42. spotapi-2.1.1/examples/taste_lab/__main__.py +309 -0
  43. spotapi-2.1.1/examples/taste_lab/audio.py +142 -0
  44. spotapi-2.1.1/examples/taste_lab/engine.py +310 -0
  45. spotapi-2.1.1/examples/taste_lab/evaluate.py +98 -0
  46. spotapi-2.1.1/examples/taste_lab/extract.py +124 -0
  47. spotapi-2.1.1/examples/taste_lab/models.py +83 -0
  48. spotapi-2.1.1/examples/taste_lab/observe.py +88 -0
  49. spotapi-2.1.1/examples/taste_lab/requirements-audio.txt +7 -0
  50. spotapi-2.1.1/examples/taste_lab/smoke_audio.py +65 -0
  51. spotapi-2.1.1/examples/taste_lab/spotify.py +256 -0
  52. spotapi-2.1.1/examples/taste_lab/store.py +205 -0
  53. spotapi-2.1.1/examples/taste_lab/youtube.py +312 -0
  54. {spotapi-2.1.0 → spotapi-2.1.1}/mkdocs.yml +3 -2
  55. {spotapi-2.1.0 → spotapi-2.1.1}/pyproject.toml +2 -1
  56. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/__init__.py +3 -1
  57. spotapi-2.1.1/spotapi/__main__.py +6 -0
  58. spotapi-2.1.1/spotapi/_connect/__init__.py +1 -0
  59. spotapi-2.1.1/spotapi/_connect/app.py +838 -0
  60. spotapi-2.1.1/spotapi/_connect/auth.py +28 -0
  61. spotapi-2.1.1/spotapi/_connect/commands.py +127 -0
  62. spotapi-2.1.1/spotapi/_connect/presentation.py +101 -0
  63. spotapi-2.1.1/spotapi/_connect/queue.py +62 -0
  64. spotapi-2.1.1/spotapi/_connect/session.py +144 -0
  65. spotapi-2.1.1/spotapi/_connect/style.tcss +290 -0
  66. spotapi-2.1.1/spotapi/_connect/suggestions.py +51 -0
  67. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_decoding.py +11 -1
  68. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_demo/discover.py +27 -14
  69. spotapi-2.1.1/spotapi/_protocol/collection.py +56 -0
  70. spotapi-2.1.1/spotapi/_protocol/user_agent.py +231 -0
  71. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/actions.py +1 -1
  72. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/app.js +121 -35
  73. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/desktop.py +6 -2
  74. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/index.html +1 -1
  75. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/service.py +27 -32
  76. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/style.css +10 -0
  77. spotapi-2.1.1/spotapi/cli.py +571 -0
  78. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/client.py +6 -2
  79. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/command_state.py +22 -5
  80. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/connection/http.py +84 -20
  81. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/connection/types.py +0 -1
  82. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/datastruct/event_handler.py +11 -5
  83. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/devices.py +2 -1
  84. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/login.py +13 -3
  85. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/mcp.py +120 -23
  86. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/media.py +38 -13
  87. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/player.py +33 -8
  88. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/query.py +38 -14
  89. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/serialization.py +26 -4
  90. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/session.py +84 -30
  91. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/status.py +139 -63
  92. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/types/__init__.py +2 -0
  93. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/types/exceptions.py +5 -0
  94. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_auth_recovery.py +84 -2
  95. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_cli.py +80 -1
  96. spotapi-2.1.1/tests/test_connect_presentation.py +294 -0
  97. spotapi-2.1.1/tests/test_connect_terminal.py +341 -0
  98. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_data_contracts.py +10 -0
  99. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_discover_demo.py +50 -0
  100. spotapi-2.1.1/tests/test_documentation_entrypoints.py +147 -0
  101. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_lifecycle.py +37 -0
  102. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_live_catalogue.py +11 -1
  103. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_native_websocket.py +31 -1
  104. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_optional_features.py +152 -0
  105. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_player.py +344 -6
  106. spotapi-2.1.1/tests/test_playlist_audit_example.py +106 -0
  107. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_queries_parsing.py +28 -0
  108. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_studio.py +34 -0
  109. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_studio_browser.py +191 -0
  110. spotapi-2.1.1/tests/test_taste_audio.py +133 -0
  111. spotapi-2.1.1/tests/test_taste_import.py +85 -0
  112. spotapi-2.1.1/tests/test_taste_lab.py +291 -0
  113. spotapi-2.1.1/tests/test_taste_sources.py +68 -0
  114. spotapi-2.1.1/tests/test_user_agent.py +81 -0
  115. spotapi-2.1.0/.github/workflows/spotify-public.yml +0 -62
  116. spotapi-2.1.0/LEGAL_NOTICE.md +0 -44
  117. spotapi-2.1.0/MIGRATION.md +0 -97
  118. spotapi-2.1.0/README.md +0 -247
  119. spotapi-2.1.0/SPONSORSHIP.md +0 -65
  120. spotapi-2.1.0/docs/player-coverage.md +0 -103
  121. spotapi-2.1.0/docs/release-checks.md +0 -129
  122. spotapi-2.1.0/spotapi/cli.py +0 -302
  123. {spotapi-2.1.0 → spotapi-2.1.1}/.dockerignore +0 -0
  124. {spotapi-2.1.0 → spotapi-2.1.1}/.env.example +0 -0
  125. {spotapi-2.1.0 → spotapi-2.1.1}/.github/workflows/publish.yml +0 -0
  126. {spotapi-2.1.0 → spotapi-2.1.1}/.gitignore +0 -0
  127. {spotapi-2.1.0 → spotapi-2.1.1}/.readthedocs.yaml +0 -0
  128. {spotapi-2.1.0 → spotapi-2.1.1}/CODE_OF_CONDUCT.md +0 -0
  129. {spotapi-2.1.0 → spotapi-2.1.1}/Dockerfile.mcp +0 -0
  130. {spotapi-2.1.0 → spotapi-2.1.1}/LICENSE +0 -0
  131. {spotapi-2.1.0 → spotapi-2.1.1}/assets/cli-demo.gif +0 -0
  132. {spotapi-2.1.0 → spotapi-2.1.1}/assets/logo-inverse.svg +0 -0
  133. {spotapi-2.1.0 → spotapi-2.1.1}/assets/logo-mono.svg +0 -0
  134. {spotapi-2.1.0 → spotapi-2.1.1}/assets/spotapi-color.svg +0 -0
  135. {spotapi-2.1.0 → spotapi-2.1.1}/assets/spotapi-inverse.svg +0 -0
  136. {spotapi-2.1.0 → spotapi-2.1.1}/assets/spotapi-mono.svg +0 -0
  137. {spotapi-2.1.0 → spotapi-2.1.1}/assets/spotapi-reversed.svg +0 -0
  138. {spotapi-2.1.0 → spotapi-2.1.1}/benchmarks/review.py +0 -0
  139. {spotapi-2.1.0 → spotapi-2.1.1}/docs/from-spotipy.md +0 -0
  140. {spotapi-2.1.0 → spotapi-2.1.1}/docs/reference.md +0 -0
  141. {spotapi-2.1.0 → spotapi-2.1.1}/docs/stylesheets/extra.css +0 -0
  142. {spotapi-2.1.0 → spotapi-2.1.1}/examples/__init__.py +0 -0
  143. {spotapi-2.1.0 → spotapi-2.1.1}/examples/credit_trail.py +0 -0
  144. {spotapi-2.1.0 → spotapi-2.1.1}/examples/credits.py +0 -0
  145. {spotapi-2.1.0 → spotapi-2.1.1}/examples/custom_transport.py +0 -0
  146. {spotapi-2.1.0 → spotapi-2.1.1}/examples/discover.py +0 -0
  147. {spotapi-2.1.0 → spotapi-2.1.1}/examples/export.py +0 -0
  148. {spotapi-2.1.0 → spotapi-2.1.1}/examples/lookup.py +0 -0
  149. {spotapi-2.1.0 → spotapi-2.1.1}/examples/lyrics.py +0 -0
  150. {spotapi-2.1.0 → spotapi-2.1.1}/examples/mix_map.py +0 -0
  151. {spotapi-2.1.0 → spotapi-2.1.1}/examples/overlap.py +0 -0
  152. {spotapi-2.1.0 → spotapi-2.1.1}/examples/pagination.py +0 -0
  153. {spotapi-2.1.0 → spotapi-2.1.1}/examples/player.py +0 -0
  154. {spotapi-2.1.0 → spotapi-2.1.1}/examples/playlist_crate.py +0 -0
  155. {spotapi-2.1.0 → spotapi-2.1.1}/examples/public_search.py +0 -0
  156. {spotapi-2.1.0 → spotapi-2.1.1}/examples/quickstart.py +0 -0
  157. {spotapi-2.1.0 → spotapi-2.1.1}/examples/studio/__init__.py +0 -0
  158. {spotapi-2.1.0 → spotapi-2.1.1}/examples/studio/__main__.py +0 -0
  159. {spotapi-2.1.0 → spotapi-2.1.1}/examples/studio/preview.png +0 -0
  160. {spotapi-2.1.0 → spotapi-2.1.1}/examples/taste.py +0 -0
  161. {spotapi-2.1.0 → spotapi-2.1.1}/requirements-docs.txt +0 -0
  162. {spotapi-2.1.0 → spotapi-2.1.1}/requirements.txt +0 -0
  163. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_demo/__init__.py +0 -0
  164. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_demo/details.py +0 -0
  165. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_parsing.py +0 -0
  166. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_protocol/__init__.py +0 -0
  167. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_protocol/bundles.py +0 -0
  168. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_protocol/embeds.py +0 -0
  169. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_protocol/protobuf.py +0 -0
  170. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_protocol/routes.py +0 -0
  171. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_protocol/totp.py +0 -0
  172. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/__init__.py +0 -0
  173. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/assets/logo.ico +0 -0
  174. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/assets/logo.png +0 -0
  175. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/assets/logo.svg +0 -0
  176. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/_studio/lyrics.py +0 -0
  177. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/account.py +0 -0
  178. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/account_session.py +0 -0
  179. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/batch.py +0 -0
  180. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/blend.py +0 -0
  181. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/cache.py +0 -0
  182. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/captcha.py +0 -0
  183. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/catalogue.py +0 -0
  184. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/charts.py +0 -0
  185. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/connect.py +0 -0
  186. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/connection/__init__.py +0 -0
  187. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/connection/client.py +0 -0
  188. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/connection/websocket.py +0 -0
  189. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/datastruct/__init__.py +0 -0
  190. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/datastruct/object_dict.py +0 -0
  191. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/datastruct/pool.py +0 -0
  192. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/embeds.py +0 -0
  193. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/history.py +0 -0
  194. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/library.py +0 -0
  195. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/lyrics.py +0 -0
  196. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/__init__.py +0 -0
  197. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/account.py +0 -0
  198. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/batch.py +0 -0
  199. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/blend.py +0 -0
  200. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/__init__.py +0 -0
  201. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/album.py +0 -0
  202. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/album_details.py +0 -0
  203. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/artist.py +0 -0
  204. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/artist_details.py +0 -0
  205. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/common.py +0 -0
  206. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/credits.py +0 -0
  207. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/entities.py +0 -0
  208. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/playlist.py +0 -0
  209. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/playlist_details.py +0 -0
  210. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/playlist_track.py +0 -0
  211. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/podcast.py +0 -0
  212. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/podcast_episode.py +0 -0
  213. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/profile_attributes.py +0 -0
  214. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/track.py +0 -0
  215. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/catalogue/track_details.py +0 -0
  216. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/discovery.py +0 -0
  217. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/embeds.py +0 -0
  218. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/history.py +0 -0
  219. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/library.py +0 -0
  220. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/lyrics.py +0 -0
  221. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/notifications.py +0 -0
  222. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/playback.py +0 -0
  223. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/profiles.py +0 -0
  224. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/search.py +0 -0
  225. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/sessions.py +0 -0
  226. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/stats.py +0 -0
  227. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/models/transcripts.py +0 -0
  228. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/notifications.py +0 -0
  229. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/operations.py +0 -0
  230. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/password.py +0 -0
  231. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/playlist.py +0 -0
  232. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/profiles.py +0 -0
  233. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/public.py +0 -0
  234. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/py.typed +0 -0
  235. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/queries.py +0 -0
  236. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/resources.py +0 -0
  237. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/stats.py +0 -0
  238. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/sync.py +0 -0
  239. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/transcripts.py +0 -0
  240. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/types/logger.py +0 -0
  241. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/utils/__init__.py +0 -0
  242. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/utils/cache.py +0 -0
  243. {spotapi-2.1.0 → spotapi-2.1.1}/spotapi/utils/random.py +0 -0
  244. {spotapi-2.1.0 → spotapi-2.1.1}/tests/README.md +0 -0
  245. {spotapi-2.1.0 → spotapi-2.1.1}/tests/conftest.py +0 -0
  246. {spotapi-2.1.0 → spotapi-2.1.1}/tests/fixtures/connect/message-1.json +0 -0
  247. {spotapi-2.1.0 → spotapi-2.1.1}/tests/fixtures/connect/message-2.json +0 -0
  248. {spotapi-2.1.0 → spotapi-2.1.1}/tests/fixtures/connect/message-3.json +0 -0
  249. {spotapi-2.1.0 → spotapi-2.1.1}/tests/fixtures/connect/message-4.json +0 -0
  250. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_account.py +0 -0
  251. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_account_content.py +0 -0
  252. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_artist_details_model.py +0 -0
  253. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_authorized_requests.py +0 -0
  254. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_bundle_cache.py +0 -0
  255. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_catalogue_lifecycle.py +0 -0
  256. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_discovery_parser.py +0 -0
  257. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_feature_parity.py +0 -0
  258. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_listening.py +0 -0
  259. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_live.py +0 -0
  260. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_live_account.py +0 -0
  261. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_live_controls.py +0 -0
  262. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_live_discovery.py +0 -0
  263. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_live_player.py +0 -0
  264. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_live_playlists.py +0 -0
  265. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_live_studio.py +0 -0
  266. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_mutations.py +0 -0
  267. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_operations.py +0 -0
  268. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_protobuf.py +0 -0
  269. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_public_api.py +0 -0
  270. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_public_catalogue.py +0 -0
  271. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_review_regressions.py +0 -0
  272. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_routes.py +0 -0
  273. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_search_models.py +0 -0
  274. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_transport.py +0 -0
  275. {spotapi-2.1.0 → spotapi-2.1.1}/tests/test_websocket_lifecycle.py +0 -0
@@ -0,0 +1,109 @@
1
+ name: Bug report
2
+ description: Report reproducible behavior that differs from SpotAPI's documented contract.
3
+ title: "[Bug]: "
4
+ labels: ["bug"]
5
+ body:
6
+ - type: markdown
7
+ attributes:
8
+ value: |
9
+ Thanks for helping improve SpotAPI. Do not include Spotify cookies, access tokens, passwords, or private playlist data.
10
+ Report security vulnerabilities privately using the repository's security policy.
11
+
12
+ - type: textarea
13
+ id: summary
14
+ attributes:
15
+ label: What happened?
16
+ description: Describe the problem and the user-visible effect.
17
+ validations:
18
+ required: true
19
+
20
+ - type: textarea
21
+ id: reproduction
22
+ attributes:
23
+ label: Minimal reproduction
24
+ description: Include the smallest script or command that reproduces the problem. Replace private IDs and credentials.
25
+ validations:
26
+ required: true
27
+
28
+ - type: textarea
29
+ id: expected
30
+ attributes:
31
+ label: Expected behavior
32
+ description: What did you expect SpotAPI to return or do?
33
+ validations:
34
+ required: true
35
+
36
+ - type: textarea
37
+ id: actual
38
+ attributes:
39
+ label: Actual behavior
40
+ description: Include the complete exception type and message when applicable.
41
+ validations:
42
+ required: true
43
+
44
+ - type: input
45
+ id: spotapi-version
46
+ attributes:
47
+ label: SpotAPI version
48
+ description: Run `python -m pip show spotapi` in the application's environment and paste the Version line. On Windows, use `py -m pip show spotapi` if you installed with `py`.
49
+ placeholder: spotapi 2.1.0
50
+ validations:
51
+ required: true
52
+
53
+ - type: input
54
+ id: python-version
55
+ attributes:
56
+ label: Python version
57
+ description: Run `python --version` in the same environment.
58
+ placeholder: Python 3.12.7
59
+ validations:
60
+ required: true
61
+
62
+ - type: dropdown
63
+ id: area
64
+ attributes:
65
+ label: Area
66
+ options:
67
+ - Public catalogue
68
+ - Account or library
69
+ - Playlists
70
+ - Player or live events
71
+ - Command-line interface
72
+ - Discover terminal UI
73
+ - Studio
74
+ - Transport or authentication
75
+ - Models, typing, or serialization
76
+ - Other
77
+ validations:
78
+ required: true
79
+
80
+ - type: dropdown
81
+ id: operating-system
82
+ attributes:
83
+ label: Operating system
84
+ options:
85
+ - Windows
86
+ - macOS
87
+ - Linux
88
+ - Other
89
+ validations:
90
+ required: true
91
+
92
+ - type: textarea
93
+ id: logs
94
+ attributes:
95
+ label: Relevant logs
96
+ description: Optional. Remove credentials, cookies, tokens, and private identifiers before pasting output.
97
+ render: shell
98
+
99
+ - type: checkboxes
100
+ id: checks
101
+ attributes:
102
+ label: Checklist
103
+ options:
104
+ - label: I searched existing issues and discussions for this problem.
105
+ required: true
106
+ - label: I reproduced this on the latest SpotAPI release, or explained why I could not.
107
+ required: true
108
+ - label: I removed all credentials and private account data.
109
+ required: true
@@ -0,0 +1,11 @@
1
+ blank_issues_enabled: false
2
+ contact_links:
3
+ - name: Questions and project ideas
4
+ url: https://github.com/Aran404/SpotAPI/discussions
5
+ about: Ask for help, share what you built, or discuss an idea before proposing an API change.
6
+ - name: Documentation
7
+ url: https://spotapi.readthedocs.io/
8
+ about: Read the quickstart, guides, migration notes, and Python API reference.
9
+ - name: Security vulnerability
10
+ url: https://github.com/Aran404/SpotAPI/security/policy
11
+ about: Follow the private reporting instructions instead of opening a public issue.
@@ -0,0 +1,66 @@
1
+ name: Feature request
2
+ description: Propose a focused workflow or API improvement for SpotAPI.
3
+ title: "[Feature]: "
4
+ labels: ["enhancement"]
5
+ body:
6
+ - type: markdown
7
+ attributes:
8
+ value: |
9
+ Start with the user problem. New surface area must earn its complexity and should reuse existing typed APIs where possible.
10
+
11
+ - type: textarea
12
+ id: problem
13
+ attributes:
14
+ label: What problem would this solve?
15
+ description: Describe the workflow that is difficult or impossible today.
16
+ validations:
17
+ required: true
18
+
19
+ - type: textarea
20
+ id: proposal
21
+ attributes:
22
+ label: Proposed behavior
23
+ description: Show the command or Python API you would expect to use.
24
+ validations:
25
+ required: true
26
+
27
+ - type: dropdown
28
+ id: area
29
+ attributes:
30
+ label: Area
31
+ options:
32
+ - Public catalogue
33
+ - Account or library
34
+ - Playlists
35
+ - Player or live events
36
+ - Command-line interface
37
+ - Discover terminal UI
38
+ - Studio
39
+ - Documentation or examples
40
+ - Other
41
+ validations:
42
+ required: true
43
+
44
+ - type: textarea
45
+ id: alternatives
46
+ attributes:
47
+ label: Alternatives considered
48
+ description: Explain existing SpotAPI methods or external tools you tried.
49
+
50
+ - type: textarea
51
+ id: scope
52
+ attributes:
53
+ label: Scope and tradeoffs
54
+ description: Note authentication, Premium, platform, dependency, or unofficial-endpoint requirements.
55
+
56
+ - type: checkboxes
57
+ id: checks
58
+ attributes:
59
+ label: Checklist
60
+ options:
61
+ - label: I searched existing issues and discussions for this request.
62
+ required: true
63
+ - label: This request describes a user workflow, not only an endpoint or feature count.
64
+ required: true
65
+ - label: I understand Spotify may not expose or permit every requested operation.
66
+ required: true
@@ -0,0 +1,25 @@
1
+ ## Summary
2
+
3
+ <!-- What changed? Keep this concrete. -->
4
+
5
+ ## Why
6
+
7
+ <!-- Link the issue and explain the user-visible outcome. -->
8
+
9
+ Closes #
10
+
11
+ ## Verification
12
+
13
+ <!-- List the commands or manual checks you ran. -->
14
+
15
+ - [ ] Tests cover the changed behavior, or the reason they do not is explained above.
16
+ - [ ] `python -m pytest -q`
17
+ - [ ] `python -m pyright`
18
+ - [ ] `python -m ruff check .`
19
+ - [ ] `python -m black --check .`
20
+ - [ ] Public behavior changes include concise documentation or changelog updates.
21
+ - [ ] No credentials, cookies, access tokens, or private account data are included.
22
+
23
+ ## Contract and lifecycle notes
24
+
25
+ <!-- For network, authentication, player, or background-task changes: describe retries, ownership, cancellation, cleanup, and mutation safety. Delete this section when it is not relevant. -->
@@ -2,6 +2,7 @@ name: Documentation
2
2
 
3
3
  on:
4
4
  push:
5
+ branches: [main]
5
6
  pull_request:
6
7
  workflow_dispatch:
7
8
 
@@ -0,0 +1,119 @@
1
+ name: Spotify API checks
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ schedule:
8
+ - cron: "17 8 * * *" # Daily contract check; reports upstream breaking changes
9
+ workflow_dispatch:
10
+
11
+ jobs:
12
+ offline:
13
+ runs-on: ${{ matrix.os }}
14
+ timeout-minutes: 15
15
+ strategy:
16
+ fail-fast: false
17
+ matrix:
18
+ os: [ubuntu-latest]
19
+ python: ["3.11", "3.12", "3.13"]
20
+ include:
21
+ - os: windows-latest
22
+ python: "3.12"
23
+ - os: macos-latest
24
+ python: "3.12"
25
+ steps:
26
+ - uses: actions/checkout@v4
27
+ - uses: actions/setup-python@v5
28
+ with:
29
+ python-version: ${{ matrix.python }}
30
+ - run: python -m pip install -e '.[dev,demo]'
31
+ - run: python -m coverage run -m pytest -m 'not live'
32
+ - run: python -m coverage report
33
+ - run: python -m coverage xml
34
+ - uses: actions/upload-artifact@v4
35
+ with:
36
+ name: coverage-${{ matrix.os }}-python-${{ matrix.python }}
37
+ path: coverage.xml
38
+ - run: python -m pyright
39
+ - run: python -m ruff check .
40
+ - run: python -m black --check --diff .
41
+
42
+ installed-wheel:
43
+ runs-on: ${{ matrix.os }}
44
+ timeout-minutes: 10
45
+ strategy:
46
+ fail-fast: false
47
+ matrix:
48
+ os: [ubuntu-latest, windows-latest, macos-latest]
49
+ steps:
50
+ - uses: actions/checkout@v4
51
+ - uses: actions/setup-python@v5
52
+ with:
53
+ python-version: "3.12"
54
+ - run: python -m pip install build
55
+ - run: python -m build --wheel
56
+ - name: Install and smoke-test outside the checkout
57
+ shell: pwsh
58
+ run: |
59
+ $wheel = (Get-ChildItem dist/*.whl).FullName
60
+ python -m pip install "$($wheel)[connect]"
61
+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
62
+ Set-Location $env:RUNNER_TEMP
63
+ spotapi --version
64
+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
65
+ python -I -m spotapi --version
66
+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
67
+ python -I -m spotapi discover --help
68
+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
69
+ python -I -m spotapi studio --help
70
+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
71
+ python -I -m spotapi connect --help
72
+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
73
+ python -I -c "import textual, keyring; from spotapi._connect.app import ConnectApp; assert ConnectApp"
74
+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
75
+ python -I -c "from importlib.resources import files; root = files('spotapi'); assert root.joinpath('py.typed').is_file(); assert root.joinpath('_studio', 'app.js').is_file()"
76
+
77
+ public-api:
78
+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
79
+ runs-on: ubuntu-latest
80
+ timeout-minutes: 15
81
+ steps:
82
+ - uses: actions/checkout@v4
83
+ - uses: actions/setup-python@v5
84
+ with:
85
+ python-version: "3.12"
86
+ - run: python -m pip install -e '.[dev]'
87
+ - name: Verify public Spotify contracts
88
+ run: python -m pytest --live=read -m "live and not authenticated" -vv -rs
89
+
90
+ account-api:
91
+ if: github.event_name == 'workflow_dispatch' && github.repository == 'Aran404/SpotAPI'
92
+ runs-on: ubuntu-latest
93
+ timeout-minutes: 15
94
+ steps:
95
+ - uses: actions/checkout@v4
96
+ - uses: actions/setup-python@v5
97
+ with:
98
+ python-version: "3.12"
99
+ - run: python -m pip install -e '.[dev]'
100
+ - name: Verify authenticated read contracts
101
+ env:
102
+ SPOTIFY_COOKIE: ${{ secrets.SPOTIFY_CANARY_COOKIE }}
103
+ run: |
104
+ if [ -z "$SPOTIFY_COOKIE" ]; then
105
+ echo "::notice::Authenticated canary skipped because SPOTIFY_CANARY_COOKIE is not configured."
106
+ exit 0
107
+ fi
108
+ python -m pytest --live=read -m "live and authenticated and not mutates" -vv -rs
109
+
110
+ studio-ui:
111
+ runs-on: ubuntu-latest
112
+ steps:
113
+ - uses: actions/checkout@v4
114
+ - uses: actions/setup-python@v5
115
+ with:
116
+ python-version: "3.12"
117
+ - run: python -m pip install -e '.[dev]'
118
+ - run: python -m playwright install --with-deps chromium
119
+ - run: python -m pytest tests/test_studio.py tests/test_studio_browser.py -q
@@ -1,7 +1,36 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.1.1 - Pending release
4
+
5
+ - Add the installable `connect` optional extra and verify its installed wheel
6
+ on Linux, Windows and macOS; clarify browser sign-in requirements (#94).
7
+ - Add a bounded, streaming, offline-tested public playlist CSV auditor (#95).
8
+ - Improve the README's first Python example and make the Studio screenshot
9
+ lightweight; retain the lyrics animation as an optional link.
10
+ - Fix outdated quickstart/release documentation and avoid duplicate CI runs
11
+ when a feature branch has an open pull request.
12
+
13
+ - Add `Player.current_track_details()` for explicit current-track metadata.
14
+ - Reconnect after transient grouped cleanup failures and report `disconnect`
15
+ on broken dealer connections.
16
+ - Raise `LoginExpired` for missing or rejected Spotify cookie sessions.
17
+ - Emit `library_change` for server collection notifications, including changes
18
+ from other clients, with local/server echoes deduplicated.
19
+ - Add opt-in MCP playback and like tools through `--allow-player`.
20
+ - Preserve authentication failures when cleanup also fails, and keep permanent
21
+ connection failures visible alongside transient cleanup errors.
22
+ - Prevent late like confirmations from overriding newer collection events.
23
+ - Expose public search locale selection through CLI `--language` (#88).
24
+
25
+ - Send Connect commands from the registered controller to the selected player.
26
+ This fixes accepted commands that left playback unchanged and then timed out
27
+ when the active player was also used as the command source (#91).
28
+
3
29
  ## 2.1.0 - 2026-11-13
4
30
 
31
+ Engineering notes: [I wrote a Python library at 16. Here are 5 things I'd fix
32
+ in the async rewrite](https://dev.to/aran404/i-wrote-a-python-library-at-16-here-are-5-things-id-fix-in-the-async-rewrite-4p62).
33
+
5
34
  ### Added
6
35
 
7
36
  - Launch the packaged desktop application with `spotapi studio` after installing
@@ -23,12 +52,16 @@
23
52
  - Managed account scopes accept explicit proxy and language options.
24
53
  - Keep sponsorship placements below usage material, with optional integration
25
54
  partnerships and privately quoted scope.
55
+ - Report the installed distribution with `spotapi --version` so executable and
56
+ package mismatches are immediately visible.
26
57
  - Require `wreq` 0.12.3 or newer within the compatible 0.12 release line for
27
58
  corrected coroutine cancellation; 0.13 remains excluded because it changes
28
59
  binary response types.
29
60
 
30
61
  ### Fixed
31
62
 
63
+ - Replace the migration page's intermediate-branch internals with verified
64
+ `spotapi==1.2.8` examples, feature differences and removed-workflow boundaries.
32
65
  - Dealer disconnects wake command waiters and clear readiness; temporary device
33
66
  loss no longer discards a valid late ACK. Quiet dealers allow one snapshot
34
67
  refresh within the existing deadline; old snapshots cannot prove success.
@@ -34,6 +34,18 @@ ownership, cancellation, partial payloads, and retry safety when changing
34
34
  network behavior. Keep optional metadata optional. A new background task
35
35
  needs an owner, a retained reference, observable failures, and shutdown.
36
36
 
37
+ When a Spotify response changes, start at the operation name in
38
+ `spotapi/operations.py`. Check its route and replay policy, then find the
39
+ extractor used by its caller. For example, catalogue playlist items select
40
+ `playlistV2.content` before decoding individual occurrences. Add a sanitized
41
+ fixture with the original and changed envelope and run the narrow parser
42
+ test before running live reads. Keep missing required fields separate
43
+ from empty lists and omitted optional metadata.
44
+
45
+ For readability, use a blank line between independent branches and between
46
+ validation, I/O, and publication. Keep cleanup next to its owner. Preserve
47
+ the order of validation and side effects when moving code.
48
+
37
49
  The package uses Hatch and `pyproject.toml` as its packaging source of truth.
38
50
  Keep `requirements.txt` consistent with the tested wreq pin. Check a wheel
39
51
  with `python -m pip wheel . --no-deps` when changing packaging.
@@ -46,6 +58,11 @@ Do not infer network speedups from the offline ownership comparison.
46
58
  See the [API layout](docs/api-layout.md) for module responsibilities and
47
59
  ownership. Follow the [code of conduct](CODE_OF_CONDUCT.md).
48
60
 
61
+ ## Picking up an issue
62
+
63
+ Comment on the issue with a short note on how you plan to approach it, and wait for me to assign it before opening a PR. PRs for unassigned labeled issues may be closed.
64
+
65
+ Every PR should include a test and a description of how you checked it. AI-assisted work is welcome, but you're responsible for understanding it and for running it.
49
66
 
50
67
  ## Documentation
51
68
 
@@ -59,8 +76,5 @@ python -m mkdocs build --strict
59
76
  python -m mkdocs serve
60
77
  ```
61
78
 
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.
79
+ Keep exploratory captures and personal audit notes outside the repository.
80
+ Do not add credentials or account identifiers to examples, logs or screenshots.
@@ -0,0 +1,36 @@
1
+ # Legal notice
2
+
3
+ SpotAPI is an independent, community-maintained open-source project. It is not
4
+ affiliated with, authorized by, sponsored by, or endorsed by Spotify or its
5
+ affiliates. Spotify and related names and marks belong to their respective owners
6
+ and are used here only to identify the service with which the project interacts.
7
+
8
+ ## Third-party services
9
+
10
+ SpotAPI interacts with Spotify's services, including undocumented web-player
11
+ interfaces. Availability of this code does not imply that Spotify authorizes
12
+ any particular use. Access to third-party services may be governed by their terms,
13
+ technical restrictions, and applicable laws. Users and developers should assess
14
+ those obligations before using or distributing integrations built with SpotAPI.
15
+
16
+ Features can stop working or be restricted when Spotify changes its services,
17
+ policies, or account entitlements. SpotAPI does not guarantee uninterrupted
18
+ access to any third-party API.
19
+
20
+ ## Licensing and warranties
21
+
22
+ SpotAPI's independently authored source code is distributed under the
23
+ [GNU General Public License version 3](LICENSE). See the license for its terms,
24
+ including the applicable disclaimers of warranty and liability. The project is
25
+ provided without a guarantee of fitness, accuracy, availability, or compatibility.
26
+
27
+ This notice does not grant rights in Spotify's intellectual property, amend
28
+ Spotify's terms, limit the rights of any third party, or guarantee that a particular
29
+ use of SpotAPI is permitted by law. It does not replace professional legal advice.
30
+
31
+ ## Reporting concerns
32
+
33
+ If you believe material in this repository infringes your rights or requires
34
+ correction, please contact the maintainer through the repository's public
35
+ [issue tracker](https://github.com/Aran404/SpotAPI/issues), without posting
36
+ credentials, private account information, or confidential legal documents.
@@ -0,0 +1,197 @@
1
+ # Migrating from SpotAPI 1.2.8
2
+
3
+ SpotAPI 2 is a rewrite, not a drop-in update. The published 1.2.8 package was
4
+ synchronous, split features across classes such as `Song`, `Artist` and
5
+ `PublicPlaylist`, and returned Spotify's nested dictionaries. SpotAPI 2 has an
6
+ async core, typed results and explicit client lifetimes. It also provides
7
+ `SyncCatalogue` for ordinary synchronous scripts.
8
+
9
+ This guide compares the published `spotapi==1.2.8` wheel with SpotAPI 2. It does
10
+ not describe the unpublished `async-v2` development branch.
11
+
12
+ ## Decide whether to migrate
13
+
14
+ Use a fresh virtual environment for either version. Keep 1.2.8 pinned while you
15
+ migrate an existing application:
16
+
17
+ ```sh
18
+ python -m pip install "spotapi==1.2.8"
19
+ ```
20
+
21
+ Install the current release in the new environment:
22
+
23
+ ```sh
24
+ python -m pip install "spotapi>=2,<3"
25
+ ```
26
+
27
+ SpotAPI 2 requires Python 3.11 or newer.
28
+
29
+ ## Why migrate?
30
+
31
+ These are observable API differences, not performance claims.
32
+
33
+ | Area | SpotAPI 1.2.8 | SpotAPI 2 |
34
+ |---|---|---|
35
+ | I/O model | Synchronous feature classes | Async-native API, plus the `SyncCatalogue` facade |
36
+ | Results | Raw nested mappings | Typed models with attributes and explicit optional fields |
37
+ | Connection ownership | Feature objects and a global public client pool | `async with` / `with` scopes with deterministic cleanup |
38
+ | Public catalogue | Tracks, artists, albums, playlists, podcasts and episodes | Those resources plus audiobooks, chapters, profiles, charts, concerts, radio, credits, Canvas, colors, transcripts and embeds |
39
+ | Search | Separate class methods and raw search envelopes | One typed multi-category search with category-specific helpers and iterators |
40
+ | Account access | Email/password `Login`, mutable feature objects and bundled CAPTCHA vendors | Cookie or browser login, composed account helpers and a provider-neutral CAPTCHA protocol |
41
+ | Player | Synchronous controls and a threaded event listener | Async controls, typed state, reconnecting event scopes, `wait_for` and explicit shutdown |
42
+ | Playlist edits | Stateful playlist IDs and raw mappings | Typed playlists and occurrence-aware edits using Spotify item UIDs |
43
+ | Tooling | Python API only | Scriptable CLI, optional Discover TUI, Studio desktop app and MCP server |
44
+
45
+ The wider surface does not make every v1 workflow portable. SpotAPI 2 does not
46
+ retain v1's account registration, family-membership automation, email/password
47
+ login, database saver classes, or bundled Capsolver/Capmonster clients. Use an
48
+ existing Spotify session for authenticated v2 features. If your application
49
+ depends on a removed workflow, keep 1.2.8 isolated until you replace it.
50
+
51
+ ## Search
52
+
53
+ Version 1.2.8 returned Spotify's raw search envelope:
54
+
55
+ ```python
56
+ from spotapi import Song
57
+
58
+ songs = Song().query_songs("weezer", limit=20)
59
+ items = songs["data"]["searchV2"]["tracksV2"]["items"]
60
+ for item in items:
61
+ print(item["item"]["data"]["name"])
62
+ ```
63
+
64
+ The native SpotAPI 2 API is asynchronous and returns typed results:
65
+
66
+ ```python
67
+ import asyncio
68
+
69
+ from spotapi import Public
70
+
71
+
72
+ async def main() -> None:
73
+ results = await Public.search("weezer", types="track", limit=20)
74
+ for track in results.tracks:
75
+ print(track.name, track.uri)
76
+
77
+
78
+ asyncio.run(main())
79
+ ```
80
+
81
+ For a synchronous script, use the same result models through
82
+ `SyncCatalogue`:
83
+
84
+ ```python
85
+ from spotapi import SyncCatalogue
86
+
87
+ with SyncCatalogue() as spotify:
88
+ results = spotify.search("weezer", types="track", limit=20)
89
+ for track in results.tracks:
90
+ print(track.name, track.uri)
91
+ ```
92
+
93
+ Do not use `SyncCatalogue` from a running event loop. In async applications and
94
+ notebooks with an active loop, use `await Public.search(...)` or
95
+ `async with Catalogue()`.
96
+
97
+ ## Common public operations
98
+
99
+ | 1.2.8 | SpotAPI 2 async | SpotAPI 2 sync |
100
+ |---|---|---|
101
+ | `Song().query_songs(query, limit=20)` | `await Public.search(query, types="track", limit=20)` | `spotify.search(query, types="track", limit=20)` |
102
+ | `Song().paginate_songs(query)` | `async for track in Public.iter_tracks(query)` | Not exposed as an unbounded iterator; page with the async API when needed |
103
+ | `Song().get_track_info(track_id)` | `await Public.get_track(track_id)` | `spotify.get_track(track_id)` |
104
+ | `Artist().query_artists(query, limit=20)` | `await Public.search(query, types="artist", limit=20)` | `spotify.search(query, types="artist", limit=20)` |
105
+ | `Artist().get_artist(artist_id)` | `await Public.get_artist(artist_id)` | `spotify.get_artist(artist_id)` |
106
+ | `PublicAlbum(album_id).get_album_info()` | `await Public.get_album(album_id)` | `spotify.get_album(album_id)` |
107
+ | `PublicPlaylist(playlist_id).get_playlist_info()` | `await Public.get_playlist(playlist_id)` | `spotify.get_playlist(playlist_id)` |
108
+ | `Podcast(podcast_id).get_podcast_info()` | `await Public.get_podcast(podcast_id)` | `spotify.get_podcast(podcast_id)` |
109
+ | `Podcast().get_episode(episode_id)` | `await Public.get_podcast_episode(episode_id)` | `spotify.get_podcast_episode(episode_id)` |
110
+
111
+ IDs, Spotify URIs and open.spotify.com URLs are accepted by the documented v2
112
+ lookup methods. Returned models are values: reading `track.name` performs no
113
+ network request. Use `spotapi.to_dict()` when an application needs JSON-safe
114
+ dictionaries.
115
+
116
+ ## Reuse connections
117
+
118
+ `Public` is convenient for unrelated one-shot calls. Reuse a `Catalogue` when
119
+ several operations belong to one workflow:
120
+
121
+ ```python
122
+ from spotapi import Catalogue
123
+
124
+
125
+ async def inspect_artist(artist_uri: str) -> None:
126
+ async with Catalogue() as spotify:
127
+ artist = await spotify.get_artist(artist_uri)
128
+ top_tracks = await spotify.get_artist_top_tracks(artist.uri)
129
+ print(artist.name, len(top_tracks))
130
+ ```
131
+
132
+ Page iterators are async generators. If a loop may stop early, close it
133
+ explicitly with `contextlib.aclosing`.
134
+
135
+ ## Authentication and account features
136
+
137
+ Version 1.2.8 constructed `Login` from an email or username, password, solver
138
+ configuration and an optional saver. SpotAPI 2 does not accept account
139
+ passwords. It uses an existing Spotify web session:
140
+
141
+ ```python
142
+ import os
143
+
144
+ from spotapi import Private
145
+
146
+
147
+ async def show_profile() -> None:
148
+ async with Private.from_cookies(os.environ["SPOTIFY_COOKIE"]) as account:
149
+ profile = await account.get_profile()
150
+ print(profile)
151
+ ```
152
+
153
+ For an interactive application, use `browser_login()` with `SavedSession`
154
+ instead of collecting credentials. Never print, commit or send the Spotify
155
+ cookie to another service.
156
+
157
+ Authenticated helpers borrow their client. The surrounding `Private` or
158
+ `AsyncClient` context owns token refresh, transports and shutdown. Playlist and
159
+ player mutations are not automatically replayed after an ambiguous failure;
160
+ read the resulting state before deciding whether to retry.
161
+
162
+ ## Player events and controls
163
+
164
+ The v1 `Player` and `EventManager` were synchronous and built on a background
165
+ listener. V2 event callbacks and controls are async and live inside an explicit
166
+ connection scope:
167
+
168
+ ```python
169
+ from spotapi import AsyncClient, Player
170
+
171
+
172
+ async def watch_player(cookie: str) -> None:
173
+ async with await AsyncClient.from_cookies(cookie) as client:
174
+ player = Player(client)
175
+
176
+ @player.event
177
+ async def on_track_change(before, after) -> None:
178
+ if after is not None:
179
+ print(after.artist, after.name)
180
+
181
+ async with player.connect():
182
+ await player.pause()
183
+ await player.resume()
184
+ ```
185
+
186
+ Important renames include `skip_next()` to `next()`, `skip_prev()` to
187
+ `previous()`, `seek_to()` to `seek()`, `set_shuffle()` to `shuffle()`, and
188
+ `set_volume()` to `volume()`. V2 repeat mode is `"off"`, `"context"` or
189
+ `"track"`, rather than a boolean.
190
+
191
+ ## Read next
192
+
193
+ - [First result](https://spotapi.readthedocs.io/en/latest/quickstart/)
194
+ - [Catalogue and search](https://spotapi.readthedocs.io/en/latest/catalogue/)
195
+ - [Accounts and playlists](https://spotapi.readthedocs.io/en/latest/account/)
196
+ - [Player controls and events](https://spotapi.readthedocs.io/en/latest/player/)
197
+ - [Python API reference](https://spotapi.readthedocs.io/en/latest/reference/)