spotapi 1.2.7__tar.gz → 2.0.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 (212) hide show
  1. spotapi-2.0.0/.env.example +4 -0
  2. spotapi-2.0.0/.github/workflows/publish.yml +65 -0
  3. spotapi-2.0.0/.github/workflows/spotify-public.yml +48 -0
  4. spotapi-2.0.0/.gitignore +177 -0
  5. spotapi-2.0.0/CHANGELOG.md +59 -0
  6. spotapi-2.0.0/CODE_OF_CONDUCT.md +128 -0
  7. spotapi-2.0.0/CONTRIBUTING.md +44 -0
  8. spotapi-2.0.0/LEGAL_NOTICE.md +46 -0
  9. {spotapi-1.2.7 → spotapi-2.0.0}/LICENSE +674 -674
  10. spotapi-2.0.0/MIGRATION.md +79 -0
  11. spotapi-2.0.0/PKG-INFO +873 -0
  12. spotapi-2.0.0/README.md +156 -0
  13. spotapi-2.0.0/SPONSORSHIP.md +23 -0
  14. spotapi-2.0.0/assets/README.md +10 -0
  15. spotapi-2.0.0/assets/cli-demo.gif +0 -0
  16. spotapi-2.0.0/assets/logo-inverse.svg +38 -0
  17. spotapi-2.0.0/assets/logo-mono.svg +38 -0
  18. spotapi-2.0.0/assets/logo.ico +0 -0
  19. spotapi-2.0.0/assets/logo.png +0 -0
  20. spotapi-2.0.0/assets/logo.svg +48 -0
  21. spotapi-2.0.0/assets/spotapi-color.svg +48 -0
  22. spotapi-2.0.0/assets/spotapi-inverse.svg +48 -0
  23. spotapi-2.0.0/assets/spotapi-mono.svg +48 -0
  24. spotapi-2.0.0/assets/spotapi-reversed.svg +48 -0
  25. spotapi-2.0.0/benchmarks/review.py +394 -0
  26. spotapi-2.0.0/docs/account.md +92 -0
  27. spotapi-2.0.0/docs/api-layout.md +39 -0
  28. spotapi-2.0.0/docs/catalogue.md +47 -0
  29. spotapi-2.0.0/docs/player-coverage.md +103 -0
  30. spotapi-2.0.0/docs/player.md +160 -0
  31. spotapi-2.0.0/docs/release-2.0.0.md +59 -0
  32. spotapi-2.0.0/docs/studio.md +89 -0
  33. spotapi-2.0.0/examples/__init__.py +1 -0
  34. spotapi-2.0.0/examples/credit_trail.py +48 -0
  35. spotapi-2.0.0/examples/credits.py +16 -0
  36. spotapi-2.0.0/examples/custom_transport.py +17 -0
  37. spotapi-2.0.0/examples/details.py +323 -0
  38. spotapi-2.0.0/examples/discover.png +0 -0
  39. spotapi-2.0.0/examples/discover.py +753 -0
  40. spotapi-2.0.0/examples/discover.svg +247 -0
  41. spotapi-2.0.0/examples/export.py +17 -0
  42. spotapi-2.0.0/examples/lookup.py +17 -0
  43. spotapi-2.0.0/examples/lyrics.py +21 -0
  44. spotapi-2.0.0/examples/mix_map.py +66 -0
  45. spotapi-2.0.0/examples/overlap.py +31 -0
  46. spotapi-2.0.0/examples/pagination.py +23 -0
  47. spotapi-2.0.0/examples/player.py +35 -0
  48. spotapi-2.0.0/examples/playlist_crate.py +31 -0
  49. spotapi-2.0.0/examples/public_search.py +26 -0
  50. spotapi-2.0.0/examples/quickstart.py +16 -0
  51. spotapi-2.0.0/examples/studio/__init__.py +1 -0
  52. spotapi-2.0.0/examples/studio/__main__.py +5 -0
  53. spotapi-2.0.0/examples/studio/actions.py +110 -0
  54. spotapi-2.0.0/examples/studio/app.js +1109 -0
  55. spotapi-2.0.0/examples/studio/desktop.py +233 -0
  56. spotapi-2.0.0/examples/studio/index.html +323 -0
  57. spotapi-2.0.0/examples/studio/lyrics.py +91 -0
  58. spotapi-2.0.0/examples/studio/preview.png +0 -0
  59. spotapi-2.0.0/examples/studio/service.py +636 -0
  60. spotapi-2.0.0/examples/studio/style.css +1338 -0
  61. spotapi-2.0.0/examples/taste.py +29 -0
  62. spotapi-2.0.0/pyproject.toml +114 -0
  63. spotapi-2.0.0/requirements.txt +1 -0
  64. spotapi-2.0.0/spotapi/__init__.py +52 -0
  65. spotapi-2.0.0/spotapi/account.py +301 -0
  66. spotapi-2.0.0/spotapi/account_session.py +152 -0
  67. spotapi-2.0.0/spotapi/blend.py +80 -0
  68. spotapi-2.0.0/spotapi/bundle_parsing.py +69 -0
  69. spotapi-2.0.0/spotapi/captcha.py +42 -0
  70. spotapi-2.0.0/spotapi/catalogue.py +1338 -0
  71. spotapi-2.0.0/spotapi/cli.py +45 -0
  72. spotapi-2.0.0/spotapi/client.py +429 -0
  73. spotapi-2.0.0/spotapi/command_state.py +66 -0
  74. spotapi-2.0.0/spotapi/connect.py +54 -0
  75. spotapi-2.0.0/spotapi/connection/__init__.py +12 -0
  76. spotapi-2.0.0/spotapi/connection/client.py +8 -0
  77. spotapi-2.0.0/spotapi/connection/http.py +650 -0
  78. spotapi-2.0.0/spotapi/connection/types.py +85 -0
  79. spotapi-2.0.0/spotapi/connection/websocket.py +520 -0
  80. spotapi-2.0.0/spotapi/datastruct/__init__.py +7 -0
  81. spotapi-2.0.0/spotapi/datastruct/event_handler.py +168 -0
  82. spotapi-2.0.0/spotapi/datastruct/object_dict.py +197 -0
  83. spotapi-2.0.0/spotapi/datastruct/pool.py +236 -0
  84. spotapi-2.0.0/spotapi/devices.py +192 -0
  85. spotapi-2.0.0/spotapi/discovery.py +103 -0
  86. spotapi-2.0.0/spotapi/history.py +144 -0
  87. spotapi-2.0.0/spotapi/library.py +268 -0
  88. spotapi-2.0.0/spotapi/library_models.py +123 -0
  89. spotapi-2.0.0/spotapi/lyrics.py +152 -0
  90. spotapi-2.0.0/spotapi/models.py +98 -0
  91. spotapi-2.0.0/spotapi/notifications.py +106 -0
  92. spotapi-2.0.0/spotapi/operations.py +419 -0
  93. spotapi-2.0.0/spotapi/password.py +84 -0
  94. spotapi-2.0.0/spotapi/playback.py +281 -0
  95. spotapi-2.0.0/spotapi/player.py +650 -0
  96. spotapi-2.0.0/spotapi/playlist.py +676 -0
  97. spotapi-2.0.0/spotapi/profiles.py +208 -0
  98. spotapi-2.0.0/spotapi/protobuf.py +120 -0
  99. spotapi-2.0.0/spotapi/public.py +508 -0
  100. spotapi-2.0.0/spotapi/py.typed +0 -0
  101. spotapi-2.0.0/spotapi/queries.py +417 -0
  102. spotapi-2.0.0/spotapi/query.py +638 -0
  103. spotapi-2.0.0/spotapi/session.py +929 -0
  104. spotapi-2.0.0/spotapi/specialized/__init__.py +5 -0
  105. spotapi-2.0.0/spotapi/specialized/data_wrappers/__init__.py +253 -0
  106. spotapi-2.0.0/spotapi/specialized/data_wrappers/album.py +72 -0
  107. spotapi-2.0.0/spotapi/specialized/data_wrappers/album_details.py +243 -0
  108. spotapi-2.0.0/spotapi/specialized/data_wrappers/artist.py +74 -0
  109. spotapi-2.0.0/spotapi/specialized/data_wrappers/artist_details.py +205 -0
  110. spotapi-2.0.0/spotapi/specialized/data_wrappers/catalogue.py +159 -0
  111. spotapi-2.0.0/spotapi/specialized/data_wrappers/common.py +143 -0
  112. spotapi-2.0.0/spotapi/specialized/data_wrappers/credits.py +28 -0
  113. spotapi-2.0.0/spotapi/specialized/data_wrappers/playlist.py +80 -0
  114. spotapi-2.0.0/spotapi/specialized/data_wrappers/playlist_details.py +46 -0
  115. spotapi-2.0.0/spotapi/specialized/data_wrappers/playlist_track.py +108 -0
  116. spotapi-2.0.0/spotapi/specialized/data_wrappers/podcast.py +56 -0
  117. spotapi-2.0.0/spotapi/specialized/data_wrappers/podcast_episode.py +137 -0
  118. spotapi-2.0.0/spotapi/specialized/data_wrappers/profile_attributes.py +32 -0
  119. spotapi-2.0.0/spotapi/specialized/data_wrappers/track.py +106 -0
  120. spotapi-2.0.0/spotapi/specialized/data_wrappers/track_details.py +207 -0
  121. spotapi-2.0.0/spotapi/specialized/totp.py +81 -0
  122. spotapi-2.0.0/spotapi/stats.py +103 -0
  123. spotapi-2.0.0/spotapi/status.py +718 -0
  124. spotapi-2.0.0/spotapi/types/__init__.py +44 -0
  125. spotapi-2.0.0/spotapi/types/exceptions.py +48 -0
  126. spotapi-2.0.0/spotapi/types/logger.py +801 -0
  127. spotapi-2.0.0/spotapi/utils/__init__.py +6 -0
  128. spotapi-2.0.0/spotapi/utils/cache.py +149 -0
  129. spotapi-2.0.0/spotapi/utils/random.py +28 -0
  130. spotapi-2.0.0/tests/README.md +17 -0
  131. spotapi-2.0.0/tests/conftest.py +39 -0
  132. spotapi-2.0.0/tests/fixtures/connect/message-1.json +100 -0
  133. spotapi-2.0.0/tests/fixtures/connect/message-2.json +382 -0
  134. spotapi-2.0.0/tests/fixtures/connect/message-3.json +393 -0
  135. spotapi-2.0.0/tests/fixtures/connect/message-4.json +146 -0
  136. spotapi-2.0.0/tests/test_account.py +250 -0
  137. spotapi-2.0.0/tests/test_account_content.py +461 -0
  138. spotapi-2.0.0/tests/test_artist_details_model.py +27 -0
  139. spotapi-2.0.0/tests/test_auth_recovery.py +207 -0
  140. spotapi-2.0.0/tests/test_bundle_cache.py +88 -0
  141. spotapi-2.0.0/tests/test_catalogue_lifecycle.py +178 -0
  142. spotapi-2.0.0/tests/test_cli.py +39 -0
  143. spotapi-2.0.0/tests/test_data_contracts.py +131 -0
  144. spotapi-2.0.0/tests/test_discover_demo.py +131 -0
  145. spotapi-2.0.0/tests/test_discovery_parser.py +22 -0
  146. spotapi-2.0.0/tests/test_lifecycle.py +305 -0
  147. spotapi-2.0.0/tests/test_listening.py +168 -0
  148. spotapi-2.0.0/tests/test_live.py +103 -0
  149. spotapi-2.0.0/tests/test_live_account.py +39 -0
  150. spotapi-2.0.0/tests/test_live_catalogue.py +152 -0
  151. spotapi-2.0.0/tests/test_live_controls.py +157 -0
  152. spotapi-2.0.0/tests/test_live_discovery.py +24 -0
  153. spotapi-2.0.0/tests/test_live_player.py +38 -0
  154. spotapi-2.0.0/tests/test_live_playlists.py +116 -0
  155. spotapi-2.0.0/tests/test_live_studio.py +45 -0
  156. spotapi-2.0.0/tests/test_mutations.py +177 -0
  157. spotapi-2.0.0/tests/test_native_websocket.py +109 -0
  158. spotapi-2.0.0/tests/test_operations.py +47 -0
  159. spotapi-2.0.0/tests/test_player.py +842 -0
  160. spotapi-2.0.0/tests/test_protobuf.py +35 -0
  161. spotapi-2.0.0/tests/test_public_api.py +627 -0
  162. spotapi-2.0.0/tests/test_public_catalogue.py +204 -0
  163. spotapi-2.0.0/tests/test_queries_parsing.py +132 -0
  164. spotapi-2.0.0/tests/test_search_models.py +26 -0
  165. spotapi-2.0.0/tests/test_studio.py +233 -0
  166. spotapi-2.0.0/tests/test_studio_browser.py +240 -0
  167. spotapi-2.0.0/tests/test_transport.py +295 -0
  168. spotapi-2.0.0/tests/test_websocket_lifecycle.py +194 -0
  169. spotapi-1.2.7/PKG-INFO +0 -168
  170. spotapi-1.2.7/README.md +0 -151
  171. spotapi-1.2.7/setup.cfg +0 -4
  172. spotapi-1.2.7/setup.py +0 -61
  173. spotapi-1.2.7/spotapi/__init__.py +0 -26
  174. spotapi-1.2.7/spotapi/_tests/__init__.py +0 -1
  175. spotapi-1.2.7/spotapi/_tests/annotations_test.py +0 -224
  176. spotapi-1.2.7/spotapi/album.py +0 -95
  177. spotapi-1.2.7/spotapi/artist.py +0 -187
  178. spotapi-1.2.7/spotapi/client.py +0 -255
  179. spotapi-1.2.7/spotapi/creator.py +0 -211
  180. spotapi-1.2.7/spotapi/exceptions/__init__.py +0 -1
  181. spotapi-1.2.7/spotapi/exceptions/errors.py +0 -111
  182. spotapi-1.2.7/spotapi/family.py +0 -162
  183. spotapi-1.2.7/spotapi/http/__init__.py +0 -2
  184. spotapi-1.2.7/spotapi/http/data.py +0 -43
  185. spotapi-1.2.7/spotapi/http/request.py +0 -248
  186. spotapi-1.2.7/spotapi/login.py +0 -366
  187. spotapi-1.2.7/spotapi/password.py +0 -99
  188. spotapi-1.2.7/spotapi/player.py +0 -360
  189. spotapi-1.2.7/spotapi/playlist.py +0 -367
  190. spotapi-1.2.7/spotapi/podcast.py +0 -132
  191. spotapi-1.2.7/spotapi/public.py +0 -121
  192. spotapi-1.2.7/spotapi/solvers/__init__.py +0 -15
  193. spotapi-1.2.7/spotapi/solvers/capmonster.py +0 -153
  194. spotapi-1.2.7/spotapi/solvers/capsolver.py +0 -154
  195. spotapi-1.2.7/spotapi/song.py +0 -290
  196. spotapi-1.2.7/spotapi/status.py +0 -234
  197. spotapi-1.2.7/spotapi/types/__init__.py +0 -2
  198. spotapi-1.2.7/spotapi/types/alias.py +0 -29
  199. spotapi-1.2.7/spotapi/types/annotations.py +0 -201
  200. spotapi-1.2.7/spotapi/types/data.py +0 -447
  201. spotapi-1.2.7/spotapi/types/interfaces.py +0 -70
  202. spotapi-1.2.7/spotapi/user.py +0 -128
  203. spotapi-1.2.7/spotapi/utils/__init__.py +0 -3
  204. spotapi-1.2.7/spotapi/utils/logger.py +0 -95
  205. spotapi-1.2.7/spotapi/utils/saver.py +0 -361
  206. spotapi-1.2.7/spotapi/utils/strings.py +0 -130
  207. spotapi-1.2.7/spotapi/websocket.py +0 -167
  208. spotapi-1.2.7/spotapi.egg-info/PKG-INFO +0 -168
  209. spotapi-1.2.7/spotapi.egg-info/SOURCES.txt +0 -43
  210. spotapi-1.2.7/spotapi.egg-info/dependency_links.txt +0 -1
  211. spotapi-1.2.7/spotapi.egg-info/requires.txt +0 -18
  212. spotapi-1.2.7/spotapi.egg-info/top_level.txt +0 -1
@@ -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,65 @@
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
+ python -I - <<'PY'
38
+ import os
39
+ from importlib.util import find_spec
40
+ from pathlib import Path
41
+ import spotapi
42
+ from spotapi import Private, Public
43
+ from spotapi.models import PlaylistTrack
44
+ assert not Path(spotapi.__file__).resolve().is_relative_to(Path(os.environ["GITHUB_WORKSPACE"]).resolve())
45
+ assert find_spec("spotapi.v2") is None
46
+ assert callable(Private.from_cookies)
47
+ assert Public.parse_url("spotify:track:abc").id == "abc"
48
+ PY
49
+ - uses: actions/upload-artifact@v4
50
+ with:
51
+ name: python-distributions
52
+ path: dist/
53
+
54
+ publish:
55
+ needs: build
56
+ runs-on: ubuntu-latest
57
+ environment: pypi
58
+ permissions:
59
+ id-token: write
60
+ steps:
61
+ - uses: actions/download-artifact@v4
62
+ with:
63
+ name: python-distributions
64
+ path: dist/
65
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,48 @@
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: ubuntu-latest
13
+ strategy:
14
+ matrix:
15
+ python: ["3.11", "3.12", "3.13"]
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ - uses: actions/setup-python@v5
19
+ with:
20
+ python-version: ${{ matrix.python }}
21
+ - run: python -m pip install -e '.[dev,demo]'
22
+ - run: python -m pytest -m 'not live'
23
+ - run: python -m pyright
24
+ - run: python -m ruff check .
25
+ - run: python -m black --check .
26
+
27
+ public-api:
28
+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
29
+ runs-on: ubuntu-latest
30
+ timeout-minutes: 15
31
+ steps:
32
+ - uses: actions/checkout@v4
33
+ - uses: actions/setup-python@v5
34
+ with:
35
+ python-version: "3.12"
36
+ - run: python -m pip install -e '.[dev]'
37
+ - run: python -m pytest --live=read -m live -vv
38
+
39
+ studio-ui:
40
+ runs-on: ubuntu-latest
41
+ steps:
42
+ - uses: actions/checkout@v4
43
+ - uses: actions/setup-python@v5
44
+ with:
45
+ python-version: "3.12"
46
+ - run: python -m pip install -e '.[dev]'
47
+ - run: python -m playwright install --with-deps chromium
48
+ - run: python -m pytest tests/test_studio.py tests/test_studio_browser.py -q
@@ -0,0 +1,177 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .vscode/
11
+ .Python
12
+ build/
13
+ develop-eggs/
14
+ dist/
15
+ downloads/
16
+ eggs/
17
+ .eggs/
18
+ lib/
19
+ lib64/
20
+ parts/
21
+ sdist/
22
+ var/
23
+ wheels/
24
+ share/python-wheels/
25
+ *.egg-info/
26
+ .installed.cfg
27
+ *.egg
28
+ MANIFEST
29
+
30
+ # PyInstaller
31
+ # Usually these files are written by a python script from a template
32
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
33
+ *.manifest
34
+ *.spec
35
+
36
+ # Installer logs
37
+ pip-log.txt
38
+ pip-delete-this-directory.txt
39
+
40
+ # Unit test / coverage reports
41
+ htmlcov/
42
+ .tox/
43
+ .nox/
44
+ .coverage
45
+ .coverage.*
46
+ .cache
47
+ nosetests.xml
48
+ coverage.xml
49
+ *.cover
50
+ *.py,cover
51
+ .hypothesis/
52
+ .pytest_cache/
53
+ cover/
54
+
55
+ # Translations
56
+ *.mo
57
+ *.pot
58
+
59
+ # Django stuff:
60
+ *.log
61
+ local_settings.py
62
+ db.sqlite3
63
+ db.sqlite3-journal
64
+
65
+ # Flask stuff:
66
+ instance/
67
+ .webassets-cache
68
+
69
+ # Scrapy stuff:
70
+ .scrapy
71
+
72
+ # Sphinx documentation
73
+ docs/_build/
74
+
75
+ # PyBuilder
76
+ .pybuilder/
77
+ target/
78
+
79
+ # Jupyter Notebook
80
+ .ipynb_checkpoints
81
+
82
+ # IPython
83
+ profile_default/
84
+ ipython_config.py
85
+
86
+ # pyenv
87
+ # For a library or package, you might want to ignore these files since the code is
88
+ # intended to run in multiple environments; otherwise, check them in:
89
+ # .python-version
90
+
91
+ # pipenv
92
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
93
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
94
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
95
+ # install all needed dependencies.
96
+ #Pipfile.lock
97
+
98
+ # poetry
99
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
100
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
101
+ # commonly ignored for libraries.
102
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
103
+ #poetry.lock
104
+
105
+ # pdm
106
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
107
+ #pdm.lock
108
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
109
+ # in version control.
110
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
111
+ .pdm.toml
112
+ .pdm-python
113
+ .pdm-build/
114
+
115
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
116
+ __pypackages__/
117
+
118
+ # Celery stuff
119
+ celerybeat-schedule
120
+ celerybeat.pid
121
+
122
+ # SageMath parsed files
123
+ *.sage.py
124
+
125
+ # Environments
126
+ .env
127
+ .venv
128
+ env/
129
+ venv/
130
+ ENV/
131
+ env.bak/
132
+ venv.bak/
133
+
134
+ # Spyder project settings
135
+ .spyderproject
136
+ .spyproject
137
+
138
+ # Rope project settings
139
+ .ropeproject
140
+
141
+ # mkdocs documentation
142
+ /site
143
+
144
+ # mypy
145
+ .mypy_cache/
146
+ .dmypy.json
147
+ dmypy.json
148
+
149
+ # Pyre type checker
150
+ .pyre/
151
+
152
+ # pytype static type analyzer
153
+ .pytype/
154
+
155
+ # Cython debug symbols
156
+ cython_debug/
157
+
158
+ # PyCharm
159
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
160
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
161
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
162
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
163
+ #.idea/
164
+ main.py
165
+ build.bat
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
@@ -0,0 +1,59 @@
1
+ # Changelog
2
+
3
+ ## 2.0.0 — unreleased
4
+
5
+ - Use `spotapi` for all async imports. The synchronous release remains available as `spotapi==1.2.8`.
6
+ - Install the `spotapi` command for anonymous track search and JSON resource lookups.
7
+ - Open a managed account session with `Private.from_cookies()`.
8
+ - Follow, unfollow and check artists by ID, URI or URL through `account.library`.
9
+ - Fetch multiple tracks, albums or artists through one catalogue client.
10
+ - Move exact playlist occurrences by UID, including duplicate tracks.
11
+ - Set or clear a custom JPEG playlist cover.
12
+ - Stream typed audiobook chapter pages for available titles.
13
+ - Browse Studio lyrics through LRCLIB and seek from timed lines on the matching track.
14
+
15
+ ### Added
16
+
17
+ - Typed async catalogue search, lookups, credits, discovery and lazy pagination.
18
+ - `Public` for self-cleaning one-shot calls and `Catalogue` for connection reuse.
19
+ - Cookie-authenticated account, library, rankings, profiles and notifications.
20
+ - Existing-player controls, async listeners, occurrence-aware queue editing,
21
+ sleep timers and entitled lyrics.
22
+ - Playlist metadata editing and removal by exact occurrence UID.
23
+ - A provider-neutral async CAPTCHA protocol for explicit account operations.
24
+ - Optional Studio and terminal examples; their dependencies stay outside the core.
25
+ - Offline lifecycle and contract tests, opt-in live checks, and release workflows.
26
+
27
+ ### Changed
28
+
29
+ - Python 3.11+ and async/await are required. See [migration](MIGRATION.md) for
30
+ compatibility changes and v1 features that have not been ported.
31
+ - Hatch and `pyproject.toml` define package metadata; `requirements.txt` retains
32
+ the same tested transport pin.
33
+ - Known reads opt into bounded retries. Mutations are not replayed after
34
+ ambiguous failures; account CSRF rotation is handled explicitly.
35
+ - Query hashes use a build-bound disk cache. Cached startup fetches the main
36
+ bundle rather than every chunk, and discards unneeded source after parsing.
37
+ - Clients own refresh, socket and callback tasks and release them on shutdown.
38
+ - Logging defaults to the standard library without configuring application sinks.
39
+
40
+ ### Fixed
41
+
42
+ - Playlist add/remove operations reject error unions such as `NotFound` instead
43
+ of interpreting a nonempty error object as success.
44
+ - Commands with `wait=True` require a matching dealer ACK or a fresh state proving
45
+ the result, even when the HTTP response contains no acknowledgement ID.
46
+ - Studio cancels timed-out sign-ins, prevents concurrent cookie imports, and
47
+ discards delayed data from the previous account.
48
+ - Library saves, pins and user follows validate Spotify's confirmation instead
49
+ of accepting nonempty error responses or incomplete mutation results.
50
+ - Playback restrictions, canonical playlist metadata reads, and optional model
51
+ fields are handled explicitly.
52
+
53
+ See the [release checks](docs/release-2.0.0.md) and [player coverage](docs/player-coverage.md)
54
+ for supported workflows and known gaps.
55
+
56
+ ## v1 history
57
+
58
+ See the [repository history](https://github.com/Aran404/SpotAPI/commits/main/)
59
+ for changes predating the rewrite.
@@ -0,0 +1,128 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ We as members, contributors, and leaders pledge to make participation in our
6
+ community a harassment-free experience for everyone, regardless of age, body
7
+ size, visible or invisible disability, ethnicity, sex characteristics, gender
8
+ identity and expression, level of experience, education, socio-economic status,
9
+ nationality, personal appearance, race, religion, or sexual identity
10
+ and orientation.
11
+
12
+ We pledge to act and interact in ways that contribute to an open, welcoming,
13
+ diverse, inclusive, and healthy community.
14
+
15
+ ## Our Standards
16
+
17
+ Examples of behavior that contributes to a positive environment for our
18
+ community include:
19
+
20
+ * Demonstrating empathy and kindness toward other people
21
+ * Being respectful of differing opinions, viewpoints, and experiences
22
+ * Giving and gracefully accepting constructive feedback
23
+ * Accepting responsibility and apologizing to those affected by our mistakes,
24
+ and learning from the experience
25
+ * Focusing on what is best not just for us as individuals, but for the
26
+ overall community
27
+
28
+ Examples of unacceptable behavior include:
29
+
30
+ * The use of sexualized language or imagery, and sexual attention or
31
+ advances of any kind
32
+ * Trolling, insulting or derogatory comments, and personal or political attacks
33
+ * Public or private harassment
34
+ * Publishing others' private information, such as a physical or email
35
+ address, without their explicit permission
36
+ * Other conduct which could reasonably be considered inappropriate in a
37
+ professional setting
38
+
39
+ ## Enforcement Responsibilities
40
+
41
+ Community leaders are responsible for clarifying and enforcing our standards of
42
+ acceptable behavior and will take appropriate and fair corrective action in
43
+ response to any behavior that they deem inappropriate, threatening, offensive,
44
+ or harmful.
45
+
46
+ Community leaders have the right and responsibility to remove, edit, or reject
47
+ comments, commits, code, wiki edits, issues, and other contributions that are
48
+ not aligned to this Code of Conduct, and will communicate reasons for moderation
49
+ decisions when appropriate.
50
+
51
+ ## Scope
52
+
53
+ This Code of Conduct applies within all community spaces, and also applies when
54
+ an individual is officially representing the community in public spaces.
55
+ Examples of representing our community include using an official e-mail address,
56
+ posting via an official social media account, or acting as an appointed
57
+ representative at an online or offline event.
58
+
59
+ ## Enforcement
60
+
61
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
62
+ reported to the community leaders responsible for enforcement at
63
+ Email: aransservices1@gmail.com.
64
+ All complaints will be reviewed and investigated promptly and fairly.
65
+
66
+ All community leaders are obligated to respect the privacy and security of the
67
+ reporter of any incident.
68
+
69
+ ## Enforcement Guidelines
70
+
71
+ Community leaders will follow these Community Impact Guidelines in determining
72
+ the consequences for any action they deem in violation of this Code of Conduct:
73
+
74
+ ### 1. Correction
75
+
76
+ **Community Impact**: Use of inappropriate language or other behavior deemed
77
+ unprofessional or unwelcome in the community.
78
+
79
+ **Consequence**: A private, written warning from community leaders, providing
80
+ clarity around the nature of the violation and an explanation of why the
81
+ behavior was inappropriate. A public apology may be requested.
82
+
83
+ ### 2. Warning
84
+
85
+ **Community Impact**: A violation through a single incident or series
86
+ of actions.
87
+
88
+ **Consequence**: A warning with consequences for continued behavior. No
89
+ interaction with the people involved, including unsolicited interaction with
90
+ those enforcing the Code of Conduct, for a specified period of time. This
91
+ includes avoiding interactions in community spaces as well as external channels
92
+ like social media. Violating these terms may lead to a temporary or
93
+ permanent ban.
94
+
95
+ ### 3. Temporary Ban
96
+
97
+ **Community Impact**: A serious violation of community standards, including
98
+ sustained inappropriate behavior.
99
+
100
+ **Consequence**: A temporary ban from any sort of interaction or public
101
+ communication with the community for a specified period of time. No public or
102
+ private interaction with the people involved, including unsolicited interaction
103
+ with those enforcing the Code of Conduct, is allowed during this period.
104
+ Violating these terms may lead to a permanent ban.
105
+
106
+ ### 4. Permanent Ban
107
+
108
+ **Community Impact**: Demonstrating a pattern of violation of community
109
+ standards, including sustained inappropriate behavior, harassment of an
110
+ individual, or aggression toward or disparagement of classes of individuals.
111
+
112
+ **Consequence**: A permanent ban from any sort of public interaction within
113
+ the community.
114
+
115
+ ## Attribution
116
+
117
+ This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118
+ version 2.0, available at
119
+ https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
120
+
121
+ Community Impact Guidelines were inspired by [Mozilla's code of conduct
122
+ enforcement ladder](https://github.com/mozilla/diversity).
123
+
124
+ [homepage]: https://www.contributor-covenant.org
125
+
126
+ For answers to common questions about this code of conduct, see the FAQ at
127
+ https://www.contributor-covenant.org/faq. Translations are available at
128
+ https://www.contributor-covenant.org/translations.
@@ -0,0 +1,44 @@
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
+
17
+ Tests run offline by default. For read-only Spotify contract checks:
18
+
19
+ ```bash
20
+ python -m pytest --live=read -vv
21
+ ```
22
+
23
+ The same command runs public and authenticated reads when `SPOTIFY_COOKIE` is set
24
+ in the environment or local `.env`. Use `--live=all` to include explicit playback
25
+ changes; it is one mode switch, not a second environment flag.
26
+ Live tests depend on Spotify and may fail when upstream contracts change.
27
+ Never run mutating checks in ordinary CI. Personal playback checks restore their baseline in `finally`.
28
+
29
+ Use real Spotify JSON key spelling in fixtures, including `items`. Test
30
+ ownership, cancellation, partial payloads, and retry safety when changing
31
+ network behavior. Keep optional metadata optional. A new background task
32
+ needs an owner, a retained reference, observable failures, and shutdown.
33
+
34
+ The package uses Hatch and `pyproject.toml` as its packaging source of truth.
35
+ Keep `requirements.txt` consistent with the tested wreq pin. Check a wheel
36
+ with `python -m pip wheel . --no-deps` when changing packaging.
37
+
38
+ Benchmark with `python benchmarks/review.py --output benchmarks/local.json`.
39
+ Add `--live` for network measurements. Publish raw samples and distinguish
40
+ new sessions, warm sessions, disk caches, network latency, and model overhead.
41
+ Do not infer network speedups from the offline ownership comparison.
42
+
43
+ See the [API layout](docs/api-layout.md) for module responsibilities and
44
+ ownership. Follow the [code of conduct](CODE_OF_CONDUCT.md).
@@ -0,0 +1,46 @@
1
+ ## Legal Notice
2
+
3
+ This repository is in no way affiliated with, authorized, maintained, sponsored or endorsed by Spotify Inc. (spotify.com) or any of its affiliates or subsidiaries. This project is intended **for educational purposes only**.
4
+
5
+ Please note the following:
6
+
7
+ ## Legal Notice
8
+
9
+ ### **Affiliation Disclaimer**
10
+ 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
+
12
+ ### **Liability Limitation**
13
+ Under no circumstances shall the author of this repository be liable for any direct, indirect, incidental, special, consequential, or punitive damages, including but not limited to, loss of profits, data, or use, arising out of or in connection with the repository, regardless of whether such damages were foreseeable and whether the author was advised of the possibility of such damages.
14
+
15
+ ### **No Warranties**
16
+ The repository is provided on an "as is" and "as available" basis without any warranties of any kind, either express or implied, including but not limited to, implied warranties of merchantability, fitness for a particular purpose, or non-infringement.
17
+
18
+ ### **User Responsibility**
19
+ Users assume all risk for their use of this repository and are solely responsible for any damage or loss, including but not limited to financial loss, of any kind, to any party, that results from the use or misuse of the repository and its contents.
20
+
21
+ ### **Legal Compliance**
22
+ Users are responsible for ensuring their use of the repository and its contents complies with all local, state, national, and international laws and regulations.
23
+
24
+ ### **Indemnification**
25
+ Users agree to indemnify, defend, and hold harmless the author from any claims, liabilities, damages, losses, or expenses, including legal fees, arising out of or in any way connected with their use of this repository, violation of these terms, or infringement of any intellectual property or other rights of any person or entity.
26
+
27
+ ### **No Endorsement**
28
+ The inclusion of third-party content does not imply endorsement or recommendation of such content by the author.
29
+
30
+ ### **Governing Law and Jurisdiction**
31
+ Any disputes arising out of or related to the use of this repository shall be governed by the laws of the author's jurisdiction, without regard to its conflict of law principles.
32
+
33
+ ### **Severability**
34
+ If any provision of this notice is found to be unlawful, void, or unenforceable, then that provision shall be deemed severable from this notice and shall not affect the validity and enforceability of any remaining provisions.
35
+
36
+ ### **Acknowledgment of Understanding**
37
+ By using this repository, users acknowledge that they have read, understood, and agree to be bound by these terms.
38
+
39
+ ### **Updates and Changes**
40
+ The author reserves the right to modify, update, or remove any content, information, or features in this repository at any time without prior notice. Users are responsible for regularly reviewing the content and any changes made to this repository.
41
+
42
+ ### **Unforeseen Consequences**
43
+ The author of this repository is not responsible for any consequences, damages, or losses arising from the use or misuse of this repository or the content provided by the third-party APIs. Users are solely responsible for their actions and any repercussions that may follow.
44
+
45
+ ### **Educational Purpose**
46
+ Please note that this project and its content are provided strictly for educational purposes. Users acknowledge that they are using the APIs at their own risk and agree to comply with any applicable laws and regulations.