tunewrangler 1.0.0__tar.gz

tunewrangler-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Chabot-Leclerc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tunewrangler-1.0.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: tunewrangler
+Version: 1.0.0
+Author: Alexandre Chabot-Leclerc
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: spotipy
+Requires-Dist: notify-py
+Requires-Dist: platformdirs
+Requires-Dist: pylast
+Requires-Dist: keyring
+Dynamic: license-file
+
+## Install requirements
+
+```
+uv sync --group dev
+```
+
+For notifications, the script uses [Notificator](https://github.com/vitorgalvao/notificator). It's in the same repo as this project.
+
+
+Add your service credentials in the Login keychain under the names:
+
+- tunewrangler-spotify-client-id
+- tunewrangler-spotify-client-secret
+- tunewrangler-last-fm-api-key
+- tunewrangler-last-fm-password
+- tunewrangler-last-fm-shared-secret
+- tunewrangler-tidal-client-id
+- tunewrangler-tidal-redirect-uri
+
+TIDAL also supports environment overrides:
+
+- `TUNEWRANGLER_TIDAL_CLIENT_ID`
+- `TUNEWRANGLER_TIDAL_REDIRECT_URI`
+- `TUNEWRANGLER_TIDAL_SCOPES`
+
+The default TIDAL OAuth scopes are:
+
+```text
+search.read collection.read collection.write playlists.read playlists.write
+```
+
+TIDAL folder access uses separate folder-capable session data. TuneWrangler
+automatically prompts for TIDAL device login when a folder command needs it and
+stores that folder session inside `tidal-session.json`.
+
+## Usage
+
+Save current track in Spotify and "Love" the track on LastFM.
+
+```
+uv run tunewrangler save track
+```
+
+Favorite the current track by saving it to your library and this year's
+playlist.
+
+```
+uv run tunewrangler favorite track
+```
+
+Favorite the current album by saving it to your library and this year's albums
+playlist.
+
+```
+uv run tunewrangler favorite album
+```
+
+Create a playlist from the currently playing album.
+
+```
+uv run tunewrangler collect album
+```
+
+
+Show CLI help
+
+```
+uv run tunewrangler --help
+uv run python -m tunewrangler --help
+```
+
+Run tests and style tools:
+
+```
+uv run pytest
+uv run pytest --cov
+uv run black .
+uv run pycodestyle
+```
+
+The coverage run reports branch and line coverage for `tunewrangler`, including
+the line numbers that are not covered.
+
+## Publishing to PyPI
+
+The [publish workflow](.github/workflows/publish.yml) builds and checks a wheel
+and source distribution when a GitHub release is published, then uploads them
+using [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
+No PyPI API token or GitHub secret is needed.
+
+Before the first release:
+
+1. Create a GitHub Actions environment named `pypi` in this repository's
+   **Settings → Environments**.
+2. Configure a GitHub trusted publisher on PyPI with these values:
+
+   | Field | Value |
+   | --- | --- |
+   | PyPI project name | `tunewrangler` |
+   | Owner | `achabotl` |
+   | Repository | `tunewrangler` |
+   | Workflow filename | `publish.yml` |
+   | Environment | `pypi` |
+
+   For a new project, use [PyPI's pending publisher form](https://pypi.org/manage/account/publishing/).
+   For an existing project you own, add the publisher under **Manage → Publishing**.
+
+For each release:
+
+1. Set a new, unused `version` in `pyproject.toml` and run `uv lock` to update
+   the lockfile. Run `uv run pytest` and commit the changes.
+2. Merge the publishing workflow and version changes into `main`.
+3. Create and publish a GitHub release targeting that commit with a matching
+   tag, such as `v1.0.0` for version `1.0.0`.
+4. Check that the **Publish to PyPI** workflow succeeds in GitHub Actions.
+
+Draft releases do not publish. Publishing a release (including a prerelease)
+uploads to the real PyPI index. The version comes from `pyproject.toml`; the
+workflow does not derive it from the tag. PyPI does not allow reusing a published
+version.
+
+## Documentation of Dependencies
+
+### Spotify
+
+- [Spotipy!](https://spotipy.readthedocs.io/) and its [examples](https://github.com/plamere/spotipy/tree/master/examples)
+- [Spotify API docs](https://developer.spotify.com/documentation/web-api/reference/)
+
+### Last.FM
+
+- [Last.fm API docs](https://www.last.fm/api/rest)
+- Python package: [pylast · PyPI](https://pypi.org/project/pylast/)
+

tunewrangler-1.0.0/README.md

@@ -0,0 +1,133 @@
+## Install requirements
+
+```
+uv sync --group dev
+```
+
+For notifications, the script uses [Notificator](https://github.com/vitorgalvao/notificator). It's in the same repo as this project.
+
+
+Add your service credentials in the Login keychain under the names:
+
+- tunewrangler-spotify-client-id
+- tunewrangler-spotify-client-secret
+- tunewrangler-last-fm-api-key
+- tunewrangler-last-fm-password
+- tunewrangler-last-fm-shared-secret
+- tunewrangler-tidal-client-id
+- tunewrangler-tidal-redirect-uri
+
+TIDAL also supports environment overrides:
+
+- `TUNEWRANGLER_TIDAL_CLIENT_ID`
+- `TUNEWRANGLER_TIDAL_REDIRECT_URI`
+- `TUNEWRANGLER_TIDAL_SCOPES`
+
+The default TIDAL OAuth scopes are:
+
+```text
+search.read collection.read collection.write playlists.read playlists.write
+```
+
+TIDAL folder access uses separate folder-capable session data. TuneWrangler
+automatically prompts for TIDAL device login when a folder command needs it and
+stores that folder session inside `tidal-session.json`.
+
+## Usage
+
+Save current track in Spotify and "Love" the track on LastFM.
+
+```
+uv run tunewrangler save track
+```
+
+Favorite the current track by saving it to your library and this year's
+playlist.
+
+```
+uv run tunewrangler favorite track
+```
+
+Favorite the current album by saving it to your library and this year's albums
+playlist.
+
+```
+uv run tunewrangler favorite album
+```
+
+Create a playlist from the currently playing album.
+
+```
+uv run tunewrangler collect album
+```
+
+
+Show CLI help
+
+```
+uv run tunewrangler --help
+uv run python -m tunewrangler --help
+```
+
+Run tests and style tools:
+
+```
+uv run pytest
+uv run pytest --cov
+uv run black .
+uv run pycodestyle
+```
+
+The coverage run reports branch and line coverage for `tunewrangler`, including
+the line numbers that are not covered.
+
+## Publishing to PyPI
+
+The [publish workflow](.github/workflows/publish.yml) builds and checks a wheel
+and source distribution when a GitHub release is published, then uploads them
+using [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
+No PyPI API token or GitHub secret is needed.
+
+Before the first release:
+
+1. Create a GitHub Actions environment named `pypi` in this repository's
+   **Settings → Environments**.
+2. Configure a GitHub trusted publisher on PyPI with these values:
+
+   | Field | Value |
+   | --- | --- |
+   | PyPI project name | `tunewrangler` |
+   | Owner | `achabotl` |
+   | Repository | `tunewrangler` |
+   | Workflow filename | `publish.yml` |
+   | Environment | `pypi` |
+
+   For a new project, use [PyPI's pending publisher form](https://pypi.org/manage/account/publishing/).
+   For an existing project you own, add the publisher under **Manage → Publishing**.
+
+For each release:
+
+1. Set a new, unused `version` in `pyproject.toml` and run `uv lock` to update
+   the lockfile. Run `uv run pytest` and commit the changes.
+2. Merge the publishing workflow and version changes into `main`.
+3. Create and publish a GitHub release targeting that commit with a matching
+   tag, such as `v1.0.0` for version `1.0.0`.
+4. Check that the **Publish to PyPI** workflow succeeds in GitHub Actions.
+
+Draft releases do not publish. Publishing a release (including a prerelease)
+uploads to the real PyPI index. The version comes from `pyproject.toml`; the
+workflow does not derive it from the tag. PyPI does not allow reusing a published
+version.
+
+## Documentation of Dependencies
+
+### Spotify
+
+- [Spotipy!](https://spotipy.readthedocs.io/) and its [examples](https://github.com/plamere/spotipy/tree/master/examples)
+- [Spotify API docs](https://developer.spotify.com/documentation/web-api/reference/)
+
+### Last.FM
+
+- [Last.fm API docs](https://www.last.fm/api/rest)
+- Python package: [pylast · PyPI](https://pypi.org/project/pylast/)
+

tunewrangler-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "tunewrangler"
+version = "1.0.0"
+authors = [{name = "Alexandre Chabot-Leclerc"}]
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+dependencies=[
+    "click",
+    "spotipy",
+    "notify-py",
+    "platformdirs",
+    "pylast",
+    "keyring",
+]
+
+[dependency-groups]
+dev = [
+    "black",
+    "pycodestyle",
+    "pytest>=7.0",
+    "pytest-cov>=7.0",
+    "pytest-mock>=3.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["tunewrangler"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 85
+
+[tool.setuptools.packages.find]
+include = ["tunewrangler*"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project.scripts]
+tunewrangler = "tunewrangler.cli:cli"

tunewrangler-1.0.0/setup.cfg

@@ -0,0 +1,8 @@
+[pycodestyle]
+max_line_length = 88
+exclude = .git,__pycache__,.venv,.direnv,build,dist,tunewrangler.egg-info,python-tidal
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

tunewrangler-1.0.0/tests/test_cli.py

@@ -0,0 +1,172 @@
+from unittest.mock import Mock, call, patch
+
+import pytest
+from click.testing import CliRunner
+
+from tunewrangler.cli import Client, cli, notify
+from tunewrangler.errors import NotPlayingError, PlaylistExistsError, TrackNotFoundError
+from tunewrangler.tidal_api import TidalRateLimitError, TidalUnsupportedFeatureError
+
+
+def test_notify_returns_when_helper_is_missing():
+    with (
+        patch("tunewrangler.cli.shutil.which", return_value=None),
+        patch("tunewrangler.cli.subprocess.run") as run,
+    ):
+        notify("Title", "Message", "Subtitle")
+    run.assert_not_called()
+
+
+def test_notify_invokes_helper_with_all_arguments():
+    with (
+        patch("tunewrangler.cli.shutil.which", return_value="helper"),
+        patch("tunewrangler.cli.subprocess.run") as run,
+    ):
+        notify("Title", "Message", "Subtitle")
+    command = run.call_args.args[0]
+    assert "TuneWranglerNotificator.app" in str(command[0])
+    assert command[1:] == [
+        "--title",
+        "Title",
+        "--subtitle",
+        "Subtitle",
+        "--message",
+        "Message",
+    ]
+
+
+def test_client_sound_workflows_delegate():
+    music = Mock()
+    lastfm = Mock()
+    music.save_current_track.return_value = ("Artist", "Track", "track-1")
+    music.save_current_album.return_value = ("Artist", "Album")
+    client = Client(music, lastfm)
+
+    client.save_current_track()
+    client.save_current_album()
+    client.favorite_current_track()
+    client.favorite_current_album()
+
+    music.save_track_to_weekly_playlist.assert_called_once_with("track-1")
+    lastfm.save_track.assert_called_once_with("Artist", "Track")
+    music.save_current_album.assert_called_once_with()
+    music.favorite_current_track.assert_called_once_with()
+    music.favorite_current_album.assert_called_once_with()
+
+
+@pytest.mark.parametrize(
+    ("error", "title"),
+    [
+        (NotPlayingError(), "Nothing Playing"),
+        (PlaylistExistsError(), "Album already exists"),
+        (TrackNotFoundError(), "Track Not Found"),
+    ],
+)
+def test_collect_album_maps_known_errors_to_notifications(error, title):
+    music = Mock()
+    music.save_album_of_current_track_in_new_playlist.side_effect = error
+    with patch("tunewrangler.cli.notify") as notify_mock:
+        Client(music, None).save_album_of_current_track_in_new_playlist()
+    assert any(title in item.args[0] for item in notify_mock.call_args_list)
+
+
+def invoke_with_clients(arguments, music=None, lastfm=None):
+    music = music or Mock()
+    lastfm = lastfm or Mock()
+    with (
+        patch("tunewrangler.cli.TidalClient", return_value=music),
+        patch("tunewrangler.cli.SpotifyClient", return_value=music),
+        patch("tunewrangler.cli.LastFmClient", return_value=lastfm),
+    ):
+        result = CliRunner().invoke(cli, arguments, obj={})
+    return result, music, lastfm
+
+
+def test_spotify_service_selection_and_multi_playlist_output():
+    music = Mock()
+    music.list_playlist_names.return_value = ["Alpha", "Beta"]
+    result, _, _ = invoke_with_clients(
+        ["--service", "spotify", "list", "playlists"], music=music
+    )
+    assert result.exit_code == 0
+    assert result.output == "Alpha\nBeta\n"
+    music.authenticate.assert_called_once_with()
+
+
+@pytest.mark.parametrize(
+    ("arguments", "method", "output"),
+    [
+        (["url", "track"], "get_url_of_current_track", "https://track"),
+        (["url", "album"], "get_url_of_current_album", "https://album"),
+        (["url", "weekly"], "get_weekly_playlist_url", "https://weekly"),
+    ],
+)
+def test_url_commands(arguments, method, output):
+    music = Mock()
+    getattr(music, method).return_value = output
+    result, _, _ = invoke_with_clients(arguments, music=music)
+    assert result.exit_code == 0
+    assert result.output.strip() == output
+
+
+def test_refresh_tidal_unsupported_is_clean_click_error():
+    music = Mock()
+    music.update_playlist_cache.side_effect = TidalUnsupportedFeatureError(
+        "TIDAL playlist cache refresh is not supported."
+    )
+    result, _, _ = invoke_with_clients(["refresh", "playlists"], music=music)
+    assert result.exit_code == 1
+    assert "Error: TIDAL playlist cache refresh is not supported." in result.output
+    assert "Traceback" not in result.output
+
+
+@pytest.mark.parametrize(
+    "error",
+    [TidalRateLimitError("slow down"), TrackNotFoundError("not found")],
+)
+def test_sound_commands_map_domain_errors(error):
+    music = Mock()
+    music.authenticate.side_effect = error
+    result, _, _ = invoke_with_clients(["save", "album"], music=music)
+    assert result.exit_code == 1
+    assert str(error) in result.output
+
+
+@pytest.mark.parametrize(
+    ("service", "answers", "expected_calls", "success"),
+    [
+        (
+            "spotify",
+            ["client", "secret"],
+            2,
+            "Spotify keys set successfully.",
+        ),
+        (
+            "lastfm",
+            ["key", "secret", "password"],
+            3,
+            "LastFM keys set successfully.",
+        ),
+        (
+            "tidal",
+            ["client", "http://callback"],
+            2,
+            "TIDAL keys set successfully.",
+        ),
+    ],
+)
+def test_auth_set_for_every_service(service, answers, expected_calls, success):
+    with (
+        patch("tunewrangler.cli.getpass", side_effect=answers),
+        patch("tunewrangler.cli.keyring.set_password") as set_password,
+    ):
+        result = CliRunner().invoke(cli, ["auth", "set", "--service", service], obj={})
+    assert result.exit_code == 0
+    assert success in result.output
+    assert set_password.call_count == expected_calls
+
+
+def test_auth_set_requires_service():
+    result = CliRunner().invoke(cli, ["auth", "set"], obj={})
+    assert result.exit_code == 0
+    assert "Please specify a service" in result.output

tunewrangler-1.0.0/tests/test_last_fm_client.py

@@ -0,0 +1,75 @@
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+import pytest
+
+from tunewrangler.errors import AuthenticationError
+from tunewrangler.last_fm_client import LastFmClient, missing_key_message
+
+
+def test_missing_key_message_points_to_auth_command():
+    message = missing_key_message("example-key")
+    assert "example-key" in message
+    assert "tunewrangler auth set" in message
+
+
+@pytest.mark.parametrize(
+    ("values", "missing_name"),
+    [
+        ([None], "api-key"),
+        (["key", None], "shared-secret"),
+        (["key", "secret", None], "password"),
+    ],
+)
+@patch("tunewrangler.last_fm_client.keyring.get_password")
+def test_authenticate_reports_each_missing_credential(
+    get_password, values, missing_name
+):
+    get_password.side_effect = values
+
+    with pytest.raises(AuthenticationError, match=missing_name):
+        LastFmClient().authenticate()
+
+
+@patch("tunewrangler.last_fm_client.pylast.LastFMNetwork")
+@patch("tunewrangler.last_fm_client.pylast.md5", return_value="password-hash")
+@patch("tunewrangler.last_fm_client.keyring.get_password")
+def test_authenticate_builds_network(get_password, md5, network):
+    get_password.side_effect = ["api-key", "shared-secret", "password"]
+    client = LastFmClient()
+
+    client.authenticate()
+
+    md5.assert_called_once_with("password")
+    network.assert_called_once_with(
+        api_key="api-key",
+        api_secret="shared-secret",
+        username=client.username,
+        password_hash="password-hash",
+    )
+    assert client.lastfm is network.return_value
+
+
+@patch(
+    "tunewrangler.last_fm_client.keyring.get_password",
+    side_effect=RuntimeError("keychain failed"),
+)
+def test_authenticate_maps_unexpected_failures(_get_password):
+    with pytest.raises(AuthenticationError, match="Can't authenticate"):
+        LastFmClient().authenticate()
+
+
+def test_save_track_looks_up_and_loves_track():
+    track = SimpleNamespace(
+        artist=SimpleNamespace(name="Artist One"),
+        title="Track One",
+        love=Mock(),
+    )
+    client = LastFmClient()
+    client.lastfm = Mock()
+    client.lastfm.get_track.return_value = track
+
+    client.save_track("Artist One", "Track One")
+
+    client.lastfm.get_track.assert_called_once_with("Artist One", "Track One")
+    track.love.assert_called_once_with()

tunewrangler-1.0.0/tests/test_notification_launcher.py

@@ -0,0 +1,65 @@
+"""Exercise launcher arguments without launching a GUI app or posting notifications."""
+
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+import pytest
+
+
+@pytest.mark.parametrize("open_status", [0, 73])
+def test_launcher_uses_launchservices_and_preserves_literal_arguments(
+    tmp_path, open_status
+):
+    app = tmp_path / "App With Spaces.app"
+    scripts = app / "Contents/Resources/Scripts"
+    scripts.mkdir(parents=True)
+    launcher = scripts / "notificator"
+    shutil.copyfile(
+        Path(__file__).resolve().parents[1] / "notifications/notificator", launcher
+    )
+    executable = app / "Contents/MacOS/applet"
+    executable.parent.mkdir()
+    executable.write_text("#!/bin/sh\nexit 99\n")
+    executable.chmod(0o755)
+    command_dir = tmp_path / "bin"
+    command_dir.mkdir()
+    capture = tmp_path / "open-arguments.json"
+    open_command = command_dir / "open"
+    open_command.write_text(
+        f"#!{sys.executable}\n"
+        "import json, os, pathlib, sys\n"
+        "destination = pathlib.Path(os.environ['OPEN_ARGUMENTS'])\n"
+        "destination.write_text(json.dumps(sys.argv[1:]))\n"
+        "sys.exit(int(os.environ['OPEN_STATUS']))\n"
+    )
+    open_command.chmod(0o755)
+    message = 'Literal $(exit 42) `exit 42` "quoted" text\nsecond line'
+    title = "--literal-title"
+    result = subprocess.run(
+        ["/bin/bash", str(launcher), "--message", message, "--title", title],
+        env={
+            **os.environ,
+            "PATH": str(command_dir) + os.pathsep + os.environ["PATH"],
+            "OPEN_ARGUMENTS": str(capture),
+            "OPEN_STATUS": str(open_status),
+        },
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    assert result.returncode == open_status, result.stderr
+    assert json.loads(capture.read_text()) == [
+        "-n",
+        "-g",
+        "-W",
+        str(app),
+        "--args",
+        message,
+        title,
+        "",
+        "",
+    ]