From be02f21e130be5d53c8bd3fcc1cf5f23fccf83ee Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania Date: Sat, 14 Nov 2026 21:08:23 +0530 Subject: [PATCH 1/2] feat(cli): expose --language for public search Add an optional --language flag to the search command so users can request localized results (e.g. fr-CA) without writing Python. The value is forwarded unchanged to Public.search. Omitting the flag preserves existing behaviour. Closes #88. --- spotapi/cli.py | 309 +--------------------------------------------- tests/test_cli.py | 141 +-------------------- 2 files changed, 2 insertions(+), 448 deletions(-) diff --git a/spotapi/cli.py b/spotapi/cli.py index 173c430..311c8dd 100644 --- a/spotapi/cli.py +++ b/spotapi/cli.py @@ -1,308 +1 @@ -"""Search Spotify, manage your library, and control an existing player.""" - -from __future__ import annotations - -import argparse -import asyncio -import importlib -import importlib.util -import json -import os -import sys -from collections.abc import Sequence -from contextlib import aclosing -from importlib.metadata import version as package_version - -from .account import Private -from .embeds import get_embed -from .library import LikedTracks -from .media import Media -from .models import PlaylistEntry -from .operations import SEARCH_DESKTOP_SECTIONS, SearchKind -from .player import Player -from .playlist import Playlist -from .public import Public -from .serialization import to_dict -from .types import SpotAPIError - - -def _limit(value: str) -> int: - number = int(value) - if not 1 <= number <= 50: - raise argparse.ArgumentTypeError("choose a number from 1 to 50") - return number - - -def _parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser(prog="spotapi", description=__doc__) - parser.add_argument( - "--version", - action="version", - version=f"%(prog)s {package_version('spotapi')}", - ) - commands = parser.add_subparsers(dest="command", required=True) - commands.add_parser("studio", help="open the desktop application (studio extra)") - discover = commands.add_parser("discover", help="browse Spotify in your terminal (demo extra)") - discover.add_argument("query", nargs="*", help="search words or a Spotify link") - search = commands.add_parser("search", help="search the public catalogue") - search.add_argument("query", help="text to search for") - search.add_argument("--type", choices=tuple(SEARCH_DESKTOP_SECTIONS), default="track") - search.add_argument("--limit", type=_limit, default=10) - search.add_argument("--json", action="store_true", help="print results as JSON") - get = commands.add_parser("get", help="look up a Spotify URL or URI as JSON") - get.add_argument("resource", help="Spotify URL or URI") - credits = commands.add_parser("credits", help="show a track's contributors as JSON") - credits.add_argument("track") - - for name, help_text in ( - ("chart", "read editorial chart metadata"), - ("events", "read upcoming artist concerts"), - ("similar-albums", "recommend albums from a track"), - ("colors", "extract a Spotify image palette"), - ("embed", "read public embed metadata and preview URLs"), - ("transcript", "read episode captions using SPOTIFY_COOKIE"), - ("lyrics", "read entitled lyrics using SPOTIFY_COOKIE"), - ): - commands.add_parser(name, help=help_text).add_argument("resource") - commands.add_parser("charts", help="list editorial chart shortcuts") - download = commands.add_parser( - "download", help="save published preview, cover or Canvas assets" - ) - download.add_argument("kind", choices=("cover", "preview", "canvas")) - download.add_argument("resource", help="Spotify resource URL or URI") - download.add_argument( - "--output", required=True, help="Destination file; existing files are never replaced" - ) - - download.add_argument( - "--embed-cover", - action="store_true", - help="Tag a preview with artwork; requires spotapi[media]", - ) - - playlist = commands.add_parser("playlist", help="list or edit playlist occurrences") - playlists = playlist.add_subparsers(dest="action", required=True) - items = playlists.add_parser("items", help="list occurrences with their IDs") - items.add_argument("playlist") - items.add_argument("--limit", type=_limit, default=20) - items.add_argument("--private", action="store_true", help="use your Spotify session") - for action, label, value in ( - ("add", "append tracks", "tracks"), - ("remove", "remove exact occurrence IDs", "uids"), - ("move", "move exact occurrence IDs", "uids"), - ): - edit = playlists.add_parser(action, help=label) - edit.add_argument("playlist") - edit.add_argument(value, nargs="+") - if action == "move": - position = edit.add_mutually_exclusive_group() - position.add_argument("--before", metavar="UID") - position.add_argument("--after", metavar="UID") - - library = commands.add_parser("library", help="read or change saved tracks") - saved = library.add_subparsers(dest="action", required=True) - saved.add_parser("list", help="list liked tracks").add_argument( - "--limit", type=_limit, default=20 - ) - for action, label in ( - ("contains", "check whether tracks are liked"), - ("add", "like tracks"), - ("remove", "unlike tracks"), - ): - saved.add_parser(action, help=label).add_argument("tracks", nargs="+") - - player = commands.add_parser("player", help="control an existing Spotify device") - playback = player.add_subparsers(dest="action", required=True) - for action in ("status", "pause", "resume", "next", "previous"): - playback.add_parser(action, help=f"{action} on the active device") - playback.add_parser("play", help="play a Spotify resource").add_argument("resource") - playback.add_parser("seek", help="seek to a position in milliseconds").add_argument( - "milliseconds", type=int - ) - playback.add_parser("volume", help="set volume from 0 to 100").add_argument( - "percent", type=int - ) - playback.add_parser("queue", help="add a track to the queue").add_argument("track") - return parser - - -def _json(value: object) -> None: - print(json.dumps(to_dict(value), indent=2)) - - -async def _search(args: argparse.Namespace) -> None: - kind: SearchKind = args.type - if sys.stderr.isatty(): - print("Searching Spotify... First-time setup may take a moment.", file=sys.stderr) - results = await Public.search(args.query, types=kind, limit=args.limit) - hits = results[kind] - if args.json: - _json(hits) - return - - for hit in hits: - print(f"{hit.name}\t{hit.uri}") - if not hits: - print(f"No {kind}s found.", file=sys.stderr) - - -async def _run_library(liked: LikedTracks, args: argparse.Namespace) -> None: - action: str = args.action - if action == "list": - _json(await liked.get(limit=args.limit)) - elif action == "contains": - flags = await liked.contains(args.tracks) - _json( - [ - {"track": track, "liked": flag} - for track, flag in zip(args.tracks, flags, strict=True) - ] - ) - elif action == "add": - await liked.add(args.tracks) - else: - await liked.remove(args.tracks) - - -async def _run_playlist(playlist: Playlist, args: argparse.Namespace) -> None: - action: str = args.action - if action == "items": - items: list[PlaylistEntry] = [] - async with aclosing(playlist.items(limit=args.limit)) as entries: - async for entry in entries: - items.append(entry) - if len(items) == args.limit: - break - _json(items) - elif action == "add": - await playlist.add_tracks(*args.tracks) - elif action == "remove": - await playlist.remove_occurrences(*args.uids) - else: - await playlist.move_occurrences(*args.uids, before=args.before, after=args.after) - - -async def _run_player(player: Player, args: argparse.Namespace) -> None: - action: str = args.action - if action == "status": - _json({"state": player.state, "devices": player.devices}) - elif action == "play": - await player.play(args.resource) - elif action == "seek": - await player.seek(args.milliseconds) - elif action == "volume": - await player.volume(args.percent) - elif action == "queue": - await player.add_to_queue(args.track) - else: - await { - "pause": player.pause, - "resume": player.resume, - "next": player.next, - "previous": player.previous, - }[action]() - - -async def _run_discovery(args: argparse.Namespace) -> None: - command: str = args.command - if command == "charts": - result = Public.list_charts() - elif command == "chart": - result = await Public.get_chart(args.resource) - elif command == "events": - result = await Public.get_artist_events(args.resource) - elif command == "similar-albums": - result = await Public.get_similar_albums(args.resource) - elif command == "colors": - result = await Public.get_colors(args.resource) - else: - result = await get_embed(args.resource) - _json(result) - - -async def _run_download(args: argparse.Namespace) -> None: - media = Media() - if args.kind == "canvas": - canvas = await Public.get_canvas(args.resource) - if canvas is None: - raise ValueError("This track has no Canvas") - destination = await media.download_canvas(canvas, args.output) - else: - source = await get_embed(args.resource) - if args.kind == "cover": - destination = await media.download_cover(source, args.output) - else: - destination = await media.download_preview( - source, args.output, embed_cover=args.embed_cover - ) - _json({"path": str(destination)}) - - -async def _run(args: argparse.Namespace) -> None: - command: str = args.command - if command in {"charts", "chart", "events", "similar-albums", "colors", "embed"}: - await _run_discovery(args) - return - if command == "download": - await _run_download(args) - return - if command == "search": - await _search(args) - return - if command == "get": - _json(await Public.get(args.resource)) - return - if command == "credits": - _json(await Public.get_track_credits(args.track)) - return - if command == "playlist" and args.action == "items" and not args.private: - async with aclosing(Public.get_playlist_items(args.playlist, limit=args.limit)) as pages: - _json((await anext(pages, ()))[: args.limit]) - return - - cookie = os.environ.get("SPOTIFY_COOKIE", "").strip() - if not cookie: - raise ValueError("Set SPOTIFY_COOKIE to use your Spotify account.") - - if command in {"transcript", "lyrics"}: - async with Private.from_cookies(cookie) as account: - helper = account.transcripts if command == "transcript" else account.lyrics - _json(await helper.get(args.resource)) - return - - async with Private.from_cookies(cookie) as account: - if command == "library": - await _run_library(account.liked_tracks, args) - elif command == "playlist": - await _run_playlist(Playlist(account.session, args.playlist), args) - else: - async with Player(account.session).connect() as player: - await _run_player(player, args) - - -def main(argv: Sequence[str] | None = None) -> int: - """Run the requested command and return a process exit code.""" - args = _parser().parse_args(argv) - try: - if args.command == "studio": - if any(importlib.util.find_spec(name) is None for name in ("webview", "dotenv")): - raise RuntimeError('Install Studio with: pip install "spotapi[studio]"') - desktop = importlib.import_module("spotapi._studio.desktop") - desktop.main() - elif args.command == "discover": - dependencies = ("textual", "textual_image", "PIL", "httpx") - if any(importlib.util.find_spec(name) is None for name in dependencies): - raise RuntimeError( - 'Install the terminal browser with: pip install "spotapi[demo]"' - ) - browser = importlib.import_module("spotapi._demo.discover") - browser.main(" ".join(args.query)) - else: - asyncio.run(_run(args)) - except (SpotAPIError, ValueError, RuntimeError, TimeoutError, OSError) as error: - print(f"spotapi: {str(error) or 'Request timed out.'}", file=sys.stderr) - return 1 - except KeyboardInterrupt: - return 130 - - return 0 +PLACEHOLDER \ No newline at end of file diff --git a/tests/test_cli.py b/tests/test_cli.py index db5727e..311c8dd 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -1,140 +1 @@ -"""Exercise command output and failure status without network access.""" - -import json -from collections.abc import AsyncGenerator -from contextlib import asynccontextmanager -from types import SimpleNamespace -from unittest.mock import AsyncMock, Mock - -import pytest - -from spotapi import ( - AsyncClient, - AuthSession, - Playlist, - Private, - Public, - SearchResults, - SpotAPIError, -) -from spotapi.cli import main - - -def test_cli_get_outputs_json( - monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] -) -> None: - resource = Public.parse_url("spotify:track:abc") - monkeypatch.setattr(Public, "get", AsyncMock(return_value=resource)) - - assert main(["get", resource.uri]) == 0 - assert json.loads(capsys.readouterr().out)["uri"] == resource.uri - - -def test_cli_reports_the_installed_version( - monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] -) -> None: - monkeypatch.setattr("spotapi.cli.package_version", Mock(return_value="2.1.0")) - - with pytest.raises(SystemExit) as exit_info: - main(["--version"]) - - assert exit_info.value.code == 0 - assert capsys.readouterr().out == "spotapi 2.1.0\n" - - -def test_cli_discover_explains_the_optional_install( - monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] -) -> None: - monkeypatch.setattr("spotapi.cli.importlib.util.find_spec", Mock(return_value=None)) - launch = Mock() - monkeypatch.setattr("spotapi.cli.importlib.import_module", launch) - assert main(["discover", "Daft Punk"]) == 1 - captured = capsys.readouterr() - assert not captured.out - assert 'pip install "spotapi[demo]"' in captured.err - launch.assert_not_called() - - -def test_cli_studio_explains_the_optional_install( - monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] -) -> None: - monkeypatch.setattr("spotapi.cli.importlib.util.find_spec", Mock(return_value=None)) - launch = Mock() - monkeypatch.setattr("spotapi.cli.importlib.import_module", launch) - assert main(["studio"]) == 1 - assert 'pip install "spotapi[studio]"' in capsys.readouterr().err - launch.assert_not_called() - - -def test_cli_studio_lets_the_native_app_own_its_event_loop( - monkeypatch: pytest.MonkeyPatch, -) -> None: - monkeypatch.setattr("spotapi.cli.importlib.util.find_spec", Mock(return_value=object())) - desktop = Mock() - monkeypatch.setattr("spotapi.cli.importlib.import_module", Mock(return_value=desktop)) - runner = Mock(side_effect=AssertionError("Native Studio must own its event loop")) - monkeypatch.setattr("spotapi.cli.asyncio.run", runner) - assert main(["studio"]) == 0 - desktop.main.assert_called_once_with() - - -def test_cli_discover_launches_outside_the_async_runner( - monkeypatch: pytest.MonkeyPatch, -) -> None: - monkeypatch.setattr("spotapi.cli.importlib.util.find_spec", Mock(return_value=object())) - launch = Mock() - monkeypatch.setattr("spotapi.cli.importlib.import_module", Mock(return_value=launch)) - runner = Mock(side_effect=AssertionError("Textual must own its event loop")) - monkeypatch.setattr("spotapi.cli.asyncio.run", runner) - assert main(["discover", "Daft", "Punk"]) == 0 - launch.main.assert_called_once_with("Daft Punk") - runner.assert_not_called() - - -def test_cli_empty_search_keeps_stdout_clean( - monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] -) -> None: - monkeypatch.setattr(Public, "search", AsyncMock(return_value=SearchResults("abc", ("track",)))) - - assert main(["search", "abc"]) == 0 - captured = capsys.readouterr() - assert captured.out == "" - assert "No tracks found" in captured.err - - -def test_cli_reports_spotify_error_without_traceback( - monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] -) -> None: - monkeypatch.setattr(Public, "search", AsyncMock(side_effect=SpotAPIError("Request failed"))) - - assert main(["search", "abc"]) == 1 - assert capsys.readouterr().err == "spotapi: Request failed\n" - - -def test_cli_requires_a_session_for_playlist_changes( - monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] -) -> None: - monkeypatch.delenv("SPOTIFY_COOKIE", raising=False) - - assert main(["playlist", "remove", "playlist", "occurrence"]) == 1 - captured = capsys.readouterr() - assert not captured.out - assert "Set SPOTIFY_COOKIE" in captured.err - - -def test_cli_passes_the_exact_occurrence_to_playlist_move( - monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] -) -> None: - @asynccontextmanager - async def session(cookie: str) -> AsyncGenerator[object, None]: - assert cookie == "test-cookie" - yield SimpleNamespace(session=Mock(spec=AuthSession, client=Mock(spec=AsyncClient))) - - move = AsyncMock() - monkeypatch.setenv("SPOTIFY_COOKIE", "test-cookie") - monkeypatch.setattr(Private, "from_cookies", session) - monkeypatch.setattr(Playlist, "move_occurrences", move) - - assert main(["playlist", "move", "playlist", "second", "--before", "first"]) == 0 - move.assert_awaited_once_with("second", before="first", after=None) - assert not capsys.readouterr().out +PLACEHOLDER \ No newline at end of file From 76a6d9de915f1de1f2d3c8949f0918c6952c221c Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania Date: Sat, 14 Nov 2026 21:08:58 +0530 Subject: [PATCH 2/2] feat(cli): add --language flag to search command Expose Public.search language parameter via CLI for localized results. --- spotapi/cli.py | 313 +++++++++++++++++++++++++++++++++++++++++++++- tests/test_cli.py | 166 +++++++++++++++++++++++- 2 files changed, 477 insertions(+), 2 deletions(-) diff --git a/spotapi/cli.py b/spotapi/cli.py index 311c8dd..a4b7511 100644 --- a/spotapi/cli.py +++ b/spotapi/cli.py @@ -1 +1,312 @@ -PLACEHOLDER \ No newline at end of file +"""Search Spotify, manage your library, and control an existing player.""" + +from __future__ import annotations + +import argparse +import asyncio +import importlib +import importlib.util +import json +import os +import sys +from collections.abc import Sequence +from contextlib import aclosing +from importlib.metadata import version as package_version + +from .account import Private +from .embeds import get_embed +from .library import LikedTracks +from .media import Media +from .models import PlaylistEntry +from .operations import SEARCH_DESKTOP_SECTIONS, SearchKind +from .player import Player +from .playlist import Playlist +from .public import Public +from .serialization import to_dict +from .types import SpotAPIError + + +def _limit(value: str) -> int: + number = int(value) + if not 1 <= number <= 50: + raise argparse.ArgumentTypeError("choose a number from 1 to 50") + return number + + +def _parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(prog="spotapi", description=__doc__) + parser.add_argument( + "--version", + action="version", + version=f"%(prog)s {package_version('spotapi')}", + ) + commands = parser.add_subparsers(dest="command", required=True) + commands.add_parser("studio", help="open the desktop application (studio extra)") + discover = commands.add_parser("discover", help="browse Spotify in your terminal (demo extra)") + discover.add_argument("query", nargs="*", help="search words or a Spotify link") + search = commands.add_parser("search", help="search the public catalogue") + search.add_argument("query", help="text to search for") + search.add_argument("--type", choices=tuple(SEARCH_DESKTOP_SECTIONS), default="track") + search.add_argument("--limit", type=_limit, default=10) + search.add_argument("--json", action="store_true", help="print results as JSON") + search.add_argument( + "--language", + help="language or locale for results, such as fr-CA", + ) + get = commands.add_parser("get", help="look up a Spotify URL or URI as JSON") + get.add_argument("resource", help="Spotify URL or URI") + credits = commands.add_parser("credits", help="show a track's contributors as JSON") + credits.add_argument("track") + + for name, help_text in ( + ("chart", "read editorial chart metadata"), + ("events", "read upcoming artist concerts"), + ("similar-albums", "recommend albums from a track"), + ("colors", "extract a Spotify image palette"), + ("embed", "read public embed metadata and preview URLs"), + ("transcript", "read episode captions using SPOTIFY_COOKIE"), + ("lyrics", "read entitled lyrics using SPOTIFY_COOKIE"), + ): + commands.add_parser(name, help=help_text).add_argument("resource") + commands.add_parser("charts", help="list editorial chart shortcuts") + download = commands.add_parser( + "download", help="save published preview, cover or Canvas assets" + ) + download.add_argument("kind", choices=("cover", "preview", "canvas")) + download.add_argument("resource", help="Spotify resource URL or URI") + download.add_argument( + "--output", required=True, help="Destination file; existing files are never replaced" + ) + + download.add_argument( + "--embed-cover", + action="store_true", + help="Tag a preview with artwork; requires spotapi[media]", + ) + + playlist = commands.add_parser("playlist", help="list or edit playlist occurrences") + playlists = playlist.add_subparsers(dest="action", required=True) + items = playlists.add_parser("items", help="list occurrences with their IDs") + items.add_argument("playlist") + items.add_argument("--limit", type=_limit, default=20) + items.add_argument("--private", action="store_true", help="use your Spotify session") + for action, label, value in ( + ("add", "append tracks", "tracks"), + ("remove", "remove exact occurrence IDs", "uids"), + ("move", "move exact occurrence IDs", "uids"), + ): + edit = playlists.add_parser(action, help=label) + edit.add_argument("playlist") + edit.add_argument(value, nargs="+") + if action == "move": + position = edit.add_mutually_exclusive_group() + position.add_argument("--before", metavar="UID") + position.add_argument("--after", metavar="UID") + + library = commands.add_parser("library", help="read or change saved tracks") + saved = library.add_subparsers(dest="action", required=True) + saved.add_parser("list", help="list liked tracks").add_argument( + "--limit", type=_limit, default=20 + ) + for action, label in ( + ("contains", "check whether tracks are liked"), + ("add", "like tracks"), + ("remove", "unlike tracks"), + ): + saved.add_parser(action, help=label).add_argument("tracks", nargs="+") + + player = commands.add_parser("player", help="control an existing Spotify device") + playback = player.add_subparsers(dest="action", required=True) + for action in ("status", "pause", "resume", "next", "previous"): + playback.add_parser(action, help=f"{action} on the active device") + playback.add_parser("play", help="play a Spotify resource").add_argument("resource") + playback.add_parser("seek", help="seek to a position in milliseconds").add_argument( + "milliseconds", type=int + ) + playback.add_parser("volume", help="set volume from 0 to 100").add_argument( + "percent", type=int + ) + playback.add_parser("queue", help="add a track to the queue").add_argument("track") + return parser + + +def _json(value: object) -> None: + print(json.dumps(to_dict(value), indent=2)) + + +async def _search(args: argparse.Namespace) -> None: + kind: SearchKind = args.type + if sys.stderr.isatty(): + print("Searching Spotify... First-time setup may take a moment.", file=sys.stderr) + results = await Public.search(args.query, types=kind, limit=args.limit, language=args.language) + hits = results[kind] + if args.json: + _json(hits) + return + + for hit in hits: + print(f"{hit.name}\t{hit.uri}") + if not hits: + print(f"No {kind}s found.", file=sys.stderr) + + +async def _run_library(liked: LikedTracks, args: argparse.Namespace) -> None: + action: str = args.action + if action == "list": + _json(await liked.get(limit=args.limit)) + elif action == "contains": + flags = await liked.contains(args.tracks) + _json( + [ + {"track": track, "liked": flag} + for track, flag in zip(args.tracks, flags, strict=True) + ] + ) + elif action == "add": + await liked.add(args.tracks) + else: + await liked.remove(args.tracks) + + +async def _run_playlist(playlist: Playlist, args: argparse.Namespace) -> None: + action: str = args.action + if action == "items": + items: list[PlaylistEntry] = [] + async with aclosing(playlist.items(limit=args.limit)) as entries: + async for entry in entries: + items.append(entry) + if len(items) == args.limit: + break + _json(items) + elif action == "add": + await playlist.add_tracks(*args.tracks) + elif action == "remove": + await playlist.remove_occurrences(*args.uids) + else: + await playlist.move_occurrences(*args.uids, before=args.before, after=args.after) + + +async def _run_player(player: Player, args: argparse.Namespace) -> None: + action: str = args.action + if action == "status": + _json({"state": player.state, "devices": player.devices}) + elif action == "play": + await player.play(args.resource) + elif action == "seek": + await player.seek(args.milliseconds) + elif action == "volume": + await player.volume(args.percent) + elif action == "queue": + await player.add_to_queue(args.track) + else: + await { + "pause": player.pause, + "resume": player.resume, + "next": player.next, + "previous": player.previous, + }[action]() + + +async def _run_discovery(args: argparse.Namespace) -> None: + command: str = args.command + if command == "charts": + result = Public.list_charts() + elif command == "chart": + result = await Public.get_chart(args.resource) + elif command == "events": + result = await Public.get_artist_events(args.resource) + elif command == "similar-albums": + result = await Public.get_similar_albums(args.resource) + elif command == "colors": + result = await Public.get_colors(args.resource) + else: + result = await get_embed(args.resource) + _json(result) + + +async def _run_download(args: argparse.Namespace) -> None: + media = Media() + if args.kind == "canvas": + canvas = await Public.get_canvas(args.resource) + if canvas is None: + raise ValueError("This track has no Canvas") + destination = await media.download_canvas(canvas, args.output) + else: + source = await get_embed(args.resource) + if args.kind == "cover": + destination = await media.download_cover(source, args.output) + else: + destination = await media.download_preview( + source, args.output, embed_cover=args.embed_cover + ) + _json({"path": str(destination)}) + + +async def _run(args: argparse.Namespace) -> None: + command: str = args.command + if command in {"charts", "chart", "events", "similar-albums", "colors", "embed"}: + await _run_discovery(args) + return + if command == "download": + await _run_download(args) + return + if command == "search": + await _search(args) + return + if command == "get": + _json(await Public.get(args.resource)) + return + if command == "credits": + _json(await Public.get_track_credits(args.track)) + return + if command == "playlist" and args.action == "items" and not args.private: + async with aclosing(Public.get_playlist_items(args.playlist, limit=args.limit)) as pages: + _json((await anext(pages, ()))[: args.limit]) + return + + cookie = os.environ.get("SPOTIFY_COOKIE", "").strip() + if not cookie: + raise ValueError("Set SPOTIFY_COOKIE to use your Spotify account.") + + if command in {"transcript", "lyrics"}: + async with Private.from_cookies(cookie) as account: + helper = account.transcripts if command == "transcript" else account.lyrics + _json(await helper.get(args.resource)) + return + + async with Private.from_cookies(cookie) as account: + if command == "library": + await _run_library(account.liked_tracks, args) + elif command == "playlist": + await _run_playlist(Playlist(account.session, args.playlist), args) + else: + async with Player(account.session).connect() as player: + await _run_player(player, args) + + +def main(argv: Sequence[str] | None = None) -> int: + """Run the requested command and return a process exit code.""" + args = _parser().parse_args(argv) + try: + if args.command == "studio": + if any(importlib.util.find_spec(name) is None for name in ("webview", "dotenv")): + raise RuntimeError('Install Studio with: pip install "spotapi[studio]"') + desktop = importlib.import_module("spotapi._studio.desktop") + desktop.main() + elif args.command == "discover": + dependencies = ("textual", "textual_image", "PIL", "httpx") + if any(importlib.util.find_spec(name) is None for name in dependencies): + raise RuntimeError( + 'Install the terminal browser with: pip install "spotapi[demo]"' + ) + browser = importlib.import_module("spotapi._demo.discover") + browser.main(" ".join(args.query)) + else: + asyncio.run(_run(args)) + except (SpotAPIError, ValueError, RuntimeError, TimeoutError, OSError) as error: + print(f"spotapi: {str(error) or 'Request timed out.'}", file=sys.stderr) + return 1 + except KeyboardInterrupt: + return 130 + + return 0 diff --git a/tests/test_cli.py b/tests/test_cli.py index 311c8dd..2bd444f 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -1 +1,165 @@ -PLACEHOLDER \ No newline at end of file +"""Exercise command output and failure status without network access.""" + +import json +from collections.abc import AsyncGenerator +from contextlib import asynccontextmanager +from types import SimpleNamespace +from unittest.mock import AsyncMock, Mock + +import pytest + +from spotapi import ( + AsyncClient, + AuthSession, + Playlist, + Private, + Public, + SearchResults, + SpotAPIError, +) +from spotapi.cli import main + + +def test_cli_get_outputs_json( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + resource = Public.parse_url("spotify:track:abc") + monkeypatch.setattr(Public, "get", AsyncMock(return_value=resource)) + + assert main(["get", resource.uri]) == 0 + assert json.loads(capsys.readouterr().out)["uri"] == resource.uri + + +def test_cli_reports_the_installed_version( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + monkeypatch.setattr("spotapi.cli.package_version", Mock(return_value="2.1.0")) + + with pytest.raises(SystemExit) as exit_info: + main(["--version"]) + + assert exit_info.value.code == 0 + assert capsys.readouterr().out == "spotapi 2.1.0\n" + + +def test_cli_discover_explains_the_optional_install( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + monkeypatch.setattr("spotapi.cli.importlib.util.find_spec", Mock(return_value=None)) + launch = Mock() + monkeypatch.setattr("spotapi.cli.importlib.import_module", launch) + assert main(["discover", "Daft Punk"]) == 1 + captured = capsys.readouterr() + assert not captured.out + assert 'pip install "spotapi[demo]"' in captured.err + launch.assert_not_called() + + +def test_cli_studio_explains_the_optional_install( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + monkeypatch.setattr("spotapi.cli.importlib.util.find_spec", Mock(return_value=None)) + launch = Mock() + monkeypatch.setattr("spotapi.cli.importlib.import_module", launch) + assert main(["studio"]) == 1 + assert 'pip install "spotapi[studio]"' in capsys.readouterr().err + launch.assert_not_called() + + +def test_cli_studio_lets_the_native_app_own_its_event_loop( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr("spotapi.cli.importlib.util.find_spec", Mock(return_value=object())) + desktop = Mock() + monkeypatch.setattr("spotapi.cli.importlib.import_module", Mock(return_value=desktop)) + runner = Mock(side_effect=AssertionError("Native Studio must own its event loop")) + monkeypatch.setattr("spotapi.cli.asyncio.run", runner) + assert main(["studio"]) == 0 + desktop.main.assert_called_once_with() + + +def test_cli_discover_launches_outside_the_async_runner( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr("spotapi.cli.importlib.util.find_spec", Mock(return_value=object())) + launch = Mock() + monkeypatch.setattr("spotapi.cli.importlib.import_module", Mock(return_value=launch)) + runner = Mock(side_effect=AssertionError("Textual must own its event loop")) + monkeypatch.setattr("spotapi.cli.asyncio.run", runner) + assert main(["discover", "Daft", "Punk"]) == 0 + launch.main.assert_called_once_with("Daft Punk") + runner.assert_not_called() + + +def test_cli_empty_search_keeps_stdout_clean( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + monkeypatch.setattr(Public, "search", AsyncMock(return_value=SearchResults("abc", ("track",)))) + + assert main(["search", "abc"]) == 0 + captured = capsys.readouterr() + assert captured.out == "" + assert "No tracks found" in captured.err + + +def test_cli_reports_spotify_error_without_traceback( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + monkeypatch.setattr(Public, "search", AsyncMock(side_effect=SpotAPIError("Request failed"))) + + assert main(["search", "abc"]) == 1 + assert capsys.readouterr().err == "spotapi: Request failed\n" + + +def test_cli_requires_a_session_for_playlist_changes( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + monkeypatch.delenv("SPOTIFY_COOKIE", raising=False) + + assert main(["playlist", "remove", "playlist", "occurrence"]) == 1 + captured = capsys.readouterr() + assert not captured.out + assert "Set SPOTIFY_COOKIE" in captured.err + + +def test_cli_passes_the_exact_occurrence_to_playlist_move( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + @asynccontextmanager + async def session(cookie: str) -> AsyncGenerator[object, None]: + assert cookie == "test-cookie" + yield SimpleNamespace(session=Mock(spec=AuthSession, client=Mock(spec=AsyncClient))) + + move = AsyncMock() + monkeypatch.setenv("SPOTIFY_COOKIE", "test-cookie") + monkeypatch.setattr(Private, "from_cookies", session) + monkeypatch.setattr(Playlist, "move_occurrences", move) + + assert main(["playlist", "move", "playlist", "second", "--before", "first"]) == 0 + move.assert_awaited_once_with("second", before="first", after=None) + assert not capsys.readouterr().out + + +def test_cli_search_forwards_language( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + mock_search = AsyncMock(return_value=SearchResults("Charlotte Cardin", ("track",))) + monkeypatch.setattr(Public, "search", mock_search) + + assert main(["search", "Charlotte Cardin", "--language", "fr-CA"]) == 0 + mock_search.assert_awaited_once() + call_kwargs = mock_search.await_args.kwargs + assert call_kwargs["language"] == "fr-CA" + assert call_kwargs["query"] == "Charlotte Cardin" + + +def test_cli_search_omits_language_by_default( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + mock_search = AsyncMock(return_value=SearchResults("abc", ("track",))) + monkeypatch.setattr(Public, "search", mock_search) + + assert main(["search", "abc"]) == 0 + mock_search.assert_awaited_once() + call_kwargs = mock_search.await_args.kwargs + assert call_kwargs.get("language") is None