Coverage for downtify/navidrome_ratings.py: 98%
220 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""Gives Navidrome songs 0-5 stars from their Deezer popularity.
3The star scale and the options are ported from dztnr
4(https://github.com/scatolo/dztnr), itself a fork of sptnr
5(https://github.com/krestaino/sptnr). Their MIT licence follows.
7MIT License
9Copyright (c) 2024 Kevin Restaino
11Permission is hereby granted, free of charge, to any person obtaining a copy
12of this software and associated documentation files (the "Software"), to deal
13in the Software without restriction, including without limitation the rights
14to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15copies of the Software, and to permit persons to whom the Software is
16furnished to do so, subject to the following conditions:
18The above copyright notice and this permission notice shall be included in all
19copies or substantial portions of the Software.
21THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27SOFTWARE.
29The first half of the module is pure: the star tables, the options
30sanitiser and the repeat-schedule rule. :class:`RatingRun` walks the
31library and rates songs from Deezer.
32"""
34from __future__ import annotations
36import time
37from collections.abc import Callable
38from datetime import datetime, timedelta, timezone
39from typing import Any, Optional
41from . import deezer
42from .navidrome import SubsonicError
44#: Subsonic error code for "not found" (a song or album removed mid-run).
45SUBSONIC_NOT_FOUND = 70
47#: Deezer error codes worth a retry: quota exceeded, service busy.
48DEEZER_RETRY_CODES = (4, 700)
50#: The options a rating run takes, with their defaults.
51DEFAULTS: dict[str, Any] = {
52 'repeat': 'off',
53 'skip_rated': True,
54 'skip_starred': False,
55 'grading': 'absolute',
56}
58#: Repeat choice -> days between runs (0 means never repeat).
59REPEAT_DAYS = {'off': 0, 'daily': 1, 'weekly': 7, 'monthly': 30}
61#: How a song's Deezer rank is turned into stars.
62GRADINGS = ('absolute', 'artist', 'album')
64#: Seconds to wait between Deezer calls, and before retrying one.
65DEEZER_PAUSE = 0.2
66RETRY_PAUSE = 5.0
68#: A failed run is retried after this long, whatever the repeat is.
69RETRY_AFTER_FAILURE = timedelta(hours=6)
71#: How many songs a preview lists.
72EXAMPLES = 500
74_EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
77def effective_settings(raw: Any) -> dict[str, Any]:
78 """Return a fresh dict holding exactly the known options.
80 Anything missing or invalid falls back to its default.
81 """
82 data = raw if isinstance(raw, dict) else {}
83 repeat = data.get('repeat')
84 grading = data.get('grading')
85 return {
86 'repeat': repeat
87 if repeat in tuple(REPEAT_DAYS)
88 else DEFAULTS['repeat'],
89 'skip_rated': bool(data.get('skip_rated', DEFAULTS['skip_rated'])),
90 'skip_starred': bool(
91 data.get('skip_starred', DEFAULTS['skip_starred'])
92 ),
93 'grading': grading if grading in GRADINGS else DEFAULTS['grading'],
94 }
97def stars_from_rank(rank: int) -> int:
98 """Stars for a Deezer rank (dztnr's ``get_rating_from_rank``)."""
99 rank = int(rank)
100 if rank < 10_000:
101 return 0
102 if rank < 100_000:
103 return 1
104 if rank < 300_000:
105 return 2
106 if rank < 600_000:
107 return 3
108 if rank < 850_000:
109 return 4
110 return 5
113def stars_from_relative_rank(rank: int, top: Optional[int]) -> int:
114 """Stars for a rank relative to the highest one (dztnr's
115 ``get_rating_from_relative_rank``)."""
116 rank = int(rank)
117 if rank <= 0 or top is None or int(top) <= 0:
118 return 0
119 ratio = rank / int(top)
120 if ratio >= 0.80:
121 return 5
122 if ratio >= 0.60:
123 return 4
124 if ratio >= 0.40:
125 return 3
126 if ratio >= 0.20:
127 return 2
128 return 1
131def _started_at(
132 last_rating_run: Optional[dict[str, Any]],
133) -> Optional[datetime]:
134 if not isinstance(last_rating_run, dict):
135 return None
136 try:
137 started = datetime.fromisoformat(last_rating_run['started_at'])
138 except (KeyError, TypeError, ValueError):
139 return None
140 if started.tzinfo is None:
141 started = started.replace(tzinfo=timezone.utc)
142 return started.astimezone(timezone.utc)
145def next_run_at(
146 settings: dict[str, Any], last_rating_run: Optional[dict[str, Any]]
147) -> Optional[datetime]:
148 """When the next scheduled run is due, as an aware UTC datetime.
150 ``None`` when repeat is off. The Unix epoch (so, due now) when there
151 is no usable last run. A failed run is retried after
152 ``RETRY_AFTER_FAILURE``, any other after the repeat interval.
153 """
154 repeat = settings.get('repeat')
155 days = REPEAT_DAYS[repeat] if repeat in tuple(REPEAT_DAYS) else 0
156 if not days:
157 return None
158 started = _started_at(last_rating_run)
159 if started is None:
160 return _EPOCH
161 if last_rating_run.get('state') == 'failed':
162 return started + RETRY_AFTER_FAILURE
163 return started + timedelta(days=days)
166_DEEZER_API = 'https://api.deezer.com'
169class DeezerUnavailable(RuntimeError):
170 """Deezer failed twice in a row; the run cannot go on."""
173def _never() -> bool:
174 return False
177def _ignore(done: int, total: int, step: str) -> None:
178 """Default progress callback: nothing listens."""
181class RatingRun:
182 """One pass over the Navidrome library, rating songs from Deezer.
184 A port of dztnr's walk. ``client`` is a
185 :class:`downtify.navidrome.NavidromeClient`; ``options`` are the
186 :func:`effective_settings`. Navidrome errors are not caught: they
187 reach the caller. With ``preview`` nothing is written.
188 """
190 def __init__(
191 self,
192 client: Any,
193 options: dict[str, Any],
194 *,
195 preview: bool = False,
196 cancelled: Callable[[], bool] = _never,
197 progress: Callable[[int, int, str], None] = _ignore,
198 sleep: Callable[[float], None] = time.sleep,
199 ) -> None:
200 self._client = client
201 self._options = effective_settings(options)
202 self._preview = preview
203 self._cancelled = cancelled
204 self._progress = progress
205 self._sleep = sleep
206 self._stopped = False
207 self._total = 0
208 self._done = 0
209 self._rated = 0
210 self._skipped = 0
211 self._not_found = 0
212 self._changes: list[dict[str, Any]] = []
213 self._unmatched: list[str] = []
214 # Reference ranks, kept even when None so they are not retried.
215 self._artist_tops: dict[str, Optional[int]] = {}
216 self._album_tops: dict[str, Optional[int]] = {}
218 def run(self) -> dict[str, Any]:
219 """Walk the library and rate it; return the summary."""
220 albums = self._library()
221 for artist_name, album_id, song_count in albums:
222 if self._stopped:
223 break
224 try:
225 album = self._client.album(album_id)
226 except SubsonicError as exc:
227 if exc.code != SUBSONIC_NOT_FOUND:
228 raise
229 # Removed since the library pass: skip its songs.
230 self._skipped += song_count
231 self._done += song_count
232 self._progress(
233 self._done, max(self._total, self._done), 'rating'
234 )
235 continue
236 self._rate_album(artist_name, album)
237 return self._summary()
239 # -- the library pass ---------------------------------------------
241 def _library(self) -> list[tuple[str, str, int]]:
242 """Every unique album as ``(navidrome artist name, album id,
243 listed song count)``."""
244 artists = self._client.artists()
245 seen: set[str] = set()
246 albums: list[tuple[str, str, int]] = []
247 for index, artist in enumerate(artists, start=1):
248 if self._cancelled():
249 self._stopped = True
250 break
251 for album in self._client.artist_albums(artist['id']):
252 if album['id'] in seen:
253 continue
254 seen.add(album['id'])
255 count = int(album.get('song_count') or 0)
256 albums.append((artist['name'], album['id'], count))
257 self._total += count
258 self._progress(index, len(artists), 'library')
259 return albums
261 # -- the rating pass ----------------------------------------------
263 def _rate_album(self, artist_name: str, album: dict[str, Any]) -> None:
264 for song in album['songs']:
265 if self._cancelled():
266 self._stopped = True
267 return
268 self._rate_song(artist_name, album, song)
269 self._done += 1
270 self._progress(self._done, max(self._total, self._done), 'rating')
272 def _wants_skip(self, song: dict[str, Any]) -> bool:
273 if self._options['skip_starred'] and song['starred']:
274 return True
275 return bool(self._options['skip_rated'] and song['rating'] > 0)
277 def _rate_song(
278 self, artist_name: str, album: dict[str, Any], song: dict[str, Any]
279 ) -> None:
280 if self._wants_skip(song):
281 self._skipped += 1
282 return
283 top = self._reference(artist_name, album)
284 rank = self._song_rank(f'{album["artist"]} {song["title"]}')
285 if rank is None:
286 self._not_found += 1
287 if len(self._unmatched) < EXAMPLES:
288 self._unmatched.append(
289 f'{album["artist"]} – {album["name"]} – {song["title"]}'
290 )
291 return
292 stars = (
293 stars_from_relative_rank(rank, top)
294 if top
295 else stars_from_rank(rank)
296 )
297 if not self._preview and stars != song['rating']:
298 try:
299 self._client.set_rating(song['id'], stars)
300 except SubsonicError as exc:
301 if exc.code != SUBSONIC_NOT_FOUND:
302 raise
303 # Removed since the album was read.
304 self._skipped += 1
305 return
306 self._rated += 1
307 if len(self._changes) < EXAMPLES:
308 self._changes.append({
309 'artist': album['artist'],
310 'album': album['name'],
311 'title': song['title'],
312 'rank': rank,
313 'stars': stars,
314 'was': song['rating'],
315 })
317 # -- Deezer -------------------------------------------------------
319 def _call(self, url: str, **params: Any) -> dict[str, Any]:
320 """A Deezer GET, paced.
322 A transport failure, quota (4) or busy (700) is retried once,
323 then :class:`DeezerUnavailable`. Any other refusal (such as 800,
324 no data) is final for that item and reads as an empty answer.
325 """
326 data: dict[str, Any] = {}
327 for attempt in (1, 2):
328 try:
329 data = deezer._get_json(url, **params)
330 break
331 except deezer.DeezerRefused as exc:
332 if exc.code not in DEEZER_RETRY_CODES:
333 data = {}
334 break
335 failure: ValueError = exc
336 except ValueError as exc:
337 failure = exc
338 if attempt == 2:
339 raise DeezerUnavailable('Deezer is not answering') from failure
340 self._sleep(RETRY_PAUSE)
341 self._sleep(DEEZER_PAUSE)
342 return data
344 @staticmethod
345 def _rows(data: dict[str, Any]) -> list[dict[str, Any]]:
346 rows = data.get('data')
347 if not isinstance(rows, list):
348 return []
349 return [row for row in rows if isinstance(row, dict)]
351 def _song_rank(self, query: str) -> Optional[int]:
352 rows = self._rows(self._call(f'{_DEEZER_API}/search', q=query))
353 rank = rows[0].get('rank') if rows else None
354 return None if rank is None else int(rank)
356 def _top_rank(self, url: str, **params: Any) -> Optional[int]:
357 rows = self._rows(self._call(url, **params))
358 ranks = [int(r['rank']) for r in rows if r.get('rank') is not None]
359 return max(ranks) if ranks else None
361 def _reference(
362 self, artist_name: str, album: dict[str, Any]
363 ) -> Optional[int]:
364 """The rank relative grading compares to, or ``None`` (absolute)."""
365 grading = self._options['grading']
366 if grading == 'artist':
367 if artist_name not in self._artist_tops:
368 self._artist_tops[artist_name] = self._artist_top(artist_name)
369 return self._artist_tops[artist_name]
370 if grading == 'album':
371 if album['id'] not in self._album_tops:
372 self._album_tops[album['id']] = self._album_top(album)
373 return self._album_tops[album['id']]
374 return None
376 def _artist_top(self, artist_name: str) -> Optional[int]:
377 # Deezer's first hit is often a namesake with a handful of fans:
378 # take the exact name with the most fans instead.
379 rows = self._rows(
380 self._call(f'{_DEEZER_API}/search/artist', q=artist_name, limit=25)
381 )
382 match = deezer._most_popular_exact_match(rows, artist_name)
383 found = match.get('id') if match else None
384 if found is None:
385 return None
386 return self._top_rank(f'{_DEEZER_API}/artist/{found}/top', limit=100)
388 def _album_top(self, album: dict[str, Any]) -> Optional[int]:
389 # The album artist on Deezer is often the composer, so only the
390 # title has to match exactly (a single or mashup ranks first).
391 rows = self._rows(
392 self._call(
393 f'{_DEEZER_API}/search/album',
394 q=f'{album["artist"]} {album["name"]}',
395 limit=25,
396 )
397 )
398 wanted = deezer.file_name_key(album['name'])
399 found = next(
400 (
401 row.get('id')
402 for row in rows
403 if wanted
404 and deezer.file_name_key(str(row.get('title') or '')) == wanted
405 ),
406 None,
407 )
408 if found is None:
409 return None
410 return self._top_rank(f'{_DEEZER_API}/album/{found}/tracks')
412 def _summary(self) -> dict[str, Any]:
413 return {
414 'state': 'stopped' if self._stopped else 'done',
415 'preview': self._preview,
416 'total': self._total,
417 'rated': self._rated,
418 'skipped': self._skipped,
419 'not_found': self._not_found,
420 'changes': self._changes,
421 'unmatched': self._unmatched,
422 }