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

1"""Playlists the user builds in the Library, stored as marked M3U files. 

2 

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

7 

8from __future__ import annotations 

9 

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 

17 

18from loguru import logger 

19 

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) 

30 

31MAX_PLAYLIST_NAME_LEN = 120 

32# Keep edits bounded, while supporting large imported playlists. 

33MAX_TRACKS_PER_EDIT = 10_000 

34 

35_P = ParamSpec('_P') 

36_R = TypeVar('_R') 

37_WRITE_LOCK = threading.RLock() 

38 

39 

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

44 

45 @functools.wraps(func) 

46 def run(*args: _P.args, **kwargs: _P.kwargs) -> _R: 

47 with _WRITE_LOCK: 

48 return func(*args, **kwargs) 

49 

50 return run 

51 

52 

53class ManualPlaylistError(ValueError): 

54 """User-facing failure (duplicate name, not manual, missing file).""" 

55 

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

57 super().__init__(message) 

58 self.status_code = status_code 

59 

60 

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

65 

66 

67def _clean_path(raw: object) -> str: 

68 return str(raw or '').strip().replace('\\', '/') 

69 

70 

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

76 

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 

89 

90 

91def _entries_for(files: list[str]) -> list[dict[str, str]]: 

92 return [{'filename': name} for name in files] 

93 

94 

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 

115 

116 

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 ) 

122 

123 

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 ) 

130 

131 

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

140 

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 

152 

153 

154@_serialized 

155def remove_manual_playlist_cover(ctx: LibraryContext, name: str) -> None: 

156 """Remove custom art and restore the manual playlist's track mosaic.""" 

157 

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

175 

176 

177def existing_playlist_names(download_dir: Path) -> set[str]: 

178 return {path.stem.casefold() for path in m3u.iter_m3u_files(download_dir)} 

179 

180 

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) 

192 

193 

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 } 

266 

267 

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) 

277 

278 

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. 

290 

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

296 

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 } 

344 

345 

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*. 

355 

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

362 

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 } 

393 

394 

395@_serialized 

396def detach_imported_playlist(ctx: LibraryContext, name: str) -> dict[str, Any]: 

397 """Turn an imported playlist into a Library one (tracks kept). 

398 

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

404 

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 } 

436 

437 

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

448 

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) 

452 

453 

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

459 

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 } 

511 

512 

513@_serialized 

514def drop_manual_playlist(ctx: LibraryContext, name: str) -> dict[str, Any]: 

515 """Remove the M3U only — audio files stay on disk.""" 

516 

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 } 

546 

547 

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

556 

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 

575 

576 

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

582 

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