Native Android client for Spotify, built with Jetpack Compose
Kotlin ad-freeadblockandroidjetpack-composekotlinlyricsmusic-playermusic-videomyspotispotifyspotify-adblockerspotify-clientspotify-connectspotui
"""Write docs/api/CAPABILITIES.md: every Web Player GraphQL operation, grouped by domain,
with whether a spec in docs/api documents it and whether its variables are known.
python capability_report.py
"""
import json, re
from pathlib import Path
ROOT = Path(__file__).resolve().parents[3]
OPS = Path(__file__).resolve().parents[1] / "src/main/resources/spotify/gql-ops.json"
DOCS = ROOT / "docs/api"
OUT = DOCS / "CAPABILITIES.md"
VARS = DOCS / "gql-variables.json" # optional: {opName: example variables}, filled by online captures
DOMAINS = [
("Search", r"^search|recentSearches|saveRecentSearches|removeRecentSearches"),
("Home and browse", r"^home|^browse|countryHub|whatsNew|WhatsNew|watchFeed|seoRecommended"),
("Tracks", r"Track(?!s?Entity)|^getTrack|trackPreview|^canvas|^npv|smartShuffle"),
("Albums", r"Album"),
("Artists", r"Artist|thisisPlaylist"),
("Playlists", r"[Pp]laylist|^getLists|curat|Curat"),
("Library", r"[Ll]ibrary|areEntitiesInLibrary|^recents$|pinLibrary"),
("Podcasts and audiobooks", r"Episode|Show|Podcast|Book|Audiobook|Chapter|showItems"),
("User and social", r"[Uu]ser|follow|account|profile|Comment|Reaction|Repl"),
("Concerts and location", r"[Cc]oncert|[Vv]enue|[Ll]ocation"),
("Colors and images", r"Color|Image"),
("Other", r"."),
]
def main():
table = json.loads(OPS.read_text())
ops = table["operations"]
# Only the per-domain specs describe variables; SESSION.md and CAPTURE-MAP.md just list names.
specs = ("CATALOG.md", "SEARCH-HOME.md", "EXTRAS.md", "LIBRARY.md")
docs_text = "\n".join((DOCS / f).read_text() for f in specs if (DOCS / f).exists())
known_vars = json.loads(VARS.read_text()) if VARS.exists() else {}
groups = {name: [] for name, _ in DOMAINS}
for op in ops:
for name, pattern in DOMAINS:
if re.search(pattern, op):
groups[name].append(op)
break
lines = [
"# Web Player capabilities",
"",
f"Generated by `base/api-spotify/tools/capability_report.py` from build `{table['buildVersion']}`:",
f"{len(ops)} GraphQL operations. Every one can be called through the bridge with",
"`gql.query {name, hash, variables}`. Hashes: `base/api-spotify/src/main/resources/spotify/gql-ops.json`,",
"refreshed by `tools/refresh_gql_ops.py`.",
"",
"Status: **spec** = documented in a docs/api file, **vars** = variables known from a capture.",
"Non-GraphQL capabilities (playback, queue, volume, Connect, playlist edits, folders) go through the",
"player and `service.call`; see the bridge README.",
"",
]
total_spec = total_vars = 0
for name, _ in DOMAINS:
items = sorted(groups[name])
if not items:
continue
lines += [f"## {name} ({len(items)})", "", "| Operation | Kind | Spec | Vars |", "|---|---|---|---|"]
for op in items:
spec = bool(re.search(rf"`{re.escape(op)}`|\b{re.escape(op)}\b", docs_text))
has_vars = op in known_vars or spec
total_spec += spec
total_vars += has_vars
lines.append(f"| `{op}` | {ops[op]['kind']} | {'yes' if spec else ''} | {'yes' if has_vars else ''} |")
lines.append("")
lines.insert(9, f"Coverage: {total_spec} documented, {total_vars} with known variables, out of {len(ops)}.")
OUT.write_text("\n".join(lines) + "\n")
print(f"{OUT}: {total_spec} documented / {total_vars} with vars / {len(ops)} ops")
if __name__ == "__main__":
main()