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
« 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.
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:
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.
17The source playlist itself is never changed: Downtify reads Spotify and
18YouTube Music anonymously and can't edit them.
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"""
30from __future__ import annotations
32import threading
33from dataclasses import dataclass
34from datetime import datetime, timezone
35from pathlib import Path
36from typing import TYPE_CHECKING, Any, Iterable, Optional
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
47if TYPE_CHECKING:
48 from .monitor import PlaylistMonitorDB
49 from .playlist_catalog import PlaylistCatalog
51#: Most songs one request may hide or show again.
52MAX_SONGS_PER_EDIT = 500
55def _now_iso() -> str:
56 return datetime.now(timezone.utc).isoformat()
59def _norm_path(path: Any) -> str:
60 return str(path or '').strip().replace('\\', '/')
63def hidden_key(name: Any) -> str:
64 """The stored key of a playlist: its M3U stem, case-insensitively."""
66 text = str(name or '').strip()
67 return m3u.sanitize_playlist_name(text).casefold() if text else ''
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}'
78@dataclass(frozen=True)
79class HiddenSongs:
80 """One playlist's hidden songs, ready to test source rows and library
81 files against."""
83 track_ids: frozenset[str] = frozenset()
84 files: frozenset[str] = frozenset()
85 content_keys: frozenset[str] = frozenset()
87 def __bool__(self) -> bool:
88 return bool(self.track_ids or self.files or self.content_keys)
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."""
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
102 def hides_file(self, path: Any, content_key: str = '') -> bool:
103 """Whether a library file is hidden, by path or content key."""
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
111class PlaylistHiddenSongs:
112 """The hidden songs of every playlist, in ``downtify_library.db``."""
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()
124 def _connect(self) -> Connection:
125 return self.db.connect()
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 """)
151 def _changed(self) -> None:
152 self._loaded = None
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
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 }
184 def songs(self, name: Any) -> HiddenSongs:
185 """What playlist *name* hides (empty when nothing)."""
187 return self._all().get(hidden_key(name), HiddenSongs())
189 def counts(self) -> dict[str, int]:
190 """``{playlist key: number of hidden songs}``, for the listing."""
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}
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."""
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
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."""
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
272 def items(self, name: Any) -> list[dict[str, Any]]:
273 """Playlist *name*'s hidden songs, most recently hidden first."""
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]
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."""
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
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."""
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
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 }
332# ── Hiding and showing ──────────────────────────────────────────────────
335class HiddenSongsError(ValueError):
336 """User-facing failure (not found, not imported, nothing to hide)."""
338 def __init__(self, message: str, *, status_code: int = 400) -> None:
339 super().__init__(message)
340 self.status_code = status_code
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
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)."""
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]
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."""
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
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."""
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 }
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)``."""
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
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*."""
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 }