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

1"""Gives Navidrome songs 0-5 stars from their Deezer popularity. 

2 

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. 

6 

7MIT License 

8 

9Copyright (c) 2024 Kevin Restaino 

10 

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: 

17 

18The above copyright notice and this permission notice shall be included in all 

19copies or substantial portions of the Software. 

20 

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. 

28 

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""" 

33 

34from __future__ import annotations 

35 

36import time 

37from collections.abc import Callable 

38from datetime import datetime, timedelta, timezone 

39from typing import Any, Optional 

40 

41from . import deezer 

42from .navidrome import SubsonicError 

43 

44#: Subsonic error code for "not found" (a song or album removed mid-run). 

45SUBSONIC_NOT_FOUND = 70 

46 

47#: Deezer error codes worth a retry: quota exceeded, service busy. 

48DEEZER_RETRY_CODES = (4, 700) 

49 

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} 

57 

58#: Repeat choice -> days between runs (0 means never repeat). 

59REPEAT_DAYS = {'off': 0, 'daily': 1, 'weekly': 7, 'monthly': 30} 

60 

61#: How a song's Deezer rank is turned into stars. 

62GRADINGS = ('absolute', 'artist', 'album') 

63 

64#: Seconds to wait between Deezer calls, and before retrying one. 

65DEEZER_PAUSE = 0.2 

66RETRY_PAUSE = 5.0 

67 

68#: A failed run is retried after this long, whatever the repeat is. 

69RETRY_AFTER_FAILURE = timedelta(hours=6) 

70 

71#: How many songs a preview lists. 

72EXAMPLES = 500 

73 

74_EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc) 

75 

76 

77def effective_settings(raw: Any) -> dict[str, Any]: 

78 """Return a fresh dict holding exactly the known options. 

79 

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 } 

95 

96 

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 

111 

112 

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 

129 

130 

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) 

143 

144 

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. 

149 

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) 

164 

165 

166_DEEZER_API = 'https://api.deezer.com' 

167 

168 

169class DeezerUnavailable(RuntimeError): 

170 """Deezer failed twice in a row; the run cannot go on.""" 

171 

172 

173def _never() -> bool: 

174 return False 

175 

176 

177def _ignore(done: int, total: int, step: str) -> None: 

178 """Default progress callback: nothing listens.""" 

179 

180 

181class RatingRun: 

182 """One pass over the Navidrome library, rating songs from Deezer. 

183 

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 """ 

189 

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]] = {} 

217 

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() 

238 

239 # -- the library pass --------------------------------------------- 

240 

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 

260 

261 # -- the rating pass ---------------------------------------------- 

262 

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') 

271 

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) 

276 

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 }) 

316 

317 # -- Deezer ------------------------------------------------------- 

318 

319 def _call(self, url: str, **params: Any) -> dict[str, Any]: 

320 """A Deezer GET, paced. 

321 

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 

343 

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)] 

350 

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) 

355 

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 

360 

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 

375 

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) 

387 

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') 

411 

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 }