Coverage for downtify/playlist_hidden.py: 98%

242 statements  

« prev     ^ index     » next       coverage.py v7.17.4, created at 2026-11-21 22:18 +0000

1"""Songs an owner took out of an imported playlist - and keeps out. 

2 

3An imported playlist (downloaded from a Spotify, YouTube Music or Deezer 

4link, often kept up to date by a Playlist Monitor watch) follows its 

5source: a sweep rewrites its M3U from the source's track list and 

6*Download missing* offers whatever the library lacks, so a song taken 

7out of the M3U by hand would come straight back. Hiding remembers the 

8song for that playlist, so every one of those paths leaves it out: 

9 

10* its line leaves the M3U at once - the audio file stays in the library 

11 (deleting it is the Library's own *Delete*); 

12* watch sweeps neither list it nor download it again, even once its file 

13 is deleted; 

14* it doesn't count as missing, so *Download missing* skips it; 

15* downloading the playlist again from its link keeps it out of the M3U. 

16 

17The source playlist itself is never changed: Downtify reads Spotify and 

18YouTube Music anonymously and can't edit them. 

19 

20A hidden song is remembered by its source track id (a Spotify track id 

21or a YouTube video id - what sweeps and the completeness reports compare) 

22when one is known, and always by its library path and content key, so 

23playlists with no source id (older downloads) work too. Rows are keyed by 

24the playlist's sanitized, casefolded name - the M3U's stem - so a watch's 

25raw name (``Top 50: USA``) and the listing's (``Top 50 USA``) find the 

26same rows. Library-created playlists don't need any of this: removing a 

27song from one is simply editing it. 

28""" 

29 

30from __future__ import annotations 

31 

32import threading 

33from dataclasses import dataclass 

34from datetime import datetime, timezone 

35from pathlib import Path 

36from typing import TYPE_CHECKING, Any, Iterable, Optional 

37 

38from . import m3u 

39from .db.config import Dialect 

40from .db.core import Connection, Database, as_database 

41from .db.dialect import insertion_order_col 

42from .library_cache_keys import file_content_key 

43from .library_catalog import LibraryContext, resolve_library_file 

44from .library_paths_cache import invalidate_library_paths_cache 

45from .track_index import normalize_spotify_track_id 

46 

47if TYPE_CHECKING: 

48 from .monitor import PlaylistMonitorDB 

49 from .playlist_catalog import PlaylistCatalog 

50 

51#: Most songs one request may hide or show again. 

52MAX_SONGS_PER_EDIT = 500 

53 

54 

55def _now_iso() -> str: 

56 return datetime.now(timezone.utc).isoformat() 

57 

58 

59def _norm_path(path: Any) -> str: 

60 return str(path or '').strip().replace('\\', '/') 

61 

62 

63def hidden_key(name: Any) -> str: 

64 """The stored key of a playlist: its M3U stem, case-insensitively.""" 

65 

66 text = str(name or '').strip() 

67 return m3u.sanitize_playlist_name(text).casefold() if text else '' 

68 

69 

70def _item_key(track_id: str, content_key: str, path: str) -> str: 

71 if track_id: 

72 return track_id 

73 if content_key: 

74 return f'key:{content_key}' 

75 return f'file:{path}' 

76 

77 

78@dataclass(frozen=True) 

79class HiddenSongs: 

80 """One playlist's hidden songs, ready to test source rows and library 

81 files against.""" 

82 

83 track_ids: frozenset[str] = frozenset() 

84 files: frozenset[str] = frozenset() 

85 content_keys: frozenset[str] = frozenset() 

86 

87 def __bool__(self) -> bool: 

88 return bool(self.track_ids or self.files or self.content_keys) 

89 

90 def hides_song(self, song: dict[str, Any]) -> bool: 

91 """Whether a source row (``song_id``: Spotify id or video id) is 

92 hidden.""" 

93 

94 if not self.track_ids: 

95 return False 

96 raw = str(song.get('song_id') or '').strip() 

97 if raw and raw in self.track_ids: 

98 return True 

99 spotify_id = normalize_spotify_track_id(song) 

100 return bool(spotify_id) and spotify_id in self.track_ids 

101 

102 def hides_file(self, path: Any, content_key: str = '') -> bool: 

103 """Whether a library file is hidden, by path or content key.""" 

104 

105 normal = _norm_path(path) 

106 if normal and normal in self.files: 

107 return True 

108 return bool(content_key) and content_key in self.content_keys 

109 

110 

111class PlaylistHiddenSongs: 

112 """The hidden songs of every playlist, in ``downtify_library.db``.""" 

113 

114 def __init__(self, path_or_db: str | Path | Database) -> None: 

115 self.db = as_database(path_or_db, 'library') 

116 if isinstance(path_or_db, Database): 

117 self._path = str(self.db.path) if self.db.path else None 

118 else: 

119 self._path = str(path_or_db) 

120 self._lock = threading.Lock() 

121 self._loaded: Optional[dict[str, HiddenSongs]] = None 

122 self._init_db() 

123 

124 def _connect(self) -> Connection: 

125 return self.db.connect() 

126 

127 def _init_db(self) -> None: 

128 # PostgreSQL: the library migrations already created the table. 

129 if self.db.dialect is not Dialect.SQLITE: 

130 return 

131 with self._connect() as conn: 

132 conn.execute(""" 

133 CREATE TABLE IF NOT EXISTS playlist_hidden_songs ( 

134 name_key TEXT NOT NULL, 

135 item_key TEXT NOT NULL, 

136 track_id TEXT NOT NULL DEFAULT '', 

137 content_key TEXT NOT NULL DEFAULT '', 

138 file TEXT NOT NULL DEFAULT '', 

139 label TEXT NOT NULL DEFAULT '', 

140 extinf TEXT NOT NULL DEFAULT '', 

141 position INTEGER NOT NULL DEFAULT -1, 

142 hidden_at TEXT NOT NULL, 

143 PRIMARY KEY (name_key, item_key) 

144 ) 

145 """) 

146 conn.execute(""" 

147 CREATE INDEX IF NOT EXISTS idx_playlist_hidden_content_key 

148 ON playlist_hidden_songs (content_key) 

149 """) 

150 

151 def _changed(self) -> None: 

152 self._loaded = None 

153 

154 def _all(self) -> dict[str, HiddenSongs]: 

155 with self._lock: 

156 if self._loaded is None: 

157 self._loaded = self._load() 

158 return self._loaded 

159 

160 def _load(self) -> dict[str, HiddenSongs]: 

161 grouped: dict[str, tuple[set[str], set[str], set[str]]] = {} 

162 with self._connect() as conn: 

163 rows = conn.execute( 

164 'SELECT name_key, track_id, content_key, file ' 

165 'FROM playlist_hidden_songs' 

166 ).fetchall() 

167 for row in rows: 

168 ids, files, keys = grouped.setdefault( 

169 row['name_key'], (set(), set(), set()) 

170 ) 

171 if row['track_id']: 

172 ids.add(row['track_id']) 

173 if row['file']: 

174 files.add(row['file']) 

175 if row['content_key']: 

176 keys.add(row['content_key']) 

177 return { 

178 name: HiddenSongs( 

179 frozenset(ids), frozenset(files), frozenset(keys) 

180 ) 

181 for name, (ids, files, keys) in grouped.items() 

182 } 

183 

184 def songs(self, name: Any) -> HiddenSongs: 

185 """What playlist *name* hides (empty when nothing).""" 

186 

187 return self._all().get(hidden_key(name), HiddenSongs()) 

188 

189 def counts(self) -> dict[str, int]: 

190 """``{playlist key: number of hidden songs}``, for the listing.""" 

191 

192 with self._connect() as conn: 

193 rows = conn.execute( 

194 'SELECT name_key, COUNT(*) AS n FROM playlist_hidden_songs ' 

195 'GROUP BY name_key' 

196 ).fetchall() 

197 return {str(row['name_key']): int(row['n']) for row in rows} 

198 

199 def hide( 

200 self, 

201 name: Any, 

202 *, 

203 track_id: str = '', 

204 content_key: str = '', 

205 path: str = '', 

206 label: str = '', 

207 extinf: str = '', 

208 position: int = -1, 

209 ) -> bool: 

210 """Remember one hidden song. ``True`` when it wasn't hidden yet.""" 

211 

212 key = hidden_key(name) 

213 tid = str(track_id or '').strip() 

214 ck = str(content_key or '').strip() 

215 normal = _norm_path(path) 

216 if not key or not (tid or ck or normal): 

217 return False 

218 with self._lock, self._connect() as conn: 

219 cur = conn.execute( 

220 """INSERT INTO playlist_hidden_songs 

221 (name_key, item_key, track_id, content_key, file, label, 

222 extinf, position, hidden_at) 

223 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) 

224 ON CONFLICT(name_key, item_key) DO NOTHING""", 

225 ( 

226 key, 

227 _item_key(tid, ck, normal), 

228 tid, 

229 ck, 

230 normal, 

231 str(label or ''), 

232 str(extinf or ''), 

233 int(position), 

234 _now_iso(), 

235 ), 

236 ) 

237 added = cur.rowcount > 0 

238 if added: 

239 self._changed() 

240 return added 

241 

242 def show(self, name: Any, keys: Iterable[str]) -> list[dict[str, Any]]: 

243 """Forget the hidden songs *keys* of playlist *name*; the rows 

244 that were there.""" 

245 

246 key = hidden_key(name) 

247 wanted = list(dict.fromkeys(str(k) for k in keys if str(k or ''))) 

248 if not key or not wanted: 

249 return [] 

250 removed: list[dict[str, Any]] = [] 

251 # FOR UPDATE keeps two shows of one song from both returning it. 

252 lock_sql = ' FOR UPDATE' if self.db.dialect is Dialect.POSTGRES else '' 

253 with self._lock, self._connect() as conn: 

254 for item in wanted: 

255 row = conn.execute( 

256 'SELECT * FROM playlist_hidden_songs ' 

257 'WHERE name_key = ? AND item_key = ?' + lock_sql, 

258 (key, item), 

259 ).fetchone() 

260 if row is None: 

261 continue 

262 conn.execute( 

263 'DELETE FROM playlist_hidden_songs ' 

264 'WHERE name_key = ? AND item_key = ?', 

265 (key, item), 

266 ) 

267 removed.append(_public_row(row)) 

268 if removed: 

269 self._changed() 

270 return removed 

271 

272 def items(self, name: Any) -> list[dict[str, Any]]: 

273 """Playlist *name*'s hidden songs, most recently hidden first.""" 

274 

275 order = insertion_order_col(self.db.dialect) 

276 with self._connect() as conn: 

277 rows = conn.execute( 

278 'SELECT * FROM playlist_hidden_songs WHERE name_key = ? ' 

279 f'ORDER BY hidden_at DESC, {order} DESC', 

280 (hidden_key(name),), 

281 ).fetchall() 

282 return [_public_row(row) for row in rows] 

283 

284 def forget(self, name: Any) -> int: 

285 """Drop every hidden song of a playlist that was deleted or 

286 detached from its source. How many.""" 

287 

288 with self._lock, self._connect() as conn: 

289 cur = conn.execute( 

290 'DELETE FROM playlist_hidden_songs WHERE name_key = ?', 

291 (hidden_key(name),), 

292 ) 

293 if cur.rowcount: 

294 self._changed() 

295 return cur.rowcount 

296 

297 def rekey(self, old_key: str, new_key: str, stored_path: str = '') -> int: 

298 """Follow a hidden song's file when it is rewritten (upgrade, 

299 replace) - a song's track id never changes, its file may.""" 

300 

301 old = str(old_key or '').strip() 

302 new = str(new_key or '').strip() 

303 if not old or not new or old == new: 

304 return 0 

305 normal = _norm_path(stored_path) 

306 with self._lock, self._connect() as conn: 

307 # No UNIQUE constraint other than the (name_key, item_key) key, 

308 # which this UPDATE never changes, so no row can collide. 

309 cur = conn.execute( 

310 'UPDATE playlist_hidden_songs SET content_key = ?, ' 

311 "file = COALESCE(NULLIF(?, ''), file) WHERE content_key = ?", 

312 (new, normal, old), 

313 ) 

314 if cur.rowcount: 

315 self._changed() 

316 return cur.rowcount 

317 

318 

319def _public_row(row: Any) -> dict[str, Any]: 

320 return { 

321 'key': row['item_key'], 

322 'track_id': row['track_id'], 

323 'content_key': row['content_key'], 

324 'file': row['file'], 

325 'label': row['label'], 

326 'extinf': row['extinf'], 

327 'position': int(row['position']), 

328 'hidden_at': row['hidden_at'], 

329 } 

330 

331 

332# ── Hiding and showing ────────────────────────────────────────────────── 

333 

334 

335class HiddenSongsError(ValueError): 

336 """User-facing failure (not found, not imported, nothing to hide).""" 

337 

338 def __init__(self, message: str, *, status_code: int = 400) -> None: 

339 super().__init__(message) 

340 self.status_code = status_code 

341 

342 

343def _imported_m3u(ctx: LibraryContext, name: str) -> Path: 

344 path = m3u.find_m3u_for_name(ctx.download_dir, name) 

345 if path is None: 

346 raise HiddenSongsError( 

347 f'Playlist {name!r} was not found', status_code=404 

348 ) 

349 if m3u.is_manual_m3u(path): 

350 raise HiddenSongsError( 

351 'Songs are removed from a Library playlist, not hidden', 

352 status_code=409, 

353 ) 

354 return path 

355 

356 

357def catalog_names_for( 

358 catalog: Optional[PlaylistCatalog], name: str 

359) -> list[str]: 

360 """The playlist catalog's names for playlist *name* (a watch stores 

361 the raw name, the listing the M3U stem).""" 

362 

363 if catalog is None: 

364 return [] 

365 key = hidden_key(name) 

366 return [n for n in catalog.list_playlist_names() if hidden_key(n) == key] 

367 

368 

369def source_track_ids( 

370 name: str, 

371 files: Iterable[str], 

372 *, 

373 catalog: Optional[PlaylistCatalog] = None, 

374 monitor_db: Optional[PlaylistMonitorDB] = None, 

375) -> dict[str, str]: 

376 """``{library path: source track id}`` for the *files* of playlist 

377 *name*, from the playlist catalog and its watch's history - the id a 

378 sweep or a completeness report compares.""" 

379 

380 wanted = {_norm_path(f) for f in files if _norm_path(f)} 

381 found: dict[str, str] = {} 

382 for exact in catalog_names_for(catalog, name): 

383 for row in catalog.list_tracks(exact): 

384 path = _norm_path(row.get('filename')) 

385 if path in wanted and row.get('track_spotify_id'): 

386 found.setdefault(path, str(row['track_spotify_id'])) 

387 if monitor_db is not None and len(found) < len(wanted): 

388 key = hidden_key(name) 

389 for watch in monitor_db.list_playlists(): 

390 if hidden_key(watch.name) != key: 

391 continue 

392 for tid, path in monitor_db.get_track_filenames(watch.id).items(): 

393 normal = _norm_path(path) 

394 if normal in wanted and tid: 

395 found.setdefault(normal, str(tid)) 

396 return found 

397 

398 

399def hide_playlist_songs( 

400 ctx: LibraryContext, 

401 store: PlaylistHiddenSongs, 

402 name: str, 

403 files: Iterable[str], 

404 *, 

405 track_ids: Optional[dict[str, str]] = None, 

406 catalog: Optional[PlaylistCatalog] = None, 

407) -> dict[str, Any]: 

408 """Hide *files* from imported playlist *name*: remember them, take 

409 them out of its M3U and of its catalog rows. The audio stays. 

410 ``keys`` in the result are what :func:`show_playlist_songs` takes to 

411 undo it.""" 

412 

413 path = _imported_m3u(ctx, name) 

414 download_dir, slskd_dir = ctx.download_dir, ctx.slskd_dir 

415 extra_dirs = tuple(ctx.extra_dirs or ()) 

416 entries = m3u.read_m3u_entries(path, download_dir, slskd_dir, extra_dirs) 

417 current = [stored for stored, _extinf in entries] 

418 wanted = {_norm_path(f) for f in files if _norm_path(f)} 

419 if len(wanted) > MAX_SONGS_PER_EDIT: 

420 raise HiddenSongsError( 

421 f'Hide at most {MAX_SONGS_PER_EDIT} songs at a time' 

422 ) 

423 chosen = [stored for stored in dict.fromkeys(current) if stored in wanted] 

424 if not chosen: 

425 raise HiddenSongsError('Those songs are not in this playlist') 

426 if not [stored for stored in current if stored not in wanted]: 

427 raise HiddenSongsError( 

428 'A playlist must keep at least one song - delete it instead' 

429 ) 

430 hidden, keys = _remember_hidden( 

431 ctx, store, path.stem, entries, chosen, track_ids or {} 

432 ) 

433 m3u.remove_m3u_tracks(path, chosen, download_dir, slskd_dir, extra_dirs) 

434 if catalog is not None: 

435 for exact in catalog_names_for(catalog, path.stem): 

436 for stored in chosen: 

437 catalog.remove_tracks_for_filename(stored, exact) 

438 invalidate_library_paths_cache() 

439 kept = m3u.read_m3u_tracks( 

440 path, download_dir, slskd_dir, extra_dirs, keep_missing=True 

441 ) 

442 return { 

443 'name': path.stem, 

444 'hidden': hidden, 

445 'keys': keys, 

446 'files': kept, 

447 'count': len(kept), 

448 } 

449 

450 

451def _remember_hidden( 

452 ctx: LibraryContext, 

453 store: PlaylistHiddenSongs, 

454 name: str, 

455 entries: list[tuple[str, str]], 

456 chosen: list[str], 

457 track_ids: dict[str, str], 

458) -> tuple[int, list[str]]: 

459 """Store *chosen* (of the M3U *entries*) as hidden from playlist 

460 *name*: ``(newly hidden, every chosen song's key)``.""" 

461 

462 current = [stored for stored, _extinf in entries] 

463 hidden = 0 

464 keys: list[str] = [] 

465 for stored in chosen: 

466 position = current.index(stored) 

467 extinf = entries[position][1] 

468 full = resolve_library_file(stored, ctx) 

469 content_key = file_content_key(full) if full is not None else '' 

470 track_id = track_ids.get(stored, '') 

471 keys.append(_item_key(track_id, content_key, stored)) 

472 if store.hide( 

473 name, 

474 track_id=track_id, 

475 content_key=content_key, 

476 path=stored, 

477 label=m3u.extinf_label(extinf) or Path(stored).stem, 

478 extinf=extinf, 

479 position=position, 

480 ): 

481 hidden += 1 

482 return hidden, keys 

483 

484 

485def show_playlist_songs( 

486 ctx: LibraryContext, 

487 store: PlaylistHiddenSongs, 

488 name: str, 

489 keys: Iterable[str], 

490 *, 

491 catalog: Optional[PlaylistCatalog] = None, 

492) -> dict[str, Any]: 

493 """Show hidden songs *keys* of playlist *name* again: forget them and 

494 put the ones still in the library back where they were. A song whose 

495 file is gone comes back the way any missing song does - the next 

496 watch sweep, or *Download missing*.""" 

497 

498 path = _imported_m3u(ctx, name) 

499 download_dir, slskd_dir = ctx.download_dir, ctx.slskd_dir 

500 extra_dirs = tuple(ctx.extra_dirs or ()) 

501 wanted = list(keys) 

502 if len(wanted) > MAX_SONGS_PER_EDIT: 

503 raise HiddenSongsError( 

504 f'Show at most {MAX_SONGS_PER_EDIT} songs at a time' 

505 ) 

506 rows = store.show(path.stem, wanted) 

507 current = m3u.read_m3u_tracks( 

508 path, download_dir, slskd_dir, extra_dirs, keep_missing=True 

509 ) 

510 restored = 0 

511 for row in sorted(rows, key=lambda item: item['position']): 

512 stored = row['file'] 

513 full = resolve_library_file(stored, ctx) if stored else None 

514 if full is None or stored in current: 

515 continue 

516 position = max(row['position'], 0) 

517 if not m3u.insert_m3u_track( 

518 path, 

519 stored, 

520 position, 

521 row['extinf'], 

522 download_dir, 

523 slskd_dir, 

524 extra_dirs, 

525 ): 

526 continue 

527 current.insert(min(position, len(current)), stored) 

528 restored += 1 

529 tid = row['track_id'] 

530 if catalog is not None and normalize_spotify_track_id({ 

531 'song_id': tid 

532 }): 

533 for exact in catalog_names_for(catalog, path.stem): 

534 catalog.upsert_track( 

535 exact, {'song_id': tid}, stored, full, track_order=position 

536 ) 

537 invalidate_library_paths_cache() 

538 return { 

539 'name': path.stem, 

540 'shown': len(rows), 

541 'restored': restored, 

542 'files': current, 

543 'count': len(current), 

544 }