Coverage for downtify/artist_profile.py: 97%

544 statements  

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

1"""Store and serve an artist's public profile: photo, banner, bio, social 

2links, related artists and platform ids. 

3 

4Photo/banner are saved as flat sidecar files under the download 

5directory's ``.metadata`` folder (``ArtistImage`` / ``ArtistBannerImage``), 

6named after the artist - the same idea as 

7:func:`downtify.downloader.save_playlist_cover` saving a playlist's cover 

8next to its M3U. There is no database row: whether the file exists on 

9disk is the source of truth. The download directory is already served at 

10``/downloads`` (see ``main.py``), so no dedicated read endpoint is needed 

11- only a small existence check and the write paths below. 

12 

13The rest of the profile (bio, origin, formation year, social links, 

14related artists, platform ids, and which source each saved photo/banner 

15came from) lives in one JSON sidecar per artist, 

16``.metadata/ArtistData/<name>.json`` - see :func:`load_profile`/ 

17:func:`fetch_bio`. Apple Music (:mod:`downtify.apple_music`) is the 

18primary bio source - it also brings origin/formation year/genre/group flag/ 

19hero colour, nothing else supplies those; Deezer (:mod:`downtify.deezer`) 

20is the secondary bio source (used only when Apple's bio is empty for 

21that artist/language) and the only source for social links and related 

22artists. Always fetched on demand (a button on the artist page) - except 

23for a brand-new artist's very first profile, seeded automatically by 

24:func:`ensure_profile` (photo/banner from Spotify/YouTube Music - only 

25the ones the user's settings allow - and bio/social/platform ids the same 

26way the button would). 

27 

28The artist's Spotify top songs are kept here too, as a cache next to the 

29profile (``.metadata/ArtistTopSongs/<name>.topsongs.json``, see the last 

30section): 

31not part of the profile itself, so it has a file of its own. 

32 

33Function names are prefixed ``image_``/``_image`` for the photo/banner 

34half and ``profile_top_songs_`` for the top-songs cache on purpose, to keep 

35them visually distinct from the profile-data half added later - and from 

36:func:`downtify.spotify.artist_top_songs_from_id`, which only fetches. 

37""" 

38 

39from __future__ import annotations 

40 

41import contextlib 

42import json 

43import os 

44import queue 

45import re 

46import tempfile 

47import threading 

48from datetime import datetime, timedelta, timezone 

49from pathlib import Path 

50from typing import Any, Optional 

51from urllib.parse import urlsplit 

52 

53import httpx 

54from loguru import logger 

55 

56from . import apple_music, deezer, providers, spotify 

57from .album_artist import filing_artist 

58from .downloader import _sanitize 

59from .file_naming import file_name_key 

60from .image_size import image_dimensions 

61from .podcasts import strip_html 

62 

63KIND_PHOTO = 'photo' 

64KIND_BANNER = 'banner' 

65 

66_DIRNAMES = { 

67 KIND_PHOTO: '.metadata/ArtistImage', 

68 KIND_BANNER: '.metadata/ArtistBannerImage', 

69} 

70_SUFFIXES = { 

71 KIND_PHOTO: '.jpg', 

72 KIND_BANNER: '.banner.jpg', 

73} 

74_PROFILE_DIRNAME = '.metadata/ArtistData' 

75_TOP_SONGS_DIRNAME = '.metadata/ArtistTopSongs' 

76# ``<name>.topsongs.json``: the artist's profile is ``<name>.json`` in its own 

77# folder, and one JSON per artist in both is easy to mix up. 

78_TOP_SONGS_SUFFIX = '.topsongs.json' 

79 

80#: How many of the artist's top songs are kept. 

81TOP_SONGS_LIMIT = 5 

82#: How long a saved top-songs file is trusted before it is fetched again. 

83TOP_SONGS_TTL = timedelta(days=7) 

84#: The top-songs file layout. A file of an older layout counts as stale, so 

85#: a new field (2: each song's ``preview_url``) shows up on the next visit 

86#: instead of when the week is out. 

87TOP_SONGS_SCHEMA = 2 

88 

89#: Refuse anything implausibly large for a profile photo or banner. 

90MAX_IMAGE_BYTES = 15 * 1024 * 1024 

91 

92_IMAGE_FETCH_TIMEOUT = 20 

93 

94 

95def image_path_for(download_dir: Path, name: str, kind: str) -> Path: 

96 """Sidecar file for *name*'s photo/banner, whether or not it exists.""" 

97 

98 return ( 

99 Path(download_dir) 

100 / _DIRNAMES[kind] 

101 / f'{_sanitize(name)}{_SUFFIXES[kind]}' 

102 ) 

103 

104 

105def image_url_for(download_dir: Path, name: str, kind: str) -> Optional[str]: 

106 """The ``/downloads/...`` URL for *name*'s photo/banner, or ``None``.""" 

107 

108 path = image_path_for(download_dir, name, kind) 

109 if not path.is_file(): 

110 return None 

111 rel = path.relative_to(Path(download_dir)).as_posix() 

112 return f'/downloads/{rel}' 

113 

114 

115def image_version_for( 

116 download_dir: Path, name: str, kind: str 

117) -> Optional[int]: 

118 """When *name*'s photo/banner file last changed (milliseconds since 

119 the epoch), or ``None`` if there is none. 

120 

121 A saved image keeps the same ``/downloads/...`` URL however often it 

122 is replaced, so a browser holding the old one has no reason to ask 

123 again. Callers put this in the URL (``?v=<version>``): it changes 

124 exactly when the file does, so a replaced photo shows up at once and 

125 an untouched one stays cached. 

126 """ 

127 

128 try: 

129 return int( 

130 image_path_for(download_dir, name, kind).stat().st_mtime * 1000 

131 ) 

132 except OSError: 

133 return None 

134 

135 

136def _write_image(download_dir: Path, name: str, kind: str, data: bytes) -> str: 

137 path = image_path_for(download_dir, name, kind) 

138 path.parent.mkdir(parents=True, exist_ok=True) 

139 path.write_bytes(data) 

140 rel = path.relative_to(Path(download_dir)).as_posix() 

141 return f'/downloads/{rel}' 

142 

143 

144def _origin_path(url: str) -> str: 

145 """The part of an image URL that names the image rather than the CDN 

146 serving it: the path, without host, query or fragment 

147 (``https://image-cdn-ak.spotifycdn.com/image/ab67…?x=1`` -> 

148 ``/image/ab67…``). ``''`` when there is none.""" 

149 

150 path = urlsplit((url or '').strip()).path 

151 return path if path.strip('/') else '' 

152 

153 

154def save_image( 

155 download_dir: Path, 

156 name: str, 

157 kind: str, 

158 data: bytes, 

159 source: str = '', 

160 origin: str = '', 

161) -> str: 

162 """Validate *data* is a real image and save it; returns its public URL. 

163 

164 What the image was made from is recorded as ``current_cover`` (photo) / 

165 ``current_cover_banner`` (banner) in the artist's profile JSON (see 

166 :func:`load_profile`), so the picker can highlight the candidate in 

167 use: *origin*, the path of the URL it was downloaded from (see 

168 :func:`_origin_path`), or - with none, an upload - *source* 

169 (``upload``). Saving with neither clears a value already there, since 

170 it described the previous image, not this one. 

171 """ 

172 

173 if ( 

174 not data 

175 or len(data) > MAX_IMAGE_BYTES 

176 or image_dimensions(data) is None 

177 ): 

178 raise ValueError('Not a valid image') 

179 url = _write_image(download_dir, name, kind, data) 

180 recorded = origin or source 

181 # Nothing to record and no profile yet: don't create one just for this. 

182 if recorded or _profile_path_for(download_dir, name).is_file(): 

183 _set_current_cover(download_dir, name, kind, recorded) 

184 return url 

185 

186 

187def fetch_and_save_image( 

188 download_dir: Path, 

189 name: str, 

190 kind: str, 

191 image_url: str, 

192 source: str = '', 

193) -> str: 

194 """Download *image_url* and save it as *name*'s photo/banner.""" 

195 

196 url = (image_url or '').strip() 

197 if not url: 

198 raise ValueError('No image URL given') 

199 try: 

200 resp = httpx.get( 

201 url, timeout=_IMAGE_FETCH_TIMEOUT, follow_redirects=True 

202 ) 

203 resp.raise_for_status() 

204 except Exception as exc: 

205 logger.opt(exception=True).debug( 

206 'Artist art fetch failed for {}', url[:200] 

207 ) 

208 raise ValueError('Could not fetch that image') from exc 

209 return save_image( 

210 download_dir, 

211 name, 

212 kind, 

213 resp.content, 

214 source=source, 

215 origin=_origin_path(url), 

216 ) 

217 

218 

219def delete_image(download_dir: Path, name: str, kind: str) -> bool: 

220 """Remove *name*'s saved photo/banner. Returns whether a file was removed.""" 

221 

222 path = image_path_for(download_dir, name, kind) 

223 try: 

224 path.unlink() 

225 except FileNotFoundError: 

226 return False 

227 _set_current_cover(download_dir, name, kind, '') 

228 return True 

229 

230 

231# ── Profile data: bio, social links, related artists, platform ids ── 

232 

233 

234def _profile_path_for(download_dir: Path, name: str) -> Path: 

235 return Path(download_dir) / _PROFILE_DIRNAME / f'{_sanitize(name)}.json' 

236 

237 

238def _default_profile(name: str) -> dict[str, Any]: 

239 return { 

240 'name': name, 

241 'bio': '', 

242 # Apple Music only - not translated per-language, so these don't 

243 # change when the bio is re-fetched in a different language. 

244 'origin': '', 

245 'born_or_formed': '', 

246 'genre': '', 

247 'is_group': None, 

248 'banner_bg_color': '', 

249 # Resolved automatically by ensure_profile/fetch_bio (Spotify: from 

250 # one of the artist's own tracks, else an exact-name search); a 

251 # manually edited profile JSON renders its platform icons too. 

252 'platforms_id': { 

253 'spotify': '', 

254 'youtubemusic': '', 

255 'deezer': '', 

256 'applemusic': '', 

257 }, 

258 'social': { 

259 'twitter': '', 

260 'facebook': '', 

261 'website': '', 

262 'instagram': '', 

263 'youtube': '', 

264 }, 

265 'related_artists': [], 

266 # Which image the saved photo/banner is: the path of the URL it was 

267 # downloaded from, or 'upload' (see save_image). The picker marks the 

268 # candidate with the same image as the one in use. 

269 'current_cover': '', 

270 'current_cover_banner': '', 

271 } 

272 

273 

274def load_profile(download_dir: Path, name: str) -> dict[str, Any]: 

275 """*name*'s profile JSON, or a blank skeleton if none was saved yet.""" 

276 

277 default = _default_profile(name) 

278 path = _profile_path_for(download_dir, name) 

279 try: 

280 data = json.loads(path.read_text(encoding='utf-8')) 

281 except (OSError, ValueError): 

282 return default 

283 if not isinstance(data, dict): 

284 return default 

285 merged = {**default, **data} 

286 platforms = dict(data.get('platforms_id') or {}) 

287 # Files saved before the key was renamed call Apple Music's id 

288 # 'itunes' - same id, same 'slug/numeric-id' shape. Read it under the 

289 # new name; the file itself is rewritten on its next save. 

290 legacy_apple_id = platforms.pop('itunes', '') 

291 if legacy_apple_id and not platforms.get('applemusic'): 

292 platforms['applemusic'] = legacy_apple_id 

293 merged['platforms_id'] = {**default['platforms_id'], **platforms} 

294 merged['social'] = {**default['social'], **(data.get('social') or {})} 

295 merged['bio'] = _normalize_stored_bio(str(merged.get('bio') or '')) 

296 return merged 

297 

298 

299def _atomic_write_json(path: Path, data: dict[str, Any]) -> None: 

300 """Write *data* to *path* atomically (a temp file in the same folder, 

301 then a rename): a reader never sees a half-written file, even with a 

302 request racing a background write of the same artist.""" 

303 

304 path.parent.mkdir(parents=True, exist_ok=True) 

305 fd, tmp = tempfile.mkstemp(dir=path.parent, suffix='.tmp') 

306 try: 

307 with os.fdopen(fd, 'w', encoding='utf-8') as handle: 

308 json.dump(data, handle, ensure_ascii=False, indent=2) 

309 os.replace(tmp, path) 

310 except BaseException: 

311 with contextlib.suppress(OSError): 

312 Path(tmp).unlink() 

313 raise 

314 

315 

316def _save_profile( 

317 download_dir: Path, name: str, profile: dict[str, Any] 

318) -> None: 

319 _atomic_write_json(_profile_path_for(download_dir, name), profile) 

320 

321 

322def _set_current_cover( 

323 download_dir: Path, name: str, kind: str, value: str 

324) -> None: 

325 profile = load_profile(download_dir, name) 

326 field = 'current_cover' if kind == KIND_PHOTO else 'current_cover_banner' 

327 profile[field] = value 

328 _save_profile(download_dir, name, profile) 

329 

330 

331def _cached_apple_music_id(profile: dict[str, Any]) -> str: 

332 # platforms_id['applemusic'] stores 'slug/numeric-id' (see fetch_artist_full 

333 # below), but the catalog API only takes the numeric id - pull it back 

334 # out of a cached value instead of re-searching by name every time. 

335 cached = profile['platforms_id'].get('applemusic') or '' 

336 match = re.search(r'(\d+)$', cached) 

337 return match.group(1) if match else '' 

338 

339 

340def _cached_or_resolved_apple_music_id( 

341 profile: dict[str, Any], name: str 

342) -> str: 

343 return _cached_apple_music_id(profile) or ( 

344 apple_music.resolve_artist_id(name) or '' 

345 ) 

346 

347 

348class ProfileUnavailable(Exception): 

349 """A service that had to answer (Apple Music, Deezer) failed - an error, 

350 not "this artist isn't there". Seeding a profile raises it *before* 

351 writing anything, so no half-made profile stands in for the real one: the 

352 artist is seeded the next time they are needed.""" 

353 

354 

355_BULLET_RE = re.compile(r'^•\s*') 

356 

357 

358def _format_bio_text(raw: str) -> str: 

359 """*raw* (Deezer's own ``<p>`` HTML, Apple Music's text with a ``•`` 

360 list, or a user's manually typed text) turned into plain text: 

361 paragraphs separated by one blank line, and no HTML left at all. 

362 

363 Every ``•`` bullet is dropped and starts a paragraph of its own - 

364 Apple separates its bullets with a single line break, so without this 

365 they'd render as one long paragraph. A single line break anywhere 

366 else is kept as it is. 

367 

368 Starts from :func:`downtify.podcasts.strip_html`, which already turns 

369 block tags (``<p>``, ``<br>``, ``<li>`` ...) into line breaks and 

370 drops every other tag, so Deezer's HTML comes out as paragraphs 

371 separated by blank lines. Idempotent - running its own output through 

372 again changes nothing. 

373 """ 

374 

375 text = strip_html(raw) 

376 if not text: 

377 return '' 

378 paragraphs: list[list[str]] = [] 

379 for block in re.split(r'\n\s*\n', text): 

380 current: list[str] = [] 

381 for raw_line in block.split('\n'): 

382 line = raw_line.strip() 

383 if not line: 

384 continue 

385 if _BULLET_RE.match(line): 

386 if current: 

387 paragraphs.append(current) 

388 current = [] 

389 line = _BULLET_RE.sub('', line) 

390 if line: 

391 current.append(line) 

392 if current: 

393 paragraphs.append(current) 

394 return '\n\n'.join('\n'.join(lines) for lines in paragraphs) 

395 

396 

397def _normalize_stored_bio(bio: str) -> str: 

398 """A bio saved by an earlier version (HTML, maybe with a ``<ul>`` 

399 list, or plain text still carrying ``•`` bullets) brought up to 

400 today's plain-text shape on read - a no-op for one already in it. 

401 Nothing is rewritten on disk until the next save. 

402 """ 

403 

404 if not bio or not ('<' in bio or '•' in bio): 

405 return bio 

406 # A list item is a bullet like any other: it ends up a paragraph. 

407 bio = re.sub(r'<li[^>]*>', '\n• ', bio).replace('</li>', '\n') 

408 return _format_bio_text(bio) 

409 

410 

411def _merge_names(existing: list[str], new: list[str]) -> list[str]: 

412 """*existing* followed by whichever of *new* isn't already present, 

413 case-insensitively - combines two platforms' related-artist name 

414 lists without duplicating an artist both happen to agree on. 

415 """ 

416 

417 seen = {n.strip().lower() for n in existing if n} 

418 merged = list(existing) 

419 for name in new: 

420 key = name.strip().lower() 

421 if key and key not in seen: 

422 seen.add(key) 

423 merged.append(name) 

424 return merged 

425 

426 

427#: Which service's biography :func:`fetch_bio` should use. 

428BIO_SOURCE_AUTO = 'auto' 

429BIO_SOURCE_APPLE_MUSIC = 'applemusic' 

430BIO_SOURCE_DEEZER = 'deezer' 

431_BIO_SOURCES = (BIO_SOURCE_AUTO, BIO_SOURCE_APPLE_MUSIC, BIO_SOURCE_DEEZER) 

432 

433 

434def _fill_empty_social( 

435 current: dict[str, str], fetched: dict[str, str] 

436) -> dict[str, str]: 

437 """*current* with each of its empty links filled from *fetched*. 

438 

439 Deezer sends an empty string for every network it doesn't know, so a 

440 plain ``{**current, **fetched}`` would blank a link the user typed 

441 in to complete what Deezer lacks - and a link that is already there, 

442 typed or fetched earlier, is never replaced either: there's no way to 

443 tell a hand-corrected one from a fetched one, and losing someone's 

444 edit is worse than keeping a stale link (they can clear the field). 

445 """ 

446 

447 merged = dict(current) 

448 for key, url in fetched.items(): 

449 if url and not str(merged.get(key) or '').strip(): 

450 merged[key] = url 

451 return merged 

452 

453 

454def fetch_bio( 

455 download_dir: Path, 

456 name: str, 

457 lang: str, 

458 source: str = BIO_SOURCE_AUTO, 

459) -> dict[str, Any]: 

460 """Fetch and save *name*'s bio and related profile data. 

461 

462 Apple Music is the primary bio source, and the only one for origin/ 

463 formation year/genre/group flag/banner colour - its artist id is resolved 

464 once and cached (see :func:`downtify.apple_music.resolve_artist_id`). 

465 Deezer is the secondary bio source - only used to fill the bio in 

466 when Apple's own is empty for that artist/language (see 

467 :func:`downtify.apple_music.fetch_artist_full`'s docstring: Apple's 

468 editorial bios aren't written for every artist in every language) - 

469 and a source for social links and related-artist names, which it 

470 contributes regardless of whether Apple already supplied a bio. 

471 Spotify also contributes related-artist names, merged in alongside 

472 Deezer's (see :func:`_merge_names`), using the cached 

473 ``platforms_id.spotify`` - or, when there is none yet, an exact-name 

474 search (:func:`_spotify_id_from_name`), cached the same way. An id 

475 already there - e.g. resolved from one of the artist's own Spotify 

476 tracks by :func:`ensure_profile` - is never replaced. 

477 

478 *source* only chooses whose biography *text* is saved - every other 

479 field is fetched the same way whatever it is. ``'auto'`` (what 

480 :func:`ensure_profile` uses) is the behaviour described above: Apple 

481 Music's bio, Deezer's only as a fallback. ``'applemusic'`` and 

482 ``'deezer'`` are the user picking one: that service's bio replaces 

483 the saved one, with no fallback to the other, and nothing at all is 

484 saved (the current bio stays) if it has none. 

485 

486 Raises :class:`ValueError` when nothing at all was found - or, for an 

487 explicit *source*, when that service has no biography for the artist. 

488 """ 

489 

490 if source not in _BIO_SOURCES: 

491 raise ValueError(f'Unknown bio source: {source!r}') 

492 profile = load_profile(download_dir, name) 

493 _fill_profile(profile, name, lang, source) 

494 _save_profile(download_dir, name, profile) 

495 return profile 

496 

497 

498def _fill_profile( 

499 profile: dict[str, Any], 

500 name: str, 

501 lang: str, 

502 source: str, 

503 *, 

504 strict: bool = False, 

505) -> None: 

506 """The fetching half of :func:`fetch_bio`: fills *profile* in memory from 

507 Apple Music, Deezer and Spotify and saves nothing. Raises 

508 :class:`ValueError` exactly where :func:`fetch_bio` documents it. 

509 

510 Not *strict*, a service that fails is skipped, as if it had nothing. 

511 *strict* is for a profile that is seeded on its own (see 

512 :func:`_seed_profile`): there a failure of Apple Music or Deezer - 

513 whose lookups then tell an error from "no such artist" - raises 

514 :class:`ProfileUnavailable` instead, because what is saved would 

515 otherwise pass for the artist's real profile. Spotify's part (related 

516 names) stays best effort either way: it depends on a hash that Spotify 

517 rolls now and then, and that must not stop a profile from being made. 

518 """ 

519 

520 got_anything = False 

521 apple_bio = '' 

522 deezer_bio = '' 

523 

524 if strict: 

525 apple_id = _cached_apple_music_id(profile) 

526 if not apple_id: 

527 try: 

528 apple_id = apple_music.lookup_artist_id(name) or '' 

529 except ValueError as exc: 

530 raise ProfileUnavailable('Apple Music did not answer') from exc 

531 else: 

532 apple_id = _cached_or_resolved_apple_music_id(profile, name) 

533 if apple_id: 

534 try: 

535 apple_full = apple_music.fetch_artist_full(apple_id, lang) 

536 except ValueError as exc: 

537 if strict: 

538 raise ProfileUnavailable('Apple Music did not answer') from exc 

539 apple_full = None 

540 if apple_full is not None: 

541 got_anything = True 

542 profile['origin'] = apple_full['origin'] 

543 profile['born_or_formed'] = apple_full['born_or_formed'] 

544 profile['genre'] = apple_full['genre'] 

545 profile['is_group'] = apple_full['is_group'] 

546 profile['banner_bg_color'] = apple_full['banner_bg_color'] 

547 if apple_full['applemusic_id']: 

548 profile['platforms_id']['applemusic'] = apple_full[ 

549 'applemusic_id' 

550 ] 

551 if apple_full['bio_html']: 

552 apple_bio = _format_bio_text(apple_full['bio_html']) 

553 if source == BIO_SOURCE_AUTO: 

554 profile['bio'] = apple_bio 

555 

556 deezer_id = profile['platforms_id'].get('deezer') or '' 

557 if not deezer_id: 

558 if strict: 

559 try: 

560 deezer_id = deezer.lookup_artist_id(name) or '' 

561 except ValueError as exc: 

562 raise ProfileUnavailable('Deezer did not answer') from exc 

563 else: 

564 deezer_id = deezer.resolve_artist_id(name) or '' 

565 if deezer_id: 

566 profile['platforms_id']['deezer'] = deezer_id 

567 

568 if deezer_id: 

569 try: 

570 deezer_full = deezer.fetch_artist_full(deezer_id, lang) 

571 except ValueError as exc: 

572 if strict: 

573 raise ProfileUnavailable('Deezer did not answer') from exc 

574 deezer_full = None 

575 if deezer_full is not None: 

576 got_anything = True 

577 profile['social'] = _fill_empty_social( 

578 profile['social'], deezer_full['social'] 

579 ) 

580 profile['related_artists'] = deezer_full['related_artist_names'] 

581 if deezer_full['bio_html']: 

582 deezer_bio = _format_bio_text(deezer_full['bio_html']) 

583 if source == BIO_SOURCE_AUTO and not profile['bio']: 

584 profile['bio'] = deezer_bio 

585 

586 spotify_id = profile['platforms_id'].get('spotify') or '' 

587 if not spotify_id: 

588 spotify_id = _spotify_id_from_name(name) or '' 

589 if spotify_id: 

590 profile['platforms_id']['spotify'] = spotify_id 

591 if spotify_id: 

592 try: 

593 spotify_related = spotify.related_artist_names_from_id(spotify_id) 

594 except Exception: 

595 logger.opt(exception=True).debug( 

596 'Spotify related-artist fetch failed for {}', spotify_id 

597 ) 

598 spotify_related = [] 

599 if spotify_related: 

600 got_anything = True 

601 profile['related_artists'] = _merge_names( 

602 profile['related_artists'], spotify_related 

603 ) 

604 

605 if source == BIO_SOURCE_APPLE_MUSIC: 

606 if not apple_bio: 

607 raise ValueError( 

608 'Apple Music has no biography for this artist in this language' 

609 ) 

610 profile['bio'] = apple_bio 

611 elif source == BIO_SOURCE_DEEZER: 

612 if not deezer_bio: 

613 raise ValueError('Deezer has no biography for this artist') 

614 profile['bio'] = deezer_bio 

615 

616 if not got_anything: 

617 raise ValueError('No matching artist found on Apple Music or Deezer') 

618 

619 

620def preview_bio(download_dir: Path, name: str, lang: str, source: str) -> str: 

621 """*name*'s biography text from one service, **without saving 

622 anything** - what the artist edit modal loads into its text box so the 

623 user decides whether to keep it (see :func:`save_bio`). 

624 

625 *source* is ``'applemusic'`` or ``'deezer'``; there's no fallback to 

626 the other one. Read-only on the profile too: an artist id it has to 

627 look up is not cached, unlike in :func:`fetch_bio`. Raises 

628 :class:`ValueError` when that service has no biography. 

629 """ 

630 

631 if source not in {BIO_SOURCE_APPLE_MUSIC, BIO_SOURCE_DEEZER}: 

632 raise ValueError(f'Unknown bio source: {source!r}') 

633 profile = load_profile(download_dir, name) 

634 html = '' 

635 if source == BIO_SOURCE_APPLE_MUSIC: 

636 apple_id = _cached_or_resolved_apple_music_id(profile, name) 

637 if apple_id: 

638 try: 

639 html = apple_music.fetch_artist_full(apple_id, lang)[ 

640 'bio_html' 

641 ] 

642 except ValueError: 

643 html = '' 

644 missing = ( 

645 'Apple Music has no biography for this artist in this language' 

646 ) 

647 else: 

648 deezer_id = ( 

649 profile['platforms_id'].get('deezer') 

650 or deezer.resolve_artist_id(name) 

651 or '' 

652 ) 

653 if deezer_id: 

654 try: 

655 html = deezer.fetch_artist_full(deezer_id, lang)['bio_html'] 

656 except ValueError: 

657 html = '' 

658 missing = 'Deezer has no biography for this artist' 

659 text = _format_bio_text(html) if html else '' 

660 if not text: 

661 raise ValueError(missing) 

662 return text 

663 

664 

665def _spotify_id_from_name(name: str) -> Optional[str]: 

666 """Spotify artist id by exact name (see 

667 :func:`downtify.spotify.search_artist_by_name`), or ``None`` - never 

668 raises, so a Spotify hiccup can't fail a profile fetch.""" 

669 

670 try: 

671 found = spotify.search_artist_by_name(name) 

672 except Exception: 

673 logger.opt(exception=True).debug( 

674 'Spotify artist search failed for {!r}', name 

675 ) 

676 return None 

677 return found['id'] if found else None 

678 

679 

680def resolve_platform_ids( 

681 name: str, known: Optional[dict[str, str]] = None 

682) -> dict[str, str]: 

683 """*name* looked up across every stream platform with a name-search 

684 API, requiring an exact match on each (ignoring case and the 

685 characters a file name can't hold, see 

686 :func:`downtify.file_naming.file_name_key`) - same 

687 strictness as every platform's own ``resolve_artist_id``, so an 

688 unrelated top result never gets attached to the wrong artist. Only 

689 the platforms that actually matched are in the returned dict. 

690 

691 Covers Spotify (:func:`_spotify_id_from_name`), Deezer, YouTube Music 

692 and Apple Music (via :func:`apple_music.resolve_artist_slug_id`, 

693 already in the ``slug/numeric-id`` shape ``platforms_id.applemusic`` 

694 needs, resolved from the same search call as the plain id). 

695 

696 *known* is a ``platforms_id`` mapping: any platform with a non-empty 

697 id there is skipped (no request, not in the result), so an id 

698 already saved - above all a Spotify one resolved from the artist's 

699 own track, which is more reliable than a name match - is never 

700 replaced by a search result. 

701 """ 

702 

703 known = known or {} 

704 ids: dict[str, str] = {} 

705 if not known.get('spotify'): 

706 spotify_id = _spotify_id_from_name(name) 

707 if spotify_id: 

708 ids['spotify'] = spotify_id 

709 if not known.get('deezer'): 

710 deezer_id = deezer.resolve_artist_id(name) 

711 if deezer_id: 

712 ids['deezer'] = deezer_id 

713 if not known.get('youtubemusic'): 

714 ytm_id = providers.resolve_artist_id(name) 

715 if ytm_id: 

716 ids['youtubemusic'] = ytm_id 

717 if not known.get('applemusic'): 

718 apple_id = apple_music.resolve_artist_slug_id(name) 

719 if apple_id: 

720 ids['applemusic'] = apple_id 

721 return ids 

722 

723 

724def resolve_spotify_artist_id( 

725 track_files: list[str], track_index: Any, name: str = '' 

726) -> Optional[str]: 

727 """Spotify artist id, or ``None``. 

728 

729 First choice is the first of *track_files* that was itself 

730 downloaded from Spotify (*track_index* may be ``None`` to skip this): 

731 a track already known to be theirs can't resolve to a namesake. With 

732 *name*, it's the id of that artist among those the track credits - a 

733 guest's track belongs to someone else, whose id isn't theirs. When 

734 none is, *name* - if given - is searched on Spotify by exact name 

735 (:func:`_spotify_id_from_name`). Not private: a caller with its own 

736 track/track_index (e.g. a download-pipeline hook - see 

737 :func:`ensure_profile`) can reuse this directly instead of 

738 re-implementing the same loop. 

739 """ 

740 

741 for file in track_files[:5] if track_index is not None else []: 

742 filename = str(file or '').strip().replace('\\', '/') 

743 if not filename: 

744 continue 

745 track_id = track_index.spotify_id_for_filename(filename) 

746 if not track_id: 

747 continue 

748 try: 

749 artist_id = ( 

750 spotify.credited_artist_id_from_track_id(track_id, name) 

751 if name.strip() 

752 else spotify.primary_artist_id_from_track_id(track_id) 

753 ) 

754 except Exception: 

755 logger.opt(exception=True).debug( 

756 'Spotify artist id resolution failed for track {}', track_id 

757 ) 

758 continue 

759 if artist_id: 

760 return artist_id 

761 return _spotify_id_from_name(name) if name.strip() else None 

762 

763 

764def _seed_image_from_streams( 

765 download_dir: Path, 

766 name: str, 

767 kind: str, 

768 spotify_artist_id: Optional[str], 

769) -> None: 

770 """Save *name*'s photo/banner from Spotify, given an already- 

771 resolved artist id (see :func:`resolve_spotify_artist_id`). Falls 

772 back to an exact YouTube Music name match when Spotify has nothing 

773 (no id at all, or the artist simply has no banner set there). No-op 

774 if this *kind* is already saved. 

775 """ 

776 

777 if image_path_for(download_dir, name, kind).is_file(): 

778 return 

779 

780 if spotify_artist_id: 

781 url = '' 

782 try: 

783 url = ( 

784 spotify.artist_banner_url_from_id(spotify_artist_id) 

785 if kind == KIND_BANNER 

786 else spotify.artist_image_url_from_id(spotify_artist_id) 

787 ) 

788 except Exception: 

789 logger.opt(exception=True).debug( 

790 'Spotify artist art seed failed for {} ({})', 

791 spotify_artist_id, 

792 kind, 

793 ) 

794 if url: 

795 try: 

796 fetch_and_save_image( 

797 download_dir, name, kind, url, source='spotify' 

798 ) 

799 except ValueError: 

800 logger.debug( 

801 'Could not save seeded Spotify {} for {}', kind, name 

802 ) 

803 return 

804 

805 wanted = file_name_key(name) 

806 if not wanted: 

807 return 

808 for artist in providers.search_artists(name, limit=25): 

809 if file_name_key(str(artist.get('name') or '')) != wanted: 

810 continue 

811 url = artist.get('cover_url') or '' 

812 if url: 

813 try: 

814 fetch_and_save_image( 

815 download_dir, name, kind, url, source='youtube' 

816 ) 

817 except ValueError: 

818 logger.debug( 

819 'Could not save seeded YouTube Music {} for {}', 

820 kind, 

821 name, 

822 ) 

823 return 

824 

825 

826def ensure_profile( 

827 download_dir: Path, 

828 name: str, 

829 track_files: list[str], 

830 lang: str, 

831 track_index: Optional[Any] = None, 

832 image_kinds: tuple[str, ...] = (), 

833) -> dict[str, Any]: 

834 """Seed a brand-new artist's profile the first time it's needed 

835 (e.g. opening their Library page) and nothing has been saved for 

836 them yet: bio/social/origin/etc from Apple Music and Deezer (see 

837 :func:`_fill_profile`) and platform ids via :func:`resolve_platform_ids` 

838 - exactly as if the user had opened the picker and clicked the fetch 

839 button themselves - then photo/banner from Spotify/YouTube Music (see 

840 :func:`_seed_image_from_streams`), only the kinds in *image_kinds*, 

841 which callers derive from the user's ``download_cover_art_artist``/ 

842 ``download_cover_art_artist_banner`` settings (none by default: an 

843 image is never saved unless the caller says the user wants it). 

844 

845 A no-op past the first call for a given artist: once a profile file 

846 exists at all - even a mostly-empty one, if the services answered that 

847 nothing matches - every later call just returns :func:`load_profile` 

848 directly, so an obscure artist nothing matches doesn't re-run this 

849 full, several-requests-deep lookup on every single page visit. 

850 

851 A service that *fails* (Apple Music, Deezer: unreachable, over its 

852 limit) is a different thing from one with nothing to say: nothing is 

853 saved then - no file, no photo - and the blank profile comes back, so 

854 the next visit tries again instead of keeping a hollow profile for 

855 good (see :class:`ProfileUnavailable`). 

856 

857 *track_index* is optional: with it, Spotify's artist id comes from one 

858 of the artist's own Spotify tracks (the most reliable route); without 

859 it, or when no track has one, from an exact-name search (see 

860 :func:`resolve_spotify_artist_id`). The download pipeline seeds through 

861 :func:`profile_seed_enqueue` instead, with the id of the track it just 

862 downloaded. Both share :func:`_seed_profile` and the per-artist lock, so 

863 a visit and a download never seed the same artist twice. 

864 """ 

865 

866 if _profile_path_for(download_dir, name).is_file(): 

867 return load_profile(download_dir, name) 

868 

869 with _seed_lock_for(download_dir, name): 

870 # Whoever held the lock (a download, another visit) may just have 

871 # made it. 

872 if _profile_path_for(download_dir, name).is_file(): 

873 return load_profile(download_dir, name) 

874 spotify_artist_id = resolve_spotify_artist_id( 

875 track_files, track_index, name 

876 ) 

877 try: 

878 return _seed_profile( 

879 download_dir, name, spotify_artist_id, lang, image_kinds 

880 ) 

881 except ProfileUnavailable: 

882 logger.debug('Profile of {!r} not seeded: a service failed', name) 

883 return load_profile(download_dir, name) 

884 

885 

886def _seed_profile( 

887 download_dir: Path, 

888 name: str, 

889 spotify_artist_id: Optional[str], 

890 lang: str, 

891 image_kinds: tuple[str, ...], 

892) -> dict[str, Any]: 

893 """Make *name*'s profile and save it; the caller holds the artist's lock 

894 (see :func:`_seed_lock_for`) and has seen there is no profile yet. 

895 

896 Everything is fetched *before* anything is written, so 

897 :class:`ProfileUnavailable` (Apple Music or Deezer failed) leaves no file 

898 at all - not a profile holding just a bio, and no photo either. Neither 

899 service knowing the artist is an answer, not a failure: the profile is 

900 made with what is known, and the file's mere existence is what makes 

901 later visits skip this. Photo/banner come last and are best effort: an 

902 error there is logged and leaves the (already saved) text as it is. 

903 """ 

904 

905 profile = load_profile(download_dir, name) 

906 if spotify_artist_id: 

907 profile['platforms_id']['spotify'] = spotify_artist_id 

908 try: 

909 _fill_profile(profile, name, lang, BIO_SOURCE_AUTO, strict=True) 

910 except ValueError: 

911 pass # neither Apple Music nor Deezer has this artist 

912 # Only what _fill_profile (and the Spotify id above) didn't already 

913 # resolve - and never over an id that's already there. 

914 platform_ids = resolve_platform_ids(name, known=profile['platforms_id']) 

915 if platform_ids: 

916 profile['platforms_id'] = {**profile['platforms_id'], **platform_ids} 

917 _save_profile(download_dir, name, profile) 

918 

919 for kind in image_kinds: 

920 try: 

921 _seed_image_from_streams( 

922 download_dir, name, kind, spotify_artist_id 

923 ) 

924 except Exception: 

925 logger.opt(exception=True).debug( 

926 'Artist {} seed failed for {!r}', kind, name 

927 ) 

928 return load_profile(download_dir, name) 

929 

930 

931# ── Seeding from the download pipeline ────────────────────────────── 

932# 

933# A track that finishes downloading asks for its artist's profile (see 

934# ``api.enrich_artist_after_download``, hooked to ``Downloader.on_downloaded``). 

935# A playlist can finish hundreds of tracks by dozens of artists at once, so: 

936# 

937# 1. *distinct*: an artist already waiting or being seeded is not queued again 

938# (:data:`_seed_pending`, checked and set under one lock); 

939# 2. a small pool of daemon threads does the work, so the download that asked 

940# never waits and the services aren't hit by hundreds of lookups at once; 

941# 3. the worker takes the artist's lock (shared with :func:`ensure_profile`) 

942# and looks again for the file, so a visit and a download - or two workers - 

943# can't seed the same artist twice, whatever the timing. 

944# 

945# An artist whose services failed is simply not saved (see 

946# :class:`ProfileUnavailable`), and the next track of theirs - or a visit to 

947# their page - tries again; nothing remembers the failure. 

948 

949#: Artists seeded at the same time. 

950SEED_WORKERS = 2 

951 

952_seed_locks: dict[str, threading.Lock] = {} 

953_seed_locks_guard = threading.Lock() 

954_seed_pending: set[str] = set() 

955_seed_pending_guard = threading.Lock() 

956_seed_jobs: queue.SimpleQueue = queue.SimpleQueue() 

957_seed_workers: list[threading.Thread] = [] 

958_seed_workers_guard = threading.Lock() 

959 

960 

961def _seed_key(download_dir: Path, name: str) -> str: 

962 return str(_profile_path_for(download_dir, name)).lower() 

963 

964 

965def _seed_lock_for(download_dir: Path, name: str) -> threading.Lock: 

966 """One lock per artist, shared by every way of seeding them.""" 

967 

968 with _seed_locks_guard: 

969 return _seed_locks.setdefault( 

970 _seed_key(download_dir, name), threading.Lock() 

971 ) 

972 

973 

974def profile_seed_artist_of(song: dict[str, Any]) -> str: 

975 """The artist whose profile a downloaded *song* seeds: the one its file 

976 is filed under (:func:`downtify.album_artist.filing_artist` - the album 

977 artist, or for a compilation the track's first artist), or ``''`` when 

978 that is no one worth a profile (``Various Artists``).""" 

979 

980 name = filing_artist(song) 

981 return '' if name.casefold() in {'various artists', 'unknown'} else name 

982 

983 

984def _spotify_artist_id_for_song( 

985 song: dict[str, Any], name: str 

986) -> Optional[str]: 

987 """Spotify's id for *name*: from the song's own Spotify track when it 

988 credits *name* (it can't pick a namesake), else an exact-name search.""" 

989 

990 track_id = song.get('song_id') 

991 artists = song.get('artists') or [] 

992 if ( 

993 song.get('source') == 'spotify' 

994 and isinstance(track_id, str) 

995 and re.fullmatch(r'[A-Za-z0-9]{22}', track_id) 

996 and any(file_name_key(str(a)) == file_name_key(name) for a in artists) 

997 ): 

998 try: 

999 found = spotify.credited_artist_id_from_track_id(track_id, name) 

1000 except Exception: 

1001 logger.opt(exception=True).debug( 

1002 'Spotify artist id from track {} failed', track_id 

1003 ) 

1004 found = None 

1005 if found: 

1006 return found 

1007 return _spotify_id_from_name(name) 

1008 

1009 

1010def profile_seed_song( 

1011 download_dir: Path, 

1012 song: dict[str, Any], 

1013 lang: str, 

1014 image_kinds: tuple[str, ...] = (), 

1015) -> bool: 

1016 """Seed the profile of *song*'s artist, unless it already exists (or 

1017 someone is making it). Blocking - what the pool's workers run. Returns 

1018 whether a profile was made; a failure of Apple Music or Deezer makes 

1019 none (see :class:`ProfileUnavailable`).""" 

1020 

1021 name = profile_seed_artist_of(song) 

1022 if not name or _profile_path_for(download_dir, name).is_file(): 

1023 return False 

1024 with _seed_lock_for(download_dir, name): 

1025 if _profile_path_for(download_dir, name).is_file(): 

1026 return False 

1027 spotify_artist_id = _spotify_artist_id_for_song(song, name) 

1028 try: 

1029 _seed_profile( 

1030 download_dir, name, spotify_artist_id, lang, image_kinds 

1031 ) 

1032 except ProfileUnavailable: 

1033 logger.debug('Profile of {!r} not seeded: a service failed', name) 

1034 return False 

1035 return True 

1036 

1037 

1038def profile_seed_enqueue( 

1039 download_dir: Path, 

1040 song: dict[str, Any], 

1041 lang: str, 

1042 image_kinds: tuple[str, ...] = (), 

1043) -> bool: 

1044 """Queue seeding *song*'s artist and return at once (a download must not 

1045 wait for this); ``False`` when there is nothing to do - no artist worth a 

1046 profile, one that already has it, or one that is already queued.""" 

1047 

1048 name = profile_seed_artist_of(song) 

1049 if not name or _profile_path_for(download_dir, name).is_file(): 

1050 return False 

1051 key = _seed_key(download_dir, name) 

1052 with _seed_pending_guard: 

1053 if key in _seed_pending: 

1054 return False 

1055 _seed_pending.add(key) 

1056 _seed_jobs.put((key, Path(download_dir), dict(song), lang, image_kinds)) 

1057 _start_seed_workers() 

1058 return True 

1059 

1060 

1061def _run_seed_job(job: tuple[Any, ...]) -> None: 

1062 key, download_dir, song, lang, image_kinds = job 

1063 try: 

1064 profile_seed_song(download_dir, song, lang, image_kinds) 

1065 except Exception: 

1066 logger.opt(exception=True).debug('Profile seeding failed') 

1067 finally: 

1068 with _seed_pending_guard: 

1069 _seed_pending.discard(key) 

1070 

1071 

1072def _seed_worker() -> None: 

1073 while True: 

1074 _run_seed_job(_seed_jobs.get()) 

1075 

1076 

1077def _start_seed_workers() -> None: 

1078 # Daemon threads on purpose: a pool that runs its queue dry at exit would 

1079 # hold the app up for as long as a big playlist's artists take. 

1080 with _seed_workers_guard: 

1081 _seed_workers[:] = [t for t in _seed_workers if t.is_alive()] 

1082 while len(_seed_workers) < SEED_WORKERS: 

1083 worker = threading.Thread( 

1084 target=_seed_worker, name='downtify-profile-seed', daemon=True 

1085 ) 

1086 worker.start() 

1087 _seed_workers.append(worker) 

1088 

1089 

1090def remove_bio(download_dir: Path, name: str) -> dict[str, Any]: 

1091 """Clear only the saved bio text. 

1092 

1093 ``social``, ``related_artists`` and ``platforms_id`` are left as-is - 

1094 a re-fetch afterwards still reuses the cached Deezer id instead of 

1095 searching by name again. 

1096 """ 

1097 

1098 profile = load_profile(download_dir, name) 

1099 profile['bio'] = '' 

1100 _save_profile(download_dir, name, profile) 

1101 return profile 

1102 

1103 

1104def save_bio(download_dir: Path, name: str, bio: str) -> dict[str, Any]: 

1105 """Manually set *name*'s bio text, overwriting a fetched or prior one. 

1106 

1107 Unlike :func:`fetch_bio`, this never touches Apple Music/Deezer - 

1108 it's the user typing their own text into the artist page's editor 

1109 (plain text, blank lines between paragraphs). Still run through 

1110 :func:`_format_bio_text` so ``bio`` is always the same plain-text 

1111 shape (no HTML, no bullets) regardless of where it came from. 

1112 """ 

1113 

1114 profile = load_profile(download_dir, name) 

1115 profile['bio'] = _format_bio_text(bio or '') 

1116 _save_profile(download_dir, name, profile) 

1117 return profile 

1118 

1119 

1120def save_social( 

1121 download_dir: Path, name: str, social: dict[str, Any] 

1122) -> dict[str, Any]: 

1123 """Manually set *name*'s social links, replacing all four fields. 

1124 

1125 Like :func:`save_bio`, this is the user editing directly - it never 

1126 fetches anything. Unknown/missing keys in *social* are saved as 

1127 empty strings rather than left at whatever was there before, since 

1128 the editor always submits its full form. 

1129 """ 

1130 

1131 profile = load_profile(download_dir, name) 

1132 default_social = _default_profile(name)['social'] 

1133 profile['social'] = { 

1134 key: str(social.get(key) or '').strip() for key in default_social 

1135 } 

1136 _save_profile(download_dir, name, profile) 

1137 return profile 

1138 

1139 

1140# ── Top songs: the Spotify shelf, kept as a JSON cache ────────────── 

1141# 

1142# Fetching an artist's top songs is slow - the artist embed, one embed per 

1143# song for its cover and album, and an overview request for the play counts 

1144# (see :func:`downtify.spotify.artist_top_songs_from_id`) - so the first 

1145# five are saved to ``.metadata/ArtistTopSongs/<name>.topsongs.json``, next 

1146# to the artist's photo, banner and profile. It is a cache, not user data: 

1147# machine-written, never edited by hand, and separate from 

1148# ``ArtistData/<name>.json`` on purpose (a bio or social-link save rewrites 

1149# that whole file, and deleting it to re-seed an artist shouldn't touch 

1150# this one). 

1151# 

1152# Only links and text are stored - the covers and the 30 s preview clips 

1153# stay remote URLs, nothing is downloaded - and nothing that changes per 

1154# download: whether a song is in the library or the queue is worked out 

1155# live by the UI. 

1156# 

1157# A file is *fresh* for :data:`TOP_SONGS_TTL` (7 days: play counts move 

1158# daily, the ranking rarely), only while it belongs to the Spotify artist id 

1159# asked about and only in the current :data:`TOP_SONGS_SCHEMA`. 

1160# :func:`profile_top_songs_ensure` is the one entry point: it creates the 

1161# file when it is missing or stale and otherwise just reads it, so the 

1162# artist page, the profile seeding and - later - the download pipeline can 

1163# all call it whenever they need the songs. 

1164 

1165_top_songs_locks: dict[str, threading.Lock] = {} 

1166_top_songs_locks_guard = threading.Lock() 

1167 

1168 

1169def profile_top_songs_path_for(download_dir: Path, name: str) -> Path: 

1170 """The file for *name*'s top songs, whether or not it exists.""" 

1171 

1172 return ( 

1173 Path(download_dir) 

1174 / _TOP_SONGS_DIRNAME 

1175 / f'{_sanitize(name)}{_TOP_SONGS_SUFFIX}' 

1176 ) 

1177 

1178 

1179def _profile_top_songs_lock_for( 

1180 download_dir: Path, name: str 

1181) -> threading.Lock: 

1182 """One lock per artist: a background refresh and a request for the 

1183 same artist queue up behind each other instead of fetching twice.""" 

1184 

1185 key = str(profile_top_songs_path_for(download_dir, name)).lower() 

1186 with _top_songs_locks_guard: 

1187 return _top_songs_locks.setdefault(key, threading.Lock()) 

1188 

1189 

1190def profile_top_songs_load( 

1191 download_dir: Path, name: str 

1192) -> Optional[dict[str, Any]]: 

1193 """The saved file, or ``None`` when missing, unreadable or malformed.""" 

1194 

1195 try: 

1196 data = json.loads( 

1197 profile_top_songs_path_for(download_dir, name).read_text( 

1198 encoding='utf-8' 

1199 ) 

1200 ) 

1201 except (OSError, ValueError): 

1202 return None 

1203 if not isinstance(data, dict) or not isinstance(data.get('songs'), list): 

1204 return None 

1205 return data 

1206 

1207 

1208def _parse_fetched_at(value: Any) -> Optional[datetime]: 

1209 try: 

1210 parsed = datetime.fromisoformat(str(value)) 

1211 except ValueError: 

1212 return None 

1213 return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc) 

1214 

1215 

1216def profile_top_songs_is_fresh( 

1217 data: Optional[dict[str, Any]], 

1218 spotify_artist_id: str, 

1219 now: Optional[datetime] = None, 

1220) -> bool: 

1221 """Whether *data* can be served as is: it belongs to 

1222 *spotify_artist_id* (a corrected id must not keep serving the old 

1223 artist's songs), is of the current :data:`TOP_SONGS_SCHEMA` and was 

1224 fetched less than :data:`TOP_SONGS_TTL` ago.""" 

1225 

1226 if not data or str(data.get('artist_id') or '') != spotify_artist_id: 

1227 return False 

1228 if data.get('schema') != TOP_SONGS_SCHEMA: 

1229 return False 

1230 fetched = _parse_fetched_at(data.get('fetched_at')) 

1231 if fetched is None: 

1232 return False 

1233 return (now or datetime.now(timezone.utc)) - fetched < TOP_SONGS_TTL 

1234 

1235 

1236def profile_top_songs_cached( 

1237 download_dir: Path, name: str, spotify_artist_id: str 

1238) -> tuple[Optional[dict[str, Any]], bool]: 

1239 """``(saved file or None, is it fresh)`` - no network.""" 

1240 

1241 data = profile_top_songs_load(download_dir, name) 

1242 return data, profile_top_songs_is_fresh(data, spotify_artist_id) 

1243 

1244 

1245def _profile_top_songs_write( 

1246 download_dir: Path, name: str, data: dict[str, Any] 

1247) -> None: 

1248 """Write atomically (temp file, then rename): a reader never sees a 

1249 half-written file, even with a request racing a background refresh.""" 

1250 

1251 _atomic_write_json(profile_top_songs_path_for(download_dir, name), data) 

1252 

1253 

1254def _profile_top_songs_fetch(spotify_artist_id: str) -> dict[str, Any]: 

1255 artist_name, cover_url, songs = spotify.artist_top_songs_from_id( 

1256 spotify_artist_id, limit=TOP_SONGS_LIMIT 

1257 ) 

1258 return { 

1259 'schema': TOP_SONGS_SCHEMA, 

1260 'source': 'spotify', 

1261 'artist_id': spotify_artist_id, 

1262 'name': artist_name, 

1263 'cover_url': cover_url, 

1264 'fetched_at': datetime.now(timezone.utc).isoformat(timespec='seconds'), 

1265 'songs': songs, 

1266 } 

1267 

1268 

1269def profile_top_songs_ensure( 

1270 download_dir: Path, name: str, spotify_artist_id: str 

1271) -> dict[str, Any]: 

1272 """*name*'s top songs: the saved file while it is fresh, otherwise 

1273 fetched from Spotify and saved. 

1274 

1275 The single entry point - the artist page, the profile seeding and the 

1276 download pipeline all go through it, so a missing or stale file gets 

1277 (re)created by whoever needs it first. Blocking (seconds when it has 

1278 to fetch): run it off the event loop. 

1279 

1280 A failed refresh falls back to the stale file when there is one; with 

1281 nothing saved the error propagates. An empty shelf is returned but not 

1282 saved, so a transient failure isn't trusted for a week. 

1283 """ 

1284 

1285 if not spotify_artist_id: 

1286 raise ValueError('No Spotify artist id') 

1287 with _profile_top_songs_lock_for(download_dir, name): 

1288 # Re-read under the lock: whoever held it may just have written it. 

1289 saved = profile_top_songs_load(download_dir, name) 

1290 if profile_top_songs_is_fresh(saved, spotify_artist_id): 

1291 return saved # type: ignore[return-value] 

1292 try: 

1293 data = _profile_top_songs_fetch(spotify_artist_id) 

1294 except Exception: 

1295 if saved is not None and saved.get('artist_id') == ( 

1296 spotify_artist_id 

1297 ): 

1298 logger.opt(exception=True).warning( 

1299 'Top songs refresh failed for {}; serving the saved file', 

1300 name, 

1301 ) 

1302 return saved 

1303 raise 

1304 if data['songs']: 

1305 _profile_top_songs_write(download_dir, name, data) 

1306 return data 

1307 

1308 

1309def profile_top_songs_refresh_in_background( 

1310 download_dir: Path, name: str, spotify_artist_id: str 

1311) -> bool: 

1312 """Start :func:`profile_top_songs_ensure` on a daemon thread when the 

1313 file is missing or stale and nobody is already fetching it; returns 

1314 whether a thread was started. Never raises and never blocks - for 

1315 callers (the profile seeding) that want the file made without waiting 

1316 for it.""" 

1317 

1318 if not spotify_artist_id: 

1319 return False 

1320 _, fresh = profile_top_songs_cached(download_dir, name, spotify_artist_id) 

1321 if fresh or _profile_top_songs_lock_for(download_dir, name).locked(): 

1322 return False 

1323 

1324 def run() -> None: 

1325 try: 

1326 profile_top_songs_ensure(download_dir, name, spotify_artist_id) 

1327 except Exception: 

1328 logger.opt(exception=True).debug( 

1329 'Background top songs fetch failed for {}', name 

1330 ) 

1331 

1332 threading.Thread( 

1333 target=run, name='downtify-top-songs', daemon=True 

1334 ).start() 

1335 return True