Coverage for downtify/manual_playlists.py: 89%
309 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"""Playlists the user builds in the Library, stored as marked M3U files.
3Downloaded Spotify/YouTube playlists stay read-only here. These ones
4live under ``Playlists/`` with ``#EXTDOWNTIFY:manual`` so they can be
5edited, and so deleting them never removes the audio files.
6"""
8from __future__ import annotations
10import functools
11import threading
12from collections import Counter
13from collections.abc import Collection, Iterable
14from pathlib import Path
15from shutil import copyfile
16from typing import Any, Callable, Optional, ParamSpec, TypeVar
18from loguru import logger
20from . import m3u
21from .library_catalog import LibraryContext, resolve_library_file
22from .library_paths_cache import invalidate_library_paths_cache
23from .playlist_mosaic import (
24 EXPLICIT_COVER_MARKER,
25 has_explicit_cover,
26 keep_explicit_cover,
27 normalize_uploaded_cover,
28 refresh_manual_playlist_cover,
29)
31MAX_PLAYLIST_NAME_LEN = 120
32# Keep edits bounded, while supporting large imported playlists.
33MAX_TRACKS_PER_EDIT = 10_000
35_P = ParamSpec('_P')
36_R = TypeVar('_R')
37_WRITE_LOCK = threading.RLock()
40def _serialized(func: Callable[_P, _R]) -> Callable[_P, _R]:
41 """Serialize this module's M3U rewrites, including maintenance:
42 reading, changing and writing a playlist concurrently would let
43 a stale edit or cleanup overwrite another operation's changes."""
45 @functools.wraps(func)
46 def run(*args: _P.args, **kwargs: _P.kwargs) -> _R:
47 with _WRITE_LOCK:
48 return func(*args, **kwargs)
50 return run
53class ManualPlaylistError(ValueError):
54 """User-facing failure (duplicate name, not manual, missing file)."""
56 def __init__(self, message: str, *, status_code: int = 400) -> None:
57 super().__init__(message)
58 self.status_code = status_code
61def _ctx_dirs(
62 ctx: LibraryContext,
63) -> tuple[Path, Optional[Path], tuple[Path, ...]]:
64 return ctx.download_dir, ctx.slskd_dir, tuple(ctx.extra_dirs or ())
67def _clean_path(raw: object) -> str:
68 return str(raw or '').strip().replace('\\', '/')
71def _occurrence_indexes(
72 files: list[str], entries: Iterable[tuple[str, int]]
73) -> set[int]:
74 """Where in *files* each ``(file, occurrence)`` sits: the
75 *occurrence*-th copy (from 0) of a song the playlist repeats."""
77 wanted: dict[str, set[int]] = {}
78 for raw, occurrence in entries:
79 stored = _clean_path(raw)
80 if stored and occurrence >= 0:
81 wanted.setdefault(stored, set()).add(occurrence)
82 seen: Counter[str] = Counter()
83 indexes: set[int] = set()
84 for index, item in enumerate(files):
85 if seen[item] in wanted.get(item, ()):
86 indexes.add(index)
87 seen[item] += 1
88 return indexes
91def _entries_for(files: list[str]) -> list[dict[str, str]]:
92 return [{'filename': name} for name in files]
95def _write(ctx: LibraryContext, files: list[str], path: Path) -> Path:
96 explicit_cover = has_explicit_cover(path)
97 content, _kept = m3u.build_m3u_content(
98 _entries_for(files),
99 download_dir=ctx.download_dir,
100 m3u_dir=path.parent,
101 slskd_dir=ctx.slskd_dir,
102 extra_dirs=tuple(ctx.extra_dirs or ()),
103 )
104 lines = content.splitlines()
105 if lines[:1] == ['#EXTM3U'] and m3u.MANUAL_M3U_MARKER not in lines[:4]:
106 lines.insert(1, m3u.MANUAL_M3U_MARKER)
107 if explicit_cover:
108 lines.insert(2, EXPLICIT_COVER_MARKER)
109 content = '\n'.join(lines) + '\n'
110 path.parent.mkdir(parents=True, exist_ok=True)
111 path.write_text(content, encoding='utf-8', newline='\n')
112 refresh_manual_playlist_cover(ctx, path, files)
113 invalidate_library_paths_cache()
114 return path
117def _read_files(ctx: LibraryContext, path: Path) -> list[str]:
118 download_dir, slskd_dir, extra_dirs = _ctx_dirs(ctx)
119 return m3u.read_m3u_tracks(
120 path, download_dir, slskd_dir, extra_dirs, keep_missing=True
121 )
124def _require_manual(path: Path, name: str) -> None:
125 if not m3u.is_manual_m3u(path):
126 raise ManualPlaylistError(
127 f'Playlist {name!r} is imported and cannot be edited',
128 status_code=403,
129 )
132@_serialized
133def save_manual_playlist_cover(
134 ctx: LibraryContext,
135 name: str,
136 data: bytes,
137 content_type: str,
138) -> Path:
139 """Replace a manual playlist's generated cover with uploaded art."""
141 path = m3u.find_m3u_for_name(ctx.download_dir, name)
142 if path is None:
143 raise ManualPlaylistError(
144 f'Playlist {name!r} was not found', status_code=404
145 )
146 _require_manual(path, path.stem)
147 cover = path.with_suffix('.jpg')
148 cover.write_bytes(normalize_uploaded_cover(data, content_type))
149 keep_explicit_cover(path)
150 invalidate_library_paths_cache()
151 return cover
154@_serialized
155def remove_manual_playlist_cover(ctx: LibraryContext, name: str) -> None:
156 """Remove custom art and restore the manual playlist's track mosaic."""
158 path = m3u.find_m3u_for_name(ctx.download_dir, name)
159 if path is None:
160 raise ManualPlaylistError(
161 f'Playlist {name!r} was not found', status_code=404
162 )
163 _require_manual(path, path.stem)
164 path.with_suffix('.jpg').unlink(missing_ok=True)
165 text = m3u.read_m3u_text(path)
166 if text is not None:
167 lines = [
168 line
169 for line in text.splitlines()
170 if line.strip() != EXPLICIT_COVER_MARKER
171 ]
172 path.write_text('\n'.join(lines) + '\n', encoding='utf-8')
173 refresh_manual_playlist_cover(ctx, path, _read_files(ctx, path))
174 invalidate_library_paths_cache()
177def existing_playlist_names(download_dir: Path) -> set[str]:
178 return {path.stem.casefold() for path in m3u.iter_m3u_files(download_dir)}
181def _validated_name(raw: str) -> str:
182 text = str(raw or '').strip()
183 if not text or len(text) > MAX_PLAYLIST_NAME_LEN:
184 raise ManualPlaylistError('Enter a playlist name')
185 # Same rule as likes.is_liked_playlist, inlined to avoid
186 # manual_playlists → likes → library_reconcile → library_delete.
187 if text.casefold() == 'downtify liked songs':
188 raise ManualPlaylistError(
189 'That name is reserved for liked songs', status_code=409
190 )
191 return m3u.sanitize_playlist_name(text)
194def _create_playlist(
195 ctx: LibraryContext,
196 name: str,
197 files: list[str],
198 owners: Any = None,
199 user_id: int = 0,
200 shares: Any = None,
201) -> dict[str, Any]:
202 if user_id and (owners is None or shares is None):
203 raise ManualPlaylistError(
204 'Playlist ownership is temporarily unavailable', status_code=503
205 )
206 safe = _validated_name(name)
207 if safe.casefold() in existing_playlist_names(ctx.download_dir):
208 raise ManualPlaylistError(
209 f'A playlist named {safe!r} already exists', status_code=409
210 )
211 path = m3u.m3u_path_for(ctx.download_dir, safe)
212 cover_path = path.with_suffix('.jpg')
213 original_cover = cover_path.read_bytes() if cover_path.is_file() else None
214 # Reserve the exact path exclusively. A failed write/claim can then
215 # remove only the file this invocation created, never a preexisting one.
216 path.parent.mkdir(parents=True, exist_ok=True)
217 try:
218 with path.open('x', encoding='utf-8'):
219 pass
220 except FileExistsError as exc:
221 raise ManualPlaylistError(
222 f'A playlist named {safe!r} already exists', status_code=409
223 ) from exc
224 identity = path.stat()
225 share_snapshot = None
226 try:
227 written = _write(ctx, files, path)
228 kept = _read_files(ctx, written)
229 if owners is not None and user_id:
230 if shares is not None:
231 share_snapshot = shares.snapshot(written.stem)
232 shares.forget(written.stem)
233 if not owners.claim_owner(written.stem, user_id):
234 raise RuntimeError('Playlist ownership claim was not accepted')
235 except BaseException:
236 if share_snapshot is not None:
237 try:
238 shares.restore(safe, share_snapshot)
239 except Exception:
240 logger.opt(exception=True).error(
241 'Could not restore playlist sharing for {}', safe
242 )
243 try:
244 current = path.stat()
245 if (current.st_dev, current.st_ino) == (
246 identity.st_dev,
247 identity.st_ino,
248 ):
249 path.unlink()
250 if original_cover is None:
251 cover_path.unlink(missing_ok=True)
252 else:
253 cover_path.write_bytes(original_cover)
254 except OSError:
255 logger.opt(exception=True).warning(
256 'Could not roll back newly created playlist {}', path
257 )
258 raise
259 logger.info('Created manual playlist {!r} at {}', safe, written)
260 return {
261 'name': written.stem,
262 'manual': True,
263 'files': kept,
264 'count': len(kept),
265 }
268@_serialized
269def create_manual_playlist(
270 ctx: LibraryContext,
271 name: str,
272 owners: Any = None,
273 user_id: int = 0,
274 shares: Any = None,
275) -> dict[str, Any]:
276 return _create_playlist(ctx, name, [], owners, user_id, shares)
279@_serialized
280def edit_manual_playlist(
281 ctx: LibraryContext,
282 name: str,
283 *,
284 add: Optional[list[str]] = None,
285 remove: Optional[list[str]] = None,
286 remove_entries: Optional[list[tuple[str, int]]] = None,
287 allow_duplicates: bool = False,
288) -> dict[str, Any]:
289 """Add songs at the end and take songs out.
291 *remove* takes every copy of a song; *remove_entries* one copy each,
292 as ``(file, occurrence)``. A song the playlist already has is only
293 added again with *allow_duplicates*: otherwise it is listed in
294 ``already`` so the caller can ask.
295 """
297 path = m3u.find_m3u_for_name(ctx.download_dir, name)
298 if path is None:
299 raise ManualPlaylistError(
300 f'Playlist {name!r} was not found', status_code=404
301 )
302 _require_manual(path, path.stem)
303 current = _read_files(ctx, path)
304 present = set(current)
305 drop = {_clean_path(item) for item in (remove or []) if _clean_path(item)}
306 dropped_at = _occurrence_indexes(current, remove_entries or [])
307 files = [
308 item
309 for index, item in enumerate(current)
310 if item not in drop and index not in dropped_at
311 ]
312 removed = len(current) - len(files)
313 seen = set(files)
314 added = 0
315 already: list[str] = []
316 for raw in add or []:
317 stored = _clean_path(raw)
318 if not stored or stored in drop:
319 continue
320 if stored in seen and not allow_duplicates:
321 if stored in present and stored not in already:
322 already.append(stored)
323 continue
324 if len(files) >= MAX_TRACKS_PER_EDIT:
325 raise ManualPlaylistError(
326 f'Playlists can hold at most {MAX_TRACKS_PER_EDIT} tracks'
327 )
328 if resolve_library_file(stored, ctx) is None:
329 raise ManualPlaylistError(f'Track not in the library: {stored}')
330 files.append(stored)
331 seen.add(stored)
332 added += 1
333 written = _write(ctx, files, path)
334 kept = _read_files(ctx, written)
335 return {
336 'name': written.stem,
337 'manual': True,
338 'files': kept,
339 'count': len(kept),
340 'added': added,
341 'removed': removed,
342 'already': already,
343 }
346@_serialized
347def reorder_manual_playlist(
348 ctx: LibraryContext,
349 name: str,
350 order: list[str],
351 *,
352 visible: Optional[Collection[str]] = None,
353) -> dict[str, Any]:
354 """Put the playlist's songs in *order*.
356 *order* is every song the caller sees, repeats included, in its new
357 place. Anything else means the playlist changed since they loaded it
358 (another editor added or removed a song): ``409``, so nobody's edit
359 is lost. Songs outside *visible* - hidden from the caller - keep the
360 places they had.
361 """
363 path = m3u.find_m3u_for_name(ctx.download_dir, name)
364 if path is None:
365 raise ManualPlaylistError(
366 f'Playlist {name!r} was not found', status_code=404
367 )
368 _require_manual(path, path.stem)
369 current = _read_files(ctx, path)
370 wanted = [_clean_path(item) for item in order if _clean_path(item)]
371 slots = [
372 index
373 for index, item in enumerate(current)
374 if visible is None or item in visible
375 ]
376 if Counter(current[index] for index in slots) != Counter(wanted):
377 raise ManualPlaylistError(
378 'The playlist changed meanwhile: reload it and try again',
379 status_code=409,
380 )
381 files = list(current)
382 for index, item in zip(slots, wanted, strict=True):
383 files[index] = item
384 written = _write(ctx, files, path)
385 kept = _read_files(ctx, written)
386 logger.info('Reordered manual playlist {!r}', written.stem)
387 return {
388 'name': written.stem,
389 'manual': True,
390 'files': kept,
391 'count': len(kept),
392 }
395@_serialized
396def detach_imported_playlist(ctx: LibraryContext, name: str) -> dict[str, Any]:
397 """Turn an imported playlist into a Library one (tracks kept).
399 Only the M3U changes: it gets the manual marker, so it can be edited
400 and no longer counts as downloaded from a link. Its artwork stays
401 until the first edit. Unlinking it from its source (catalog row,
402 watch) is the caller's job.
403 """
405 path = m3u.find_m3u_for_name(ctx.download_dir, name)
406 if path is None:
407 raise ManualPlaylistError(
408 f'Playlist {name!r} was not found', status_code=404
409 )
410 if m3u.is_manual_m3u(path):
411 raise ManualPlaylistError(
412 f'Playlist {path.stem!r} can already be edited', status_code=409
413 )
414 text = m3u.read_m3u_text(path)
415 if text is None:
416 raise ManualPlaylistError(f'Could not read {path.name}')
417 lines = text.splitlines()
418 if lines[:1] != ['#EXTM3U']:
419 lines.insert(0, '#EXTM3U')
420 lines.insert(1, m3u.MANUAL_M3U_MARKER)
421 try:
422 path.write_text(
423 '\n'.join(lines) + '\n', encoding='utf-8', newline='\n'
424 )
425 except OSError as exc:
426 raise ManualPlaylistError(f'Could not write {path.name}') from exc
427 invalidate_library_paths_cache()
428 kept = _read_files(ctx, path)
429 logger.info('Detached playlist {!r} from its source', path.stem)
430 return {
431 'name': path.stem,
432 'manual': True,
433 'files': kept,
434 'count': len(kept),
435 }
438@_serialized
439def copy_playlist(
440 ctx: LibraryContext,
441 files: list[str],
442 new_name: str,
443 owners: Any = None,
444 user_id: int = 0,
445 shares: Any = None,
446) -> dict[str, Any]:
447 """Save *files* as a new Library playlist called *new_name*."""
449 # In order, a song the original repeats included.
450 cleaned = [_clean_path(item) for item in files if _clean_path(item)]
451 return _create_playlist(ctx, new_name, cleaned, owners, user_id, shares)
454@_serialized
455def rename_manual_playlist(
456 ctx: LibraryContext, name: str, new_name: str
457) -> dict[str, Any]:
458 """Rename a Library-created playlist. Audio files stay where they are."""
460 path = m3u.find_m3u_for_name(ctx.download_dir, name)
461 if path is None:
462 raise ManualPlaylistError(
463 f'Playlist {name!r} was not found', status_code=404
464 )
465 _require_manual(path, path.stem)
466 safe = _validated_name(new_name)
467 dest = path.with_name(f'{safe}.m3u')
468 if dest.resolve() != path.resolve():
469 taken = existing_playlist_names(ctx.download_dir)
470 if (
471 safe.casefold() in taken
472 and path.stem.casefold() != safe.casefold()
473 ):
474 raise ManualPlaylistError(
475 f'A playlist named {safe!r} already exists', status_code=409
476 )
477 if dest.exists() and dest.resolve() != path.resolve():
478 raise ManualPlaylistError(
479 f'A playlist named {safe!r} already exists', status_code=409
480 )
481 files = _read_files(ctx, path)
482 explicit_cover = has_explicit_cover(path)
483 written = _write(ctx, files, dest)
484 if written.resolve() != path.resolve():
485 old_cover = path.with_suffix('.jpg')
486 if explicit_cover:
487 copyfile(old_cover, written.with_suffix('.jpg'))
488 keep_explicit_cover(written)
489 try:
490 path.unlink(missing_ok=True)
491 except OSError as exc:
492 raise ManualPlaylistError(f'Could not remove {path.name}') from exc
493 if old_cover.resolve() != written.with_suffix('.jpg').resolve():
494 try:
495 old_cover.unlink(missing_ok=True)
496 except OSError:
497 logger.opt(exception=True).warning(
498 'Could not remove playlist cover {}', old_cover
499 )
500 logger.info(
501 'Renamed manual playlist {!r} to {!r}', path.stem, written.stem
502 )
503 kept = _read_files(ctx, written)
504 return {
505 'name': written.stem,
506 'previous': path.stem,
507 'manual': True,
508 'files': kept,
509 'count': len(kept),
510 }
513@_serialized
514def drop_manual_playlist(ctx: LibraryContext, name: str) -> dict[str, Any]:
515 """Remove the M3U only — audio files stay on disk."""
517 path = m3u.find_m3u_for_name(ctx.download_dir, name)
518 if path is None:
519 raise ManualPlaylistError(
520 f'Playlist {name!r} was not found', status_code=404
521 )
522 _require_manual(path, path.stem)
523 cover = path.with_suffix('.jpg')
524 try:
525 path.unlink(missing_ok=True)
526 except OSError as exc:
527 raise ManualPlaylistError(f'Could not remove {path.name}') from exc
528 try:
529 cover.unlink(missing_ok=True)
530 except OSError:
531 logger.opt(exception=True).warning(
532 'Could not remove playlist cover {}', cover
533 )
534 logger.info('Removed manual playlist {!r} (audio kept)', path.stem)
535 invalidate_library_paths_cache()
536 return {
537 'ok': True,
538 'playlist': path.stem,
539 'files': [],
540 'deleted_count': 0,
541 'failed_count': 0,
542 'failed': [],
543 'playlists_affected': [],
544 'manual': True,
545 }
548@_serialized
549@_serialized
550def drop_copies_of(
551 ctx: LibraryContext, keep: str, extras: list[str]
552) -> list[str]:
553 """Drop *extras* from every manual M3U that already lists *keep* -
554 two copies of one song being merged into *keep*, where the playlist
555 would otherwise list it twice. Returns the playlists changed."""
557 keep = str(keep or '').strip().replace('\\', '/')
558 gone = {
559 str(item or '').strip().replace('\\', '/')
560 for item in extras
561 if str(item or '').strip()
562 }
563 if not keep or not gone:
564 return []
565 affected: list[str] = []
566 for path in m3u.iter_m3u_files(ctx.download_dir):
567 if not m3u.is_manual_m3u(path):
568 continue
569 files = _read_files(ctx, path)
570 if keep not in files or not gone.intersection(files):
571 continue
572 _write(ctx, [item for item in files if item not in gone], path)
573 affected.append(path.stem)
574 return affected
577@_serialized
578def prune_files_from_manual_playlists(
579 ctx: LibraryContext, filenames: list[str]
580) -> list[str]:
581 """Drop *filenames* from every manual M3U. Returns playlist names."""
583 gone = {
584 str(item or '').strip().replace('\\', '/')
585 for item in filenames
586 if str(item or '').strip()
587 }
588 if not gone:
589 return []
590 affected: list[str] = []
591 for path in m3u.iter_m3u_files(ctx.download_dir):
592 if not m3u.is_manual_m3u(path):
593 continue
594 files = _read_files(ctx, path)
595 kept = [item for item in files if item not in gone]
596 if len(kept) == len(files):
597 continue
598 _write(ctx, kept, path)
599 affected.append(path.stem)
600 return affected