Coverage for downtify/deezer.py: 93%

675 statements  

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

1"""Search the public Deezer API for artist photo candidates, fetch 

2bio/social/related-artist data from Deezer's internal web-player API, 

3read Deezer's own global "what's trending" chart, and resolve a pasted 

4Deezer track/album/playlist/artist link the same way :mod:`downtify.spotify` 

5and :mod:`downtify.providers` do for Spotify and YouTube Music (see 

6:func:`parse_deezer_url` and ``downtify.api``'s ``_deezer_details``), and 

7back the Finder page's Deezer-only search and artist/album/track column 

8view (see :func:`finder_search` and the functions after it). 

9 

10``api.deezer.com`` is unauthenticated and keyless, same shape of 

11integration as :mod:`downtify.itunes`. Deezer's artist search never 

12returns a banner-shaped image, only square profile photos. 

13 

14Bio/social data has no public REST equivalent at all (verified live: 

15``/artist/{id}`` has no bio field, and ``/artist/{id}/biography`` etc. 

16all 400). Related artists do - ``/artist/{id}/related``, keyless like the 

17search, is what :func:`related_artists` (the Discover page, see 

18:mod:`downtify.discover`) reads - but the artist profile keeps taking its 

19related-artist names from the same call as the bio. The only way to get 

20the bio is 

21Deezer's *internal*, undocumented web-player GraphQL API 

22(``pipe.deezer.com/api``), which is fragile by nature: it only accepts 

23an anonymous token's exact, full, persisted "ArtistFull" query text 

24(captured live from the browser, see :func:`fetch_artist_full`) - a 

25hand-trimmed query gets a generic, unhelpful error instead of the usual 

26GraphQL validation message. Treat this as append-only: if Deezer changes 

27that query shape, this needs a fresh capture, not a clever rewrite. 

28""" 

29 

30from __future__ import annotations 

31 

32import re 

33import threading 

34import time 

35from collections import deque 

36from concurrent.futures import ThreadPoolExecutor 

37from typing import Any, Callable, Optional 

38from urllib.parse import urlsplit 

39 

40import httpx 

41from loguru import logger 

42 

43from . import providers 

44from .album_artist import album_artist_fields 

45from .file_naming import file_name_key, title_key 

46 

47_SEARCH_URL = 'https://api.deezer.com/search/artist' 

48_RELATED_URL = 'https://api.deezer.com/artist/{artist_id}/related' 

49_TRACK_SEARCH_URL = 'https://api.deezer.com/search/track' 

50# Deezer's 30 s clips are served from here (``cdnt-preview.dzcdn.net``). 

51_PREVIEW_HOST_SUFFIX = '.dzcdn.net' 

52_AUTH_URL = 'https://auth.deezer.com/login/anonymous' 

53_GRAPHQL_URL = 'https://pipe.deezer.com/api' 

54_CHART_URL = 'https://api.deezer.com/chart' 

55_TIMEOUT = 10 

56_GRAPHQL_TIMEOUT = 15 

57 

58# Captured live from www.deezer.com's web player (DevTools network tab). 

59# Must be sent verbatim - the server enforces this as a persisted/ 

60# allowlisted query, not just valid GraphQL. `me`/`isFavorite` come back 

61# as UnloggedUserError for an anonymous token; that's expected and 

62# doesn't block the rest of the response. 

63_ARTIST_FULL_QUERY = """query ArtistFull($artistId: String!, $relatedArtistFirst: Int!, $liveEventsFirst: Int!) { 

64 artist(artistId: $artistId) { 

65 ...ArtistMasthead 

66 relatedArtists: relatedArtist(first: $relatedArtistFirst) { 

67 edges { 

68 cursor 

69 node { 

70 ...ArtistBase 

71 __typename 

72 } 

73 __typename 

74 } 

75 pageInfo { 

76 hasNextPage 

77 hasPreviousPage 

78 startCursor 

79 endCursor 

80 __typename 

81 } 

82 __typename 

83 } 

84 liveEvents( 

85 first: $liveEventsFirst 

86 types: [CONCERT, FESTIVAL] 

87 statuses: [PENDING] 

88 ) { 

89 edges { 

90 node { 

91 id 

92 __typename 

93 } 

94 __typename 

95 } 

96 pageInfo { 

97 endCursor 

98 hasNextPage 

99 __typename 

100 } 

101 __typename 

102 } 

103 __typename 

104 } 

105 me { 

106 userFavorites { 

107 byArtist(artistId: $artistId) { 

108 estimatedTracksCount 

109 __typename 

110 } 

111 __typename 

112 } 

113 __typename 

114 } 

115} 

116 

117fragment ArtistMasthead on Artist { 

118 ...ArtistBase 

119 ...ArtistBio 

120 ...ArtistSocial 

121 onTour 

122 status 

123 __typename 

124} 

125 

126fragment ArtistBase on Artist { 

127 id 

128 name 

129 fansCount 

130 hasSmartRadio 

131 isFavorite 

132 picture { 

133 ...PictureSmall 

134 ...PictureMedium 

135 ...PictureLarge 

136 __typename 

137 } 

138 __typename 

139} 

140 

141fragment PictureSmall on Picture { 

142 id 

143 small: urls(pictureRequest: {height: 100, width: 100}) 

144 explicitStatus 

145 __typename 

146} 

147 

148fragment PictureMedium on Picture { 

149 id 

150 medium: urls(pictureRequest: {width: 264, height: 264}) 

151 explicitStatus 

152 __typename 

153} 

154 

155fragment PictureLarge on Picture { 

156 id 

157 large: urls(pictureRequest: {width: 500, height: 500}) 

158 explicitStatus 

159 __typename 

160} 

161 

162fragment ArtistBio on Artist { 

163 bio { 

164 full 

165 __typename 

166 } 

167 __typename 

168} 

169 

170fragment ArtistSocial on Artist { 

171 social { 

172 twitter 

173 facebook 

174 website 

175 instagram 

176 __typename 

177 } 

178 __typename 

179}""" 

180 

181 

182# Deezer has no "this artist has no photo" flag: an artist without one gets 

183# a picture whose CDN path carries the md5 of an empty string, which turns 

184# out as a generic grey placeholder (found live: the obscure "Survivor" that 

185# ranks above the real band). Recognising that hash is the only tell. 

186_NO_PICTURE_HASH = 'd41d8cd98f00b204e9800998ecf8427e' 

187 

188 

189def _has_real_picture(row: dict[str, Any]) -> bool: 

190 """Whether a search row's artist has an actual photo, not Deezer's 

191 placeholder (see :data:`_NO_PICTURE_HASH`).""" 

192 

193 for key in ( 

194 'picture_xl', 

195 'picture_big', 

196 'picture_medium', 

197 'picture_small', 

198 ): 

199 url = str(row.get(key) or '') 

200 if url: 

201 return _NO_PICTURE_HASH not in url 

202 return False 

203 

204 

205def _most_popular_exact_match( 

206 rows: list[Any], name: str 

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

208 """Of the rows whose name is *name* - the same name on disk, so 

209 ``AC/DC`` matches ``ACDC`` (see :func:`file_name_key`) - the one with 

210 the most fans, or ``None``. 

211 

212 Deezer doesn't rank namesakes by popularity: the well-known "Survivor" 

213 (261k fans) comes after an unknown one (34 fans, no photo). Taking the 

214 first exact match would attach the wrong artist's id or face. 

215 """ 

216 

217 wanted = file_name_key(name) 

218 if not wanted: 

219 return None 

220 matches = [ 

221 row 

222 for row in rows 

223 if isinstance(row, dict) 

224 and file_name_key(str(row.get('name') or '')) == wanted 

225 ] 

226 if not matches: 

227 return None 

228 return max(matches, key=lambda row: int(row.get('nb_fan') or 0)) 

229 

230 

231def _search_rows(text: str, limit: int) -> list[Any]: 

232 """The rows of Deezer's artist search for *text*. 

233 

234 Raises :class:`ValueError` whenever Deezer did not really answer: it 

235 can't be reached, refuses (an HTTP error) or - the sneaky one - reports 

236 a problem inside a *successful* response. Its limit of 50 requests per 

237 5 seconds is reported that way: HTTP 200, an ``error`` object 

238 (``{"code": 4, "message": "Quota limit exceeded"}``) and no ``data``, 

239 which would read as "no such artist" if taken at face value. Callers 

240 must not remember any of this as an answer. 

241 """ 

242 

243 try: 

244 resp = httpx.get( 

245 _SEARCH_URL, params={'q': text, 'limit': limit}, timeout=_TIMEOUT 

246 ) 

247 resp.raise_for_status() 

248 data = resp.json() 

249 except Exception as exc: 

250 logger.opt(exception=True).debug('Deezer artist search failed') 

251 raise ValueError('Could not reach Deezer') from exc 

252 if not isinstance(data, dict): 

253 raise ValueError('Deezer sent an unexpected answer') 

254 if data.get('error'): 

255 logger.debug('Deezer refused the artist search: {}', data['error']) 

256 raise ValueError('Deezer refused the request') 

257 return data.get('data') or [] 

258 

259 

260def search_artist(query: str, limit: int = 10) -> list[dict[str, Any]]: 

261 """Artist photo candidates for *query*, largest Deezer offers each. 

262 

263 Each result is ``{source: 'deezer', name, image_url, url}`` - same 

264 shape the artist-image picker expects from every source. An artist 

265 with only Deezer's placeholder picture is left out: it isn't a photo 

266 anyone could pick. 

267 """ 

268 

269 text = query.strip() 

270 if not text: 

271 return [] 

272 try: 

273 rows = _search_rows(text, max(1, limit)) 

274 except ValueError: 

275 return [] 

276 

277 results: list[dict[str, Any]] = [] 

278 for row in rows: 

279 if not isinstance(row, dict): 

280 continue 

281 name = str(row.get('name') or '').strip() 

282 image = ( 

283 row.get('picture_xl') 

284 or row.get('picture_big') 

285 or row.get('picture_medium') 

286 or '' 

287 ) 

288 if not name or not image or not _has_real_picture(row): 

289 continue 

290 results.append({ 

291 'source': 'deezer', 

292 'name': name, 

293 'image_url': image, 

294 'url': row.get('link') or '', 

295 }) 

296 return results 

297 

298 

299def lookup_artist_id(name: str) -> Optional[str]: 

300 """Deezer's numeric artist id for an exact name match, or ``None`` if 

301 no result's name matches exactly. Case and the characters a file name 

302 can't hold are ignored (``ACDC`` matches ``AC/DC``, see 

303 :func:`downtify.file_naming.file_name_key`). 

304 

305 Deliberately stricter than :func:`search_artist`: an unrelated top 

306 result would silently attach the wrong bio/social/related-artists to 

307 this artist's profile, so a fuzzy "good enough" match isn't good 

308 enough here. Several artists can share the exact name; the one with 

309 the most fans wins (see :func:`_most_popular_exact_match`). 

310 

311 Raises :class:`ValueError` when Deezer didn't really answer (see 

312 :func:`_search_rows`), so ``None`` always means "no such artist" - 

313 :func:`resolve_artist_id` is the same without that distinction. 

314 """ 

315 

316 text = name.strip() 

317 if not file_name_key(text): 

318 return None 

319 match = _most_popular_exact_match(_search_rows(text, 25), text) 

320 if match is None: 

321 return None 

322 artist_id = match.get('id') 

323 return str(artist_id) if artist_id is not None else None 

324 

325 

326def resolve_artist_id(name: str) -> Optional[str]: 

327 """:func:`lookup_artist_id`, with a failed lookup reading as ``None`` 

328 - for the callers where "couldn't find out" and "no such artist" may 

329 be treated alike.""" 

330 

331 try: 

332 return lookup_artist_id(name) 

333 except ValueError: 

334 return None 

335 

336 

337def exact_artist_picture(name: str) -> Optional[str]: 

338 """Deezer's medium-size profile photo URL for an exact artist name 

339 match (same rule as :func:`resolve_artist_id`), or ``None``. 

340 

341 One search call, no id needed. Same strictness as 

342 :func:`resolve_artist_id`, and the same pick among namesakes (the 

343 most popular one): a near match would show another artist's face 

344 under this name. If that artist has no photo - Deezer only has its 

345 placeholder (see :data:`_NO_PICTURE_HASH`) - the answer is ``None``, 

346 not a namesake's photo or the placeholder. 

347 

348 Raises :class:`ValueError` when Deezer can't be reached or refuses 

349 (a rate limit, say, see :func:`_search_rows`): that is not "this 

350 artist has no photo", and the caller must not remember it as one. 

351 """ 

352 

353 text = name.strip() 

354 if not file_name_key(text): 

355 return None 

356 match = _most_popular_exact_match(_search_rows(text, 25), text) 

357 if match is None or not _has_real_picture(match): 

358 return None 

359 return match.get('picture_medium') or None 

360 

361 

362def _picture(row: dict[str, Any]) -> str: 

363 """A row's largest real photo, or ``""`` for Deezer's placeholder.""" 

364 

365 if not _has_real_picture(row): 

366 return '' 

367 return str( 

368 row.get('picture_big') 

369 or row.get('picture_xl') 

370 or row.get('picture_medium') 

371 or '' 

372 ) 

373 

374 

375def related_artists(artist_id: str, limit: int = 20) -> list[dict[str, Any]]: 

376 """Deezer's "similar artists" for a Deezer artist id, best match first. 

377 

378 Each is ``{deezer_id, name, picture_url, fans}`` - ``picture_url`` is 

379 ``""`` for an artist with only Deezer's placeholder (see 

380 :data:`_NO_PICTURE_HASH`). Public and keyless, like the artist search. 

381 

382 Raises :class:`ValueError` when Deezer didn't really answer - including 

383 its rate limit, which comes back as an HTTP 200 with an ``error`` 

384 object (see :func:`_search_rows`) - so ``[]`` always means "Deezer has 

385 no related artists for this one". 

386 """ 

387 

388 try: 

389 resp = httpx.get( 

390 _RELATED_URL.format(artist_id=artist_id), 

391 params={'limit': max(1, limit)}, 

392 timeout=_TIMEOUT, 

393 ) 

394 resp.raise_for_status() 

395 data = resp.json() 

396 except Exception as exc: 

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

398 'Deezer related-artists fetch failed for {}', artist_id 

399 ) 

400 raise ValueError('Could not reach Deezer') from exc 

401 if not isinstance(data, dict): 

402 raise ValueError('Deezer sent an unexpected answer') 

403 if data.get('error'): 

404 logger.debug('Deezer refused the related artists: {}', data['error']) 

405 raise ValueError('Deezer refused the request') 

406 

407 related: list[dict[str, Any]] = [] 

408 for row in data.get('data') or []: 

409 if not isinstance(row, dict): 

410 continue 

411 name = str(row.get('name') or '').strip() 

412 if not name or row.get('id') is None: 

413 continue 

414 related.append({ 

415 'deezer_id': str(row['id']), 

416 'name': name, 

417 'picture_url': _picture(row), 

418 'fans': int(row.get('nb_fan') or 0), 

419 }) 

420 return related 

421 

422 

423def _preview_link(url: Any) -> str: 

424 """*url* when it's an https link to Deezer's clip CDN, else ``""``.""" 

425 

426 if not isinstance(url, str): 

427 return '' 

428 parts = urlsplit(url) 

429 host = parts.hostname or '' 

430 if parts.scheme == 'https' and host.endswith(_PREVIEW_HOST_SUFFIX): 

431 return url 

432 return '' 

433 

434 

435def find_track_preview( 

436 artist: str, title: str, duration: Optional[float] = None 

437) -> str: 

438 """The 30 s preview clip Deezer has for a song, or ``""``. 

439 

440 For a song with no clip of its own (a YouTube Music result, or a 

441 Spotify playlist track past what the embed page lists). Deezer's 

442 public track search is keyless; a row counts only when its artist is 

443 *artist* and its title is *title*, both compared the way a file name 

444 keeps them and ignoring ``(Live)``/``[Remastered]``/`` - Radio Edit`` 

445 style suffixes, so another artist's cover or a different song is never 

446 played in its place. Among those, the one closest to *duration* wins, 

447 so a live version doesn't beat the studio one. 

448 

449 Raises :class:`ValueError` when Deezer didn't really answer (see 

450 :func:`_search_rows`), so ``""`` always means "no clip found". 

451 """ 

452 

453 wanted_artist = file_name_key(artist) 

454 wanted_title = title_key(title) 

455 if not wanted_artist or not wanted_title: 

456 return '' 

457 try: 

458 resp = httpx.get( 

459 _TRACK_SEARCH_URL, 

460 params={'q': f'{artist} {title}', 'limit': 25}, 

461 timeout=_TIMEOUT, 

462 ) 

463 resp.raise_for_status() 

464 data = resp.json() 

465 except Exception as exc: 

466 logger.opt(exception=True).debug('Deezer track search failed') 

467 raise ValueError('Could not reach Deezer') from exc 

468 if not isinstance(data, dict): 

469 raise ValueError('Deezer sent an unexpected answer') 

470 if data.get('error'): 

471 logger.debug('Deezer refused the track search: {}', data['error']) 

472 raise ValueError('Deezer refused the request') 

473 

474 matches = [] 

475 for row in data.get('data') or []: 

476 if not isinstance(row, dict): 

477 continue 

478 preview = _preview_link(row.get('preview')) 

479 row_artist = str((row.get('artist') or {}).get('name') or '') 

480 if not preview or file_name_key(row_artist) != wanted_artist: 

481 continue 

482 titles = { 

483 title_key(row.get('title')), 

484 title_key(row.get('title_short')), 

485 } 

486 if wanted_title not in titles: 

487 continue 

488 matches.append((row, preview)) 

489 if not matches: 

490 return '' 

491 if duration: 

492 matches.sort( 

493 key=lambda m: abs(float(m[0].get('duration') or 0) - duration) 

494 ) 

495 return matches[0][1] 

496 

497 

498def find_track_cover(artist: str, title: str, px: int) -> str: 

499 """The cover of the release Deezer has *artist*'s *title* on, at the 

500 smallest of Deezer's sizes that reaches *px* (its largest, 1000px, 

501 when none does), or ``""``. 

502 

503 Matched like :func:`find_track_preview`: the row's artist must be 

504 *artist* and its title *title*, ignoring ``(Live)``-style suffixes, 

505 so another song's cover is never taken. Raises :class:`ValueError` 

506 when Deezer didn't really answer. 

507 """ 

508 

509 wanted_artist = file_name_key(artist) 

510 wanted_title = title_key(title) 

511 if not wanted_artist or not wanted_title: 

512 return '' 

513 try: 

514 resp = httpx.get( 

515 _TRACK_SEARCH_URL, 

516 params={'q': f'{artist} {title}', 'limit': 25}, 

517 timeout=_TIMEOUT, 

518 ) 

519 resp.raise_for_status() 

520 data = resp.json() 

521 except Exception as exc: 

522 logger.opt(exception=True).debug('Deezer track search failed') 

523 raise ValueError('Could not reach Deezer') from exc 

524 if not isinstance(data, dict) or data.get('error'): 

525 raise ValueError('Deezer refused the request') 

526 for row in data.get('data') or []: 

527 if not isinstance(row, dict): 

528 continue 

529 row_artist = str((row.get('artist') or {}).get('name') or '') 

530 if file_name_key(row_artist) != wanted_artist: 

531 continue 

532 titles = { 

533 title_key(row.get('title')), 

534 title_key(row.get('title_short')), 

535 } 

536 if wanted_title not in titles: 

537 continue 

538 album = row.get('album') or {} 

539 if not isinstance(album, dict): 

540 continue 

541 largest = '' 

542 for suffix, pixels in _COVER_SIZES: 

543 url = str(album.get(f'cover_{suffix}') or '') 

544 if not url: 

545 continue 

546 largest = url 

547 if pixels >= px: 

548 return url 

549 if largest: 

550 return largest 

551 return '' 

552 

553 

554def fetch_artist_full(artist_id: str, lang: str) -> dict[str, Any]: 

555 """Bio, social links and related-artist names for a Deezer artist id. 

556 

557 ``lang`` is sent as ``Accept-Language`` - the bio text itself changes 

558 (not just an echoed header), confirmed live for ``pt-BR``/``en``. 

559 Raises :class:`ValueError` if the request or the token exchange fails. 

560 

561 ``social.instagram`` is a real schema field but came back ``null`` 

562 for every artist tried live (old and current, big and small) - it 

563 looks unpopulated on Deezer's side. When an artist does have an 

564 Instagram link, Deezer sometimes stores it under ``facebook`` 

565 instead (seen live for at least two artists) - there's no reliable 

566 way to detect that case from here, so it's left as-is. 

567 """ 

568 

569 try: 

570 auth_resp = httpx.get( 

571 _AUTH_URL, 

572 params={'jo': 'p', 'rto': 'c', 'i': 'c'}, 

573 timeout=_TIMEOUT, 

574 ) 

575 auth_resp.raise_for_status() 

576 token = auth_resp.json().get('jwt') 

577 if not token: 

578 raise ValueError('No anonymous Deezer token returned') 

579 

580 resp = httpx.post( 

581 _GRAPHQL_URL, 

582 headers={ 

583 'Authorization': f'Bearer {token}', 

584 'Accept-Language': lang or 'en', 

585 'Referer': 'https://www.deezer.com/', 

586 'Content-Type': 'application/json', 

587 }, 

588 json={ 

589 'operationName': 'ArtistFull', 

590 'variables': { 

591 'artistId': str(artist_id), 

592 'relatedArtistFirst': 10, 

593 'liveEventsFirst': 1, 

594 }, 

595 'query': _ARTIST_FULL_QUERY, 

596 }, 

597 timeout=_GRAPHQL_TIMEOUT, 

598 ) 

599 resp.raise_for_status() 

600 payload = resp.json() 

601 except Exception as exc: 

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

603 'Deezer artist bio fetch failed for {}', artist_id 

604 ) 

605 raise ValueError('Could not fetch artist info from Deezer') from exc 

606 

607 artist = (payload.get('data') or {}).get('artist') or {} 

608 social = artist.get('social') or {} 

609 related_edges = (artist.get('relatedArtists') or {}).get('edges') or [] 

610 related_names = [ 

611 str(edge['node']['name']).strip() 

612 for edge in related_edges 

613 if isinstance(edge, dict) 

614 and isinstance(edge.get('node'), dict) 

615 and edge['node'].get('name') 

616 ] 

617 return { 

618 'bio_html': str((artist.get('bio') or {}).get('full') or ''), 

619 'social': { 

620 'twitter': str(social.get('twitter') or ''), 

621 'facebook': str(social.get('facebook') or ''), 

622 'website': str(social.get('website') or ''), 

623 'instagram': str(social.get('instagram') or ''), 

624 }, 

625 'related_artist_names': related_names, 

626 } 

627 

628 

629def _chart_payload(limit: int) -> dict[str, Any]: 

630 """The raw ``GET /chart`` response (no genre id - Deezer's own overall 

631 "what's trending" chart), or raise :class:`ValueError`. 

632 

633 Same "HTTP 200 but an ``error`` object instead of data" trap as 

634 :func:`_search_rows` - a rate limit would otherwise read as an empty 

635 chart. 

636 """ 

637 

638 try: 

639 resp = httpx.get(_CHART_URL, params={'limit': limit}, timeout=_TIMEOUT) 

640 resp.raise_for_status() 

641 data = resp.json() 

642 except Exception as exc: 

643 logger.opt(exception=True).debug('Deezer chart fetch failed') 

644 raise ValueError('Could not reach Deezer') from exc 

645 if not isinstance(data, dict): 

646 raise ValueError('Deezer sent an unexpected answer') 

647 if data.get('error'): 

648 logger.debug('Deezer refused the chart request: {}', data['error']) 

649 raise ValueError('Deezer refused the request') 

650 return data 

651 

652 

653def _chart_track_song(row: dict[str, Any]) -> Optional[dict[str, Any]]: 

654 """A chart track row as a Downtify song (``source: 'deezer'``), or 

655 ``None`` when it's missing a title, an id or every artist name. 

656 

657 Shaped like :func:`downtify.providers._result_to_song` so it can be 

658 queued for download exactly like a search result - see 

659 :func:`downtify.api._song_from_download_request`, which lets a 

660 ``source: 'deezer'`` row skip the Spotify/YouTube URL parsing 

661 ``/api/download/url`` would otherwise require, since a Deezer track 

662 link isn't one this app can resolve on its own. 

663 """ 

664 

665 track_id = row.get('id') 

666 name = str(row.get('title') or row.get('title_short') or '').strip() 

667 if not track_id or not name: 

668 return None 

669 artist = row.get('artist') if isinstance(row.get('artist'), dict) else {} 

670 album = row.get('album') if isinstance(row.get('album'), dict) else {} 

671 artists = [] 

672 lead = str(artist.get('name') or '').strip() 

673 if lead: 

674 artists.append(lead) 

675 for contributor in row.get('contributors') or []: 

676 if not isinstance(contributor, dict): 

677 continue 

678 contributor_name = str(contributor.get('name') or '').strip() 

679 if contributor_name and contributor_name not in artists: 

680 artists.append(contributor_name) 

681 if not artists: 

682 return None 

683 cover = _cover_from_images(album) 

684 # A 30s MP3 clip Deezer's own player streams for unauthenticated users - 

685 # always https when present. See lib/preview.js on the frontend, which 

686 # refuses to hand anything else to an <audio> element. 

687 preview = str(row.get('preview') or '') 

688 return { 

689 'song_id': f'deezer-{track_id}', 

690 'name': name, 

691 'artists': artists, 

692 'album_name': str(album.get('title') or '').strip(), 

693 'cover_url': cover, 

694 'duration': int(row.get('duration') or 0), 

695 'url': str(row.get('link') or ''), 

696 'preview_url': preview if preview.startswith('https://') else '', 

697 'explicit': bool(row.get('explicit_lyrics')), 

698 'year': '', 

699 'release_date': '', 

700 'source': 'deezer', 

701 } 

702 

703 

704def _chart_album_release(row: dict[str, Any]) -> Optional[dict[str, Any]]: 

705 """A chart album row as a read-only release summary, or ``None``. 

706 

707 Downtify has no Deezer discography resolver (unlike its Spotify/ 

708 YouTube Music ones), so this is display-only: ``url`` opens the album 

709 on Deezer rather than feeding ``/api/url/resolve``. 

710 """ 

711 

712 album_id = row.get('id') 

713 name = str(row.get('title') or '').strip() 

714 if not album_id or not name: 

715 return None 

716 artist = row.get('artist') if isinstance(row.get('artist'), dict) else {} 

717 cover = _cover_from_images(row) 

718 return { 

719 'album_id': str(album_id), 

720 'name': name, 

721 'artist': str(artist.get('name') or '').strip(), 

722 'cover_url': cover, 

723 'url': str(row.get('link') or ''), 

724 'source': 'deezer', 

725 } 

726 

727 

728def _chart_artist_release(row: dict[str, Any]) -> Optional[dict[str, Any]]: 

729 """A chart artist row as a read-only release summary, or ``None``. 

730 

731 Same placeholder-picture check as :func:`_has_real_picture` - the 

732 chart ranks by popularity, so an unphotographed artist here would be 

733 unusual, but it's still not worth showing Deezer's generic grey face 

734 for. 

735 """ 

736 

737 artist_id = row.get('id') 

738 name = str(row.get('name') or '').strip() 

739 if not artist_id or not name: 

740 return None 

741 return { 

742 'artist_id': str(artist_id), 

743 'name': name, 

744 'cover_url': ( 

745 _cover_from_images(row, prefix='picture') 

746 if _has_real_picture(row) 

747 else '' 

748 ), 

749 'url': str(row.get('link') or ''), 

750 'source': 'deezer', 

751 } 

752 

753 

754def _chart_playlist_release(row: dict[str, Any]) -> Optional[dict[str, Any]]: 

755 """A chart playlist row as a read-only release summary, or ``None``. 

756 

757 Same read-only reasoning as :func:`_chart_album_release`: Downtify has 

758 no way to resolve a Deezer playlist into a tracklist. 

759 """ 

760 

761 playlist_id = row.get('id') 

762 name = str(row.get('title') or '').strip() 

763 if not playlist_id or not name: 

764 return None 

765 user = row.get('user') if isinstance(row.get('user'), dict) else {} 

766 cover = _cover_from_images(row, prefix='picture') 

767 return { 

768 'playlist_id': str(playlist_id), 

769 'name': name, 

770 'owner': str(user.get('name') or '').strip(), 

771 'cover_url': cover, 

772 'url': str(row.get('link') or ''), 

773 'source': 'deezer', 

774 } 

775 

776 

777def _chart_section( 

778 data: dict[str, Any], 

779 key: str, 

780 mapper: Any, 

781) -> list[dict[str, Any]]: 

782 rows: list[dict[str, Any]] = [] 

783 for row in (data.get(key) or {}).get('data') or []: 

784 if not isinstance(row, dict): 

785 continue 

786 mapped = mapper(row) 

787 if mapped: 

788 rows.append(mapped) 

789 return rows 

790 

791 

792def fetch_chart(limit: int = 25) -> dict[str, Any]: 

793 """Deezer's global "what's trending" chart: top tracks, albums, 

794 artists and playlists - ``{tracks, albums, artists, playlists}``. 

795 

796 Tracks are downloadable Downtify song rows, with a 30s preview clip 

797 when Deezer offers one (see :func:`_chart_track_song`); everything 

798 else is a read-only summary (see :func:`_chart_album_release`, 

799 :func:`_chart_artist_release`, :func:`_chart_playlist_release`). 

800 

801 Raises :class:`ValueError` when Deezer can't be reached or refuses 

802 (see :func:`_chart_payload`). 

803 """ 

804 

805 data = _chart_payload(max(1, min(limit, 50))) 

806 return { 

807 'tracks': _chart_section(data, 'tracks', _chart_track_song), 

808 'albums': _chart_section(data, 'albums', _chart_album_release), 

809 'artists': _chart_section(data, 'artists', _chart_artist_release), 

810 'playlists': _chart_section( 

811 data, 'playlists', _chart_playlist_release 

812 ), 

813 } 

814 

815 

816# ── Pasted-link resolution (track/album/playlist/artist) ─────────────── 

817# 

818# Unlike the chart above (rows already embedded in one response) or the 

819# artist-photo search (no id needed), these read a specific Deezer id the 

820# same way downtify.spotify/downtify.providers do for a pasted Spotify or 

821# YouTube Music link - see downtify.api's _deezer_details, wired into 

822# GET /api/url/resolve, /api/song/url and /api/artists/top_songs/url next 

823# to the existing Spotify/YouTube Music branches. 

824 

825_DEEZER_URL_RE = re.compile( 

826 r'deezer\.com/(?:[a-z]{2}/)?(track|album|playlist|artist)/(\d+)', 

827 re.IGNORECASE, 

828) 

829 

830 

831def parse_deezer_url(url: str) -> Optional[tuple[str, str]]: 

832 """``(kind, id)`` for a Deezer track/album/playlist/artist URL, or 

833 ``None``. 

834 

835 Matches ``deezer.com/track/123`` with or without a ``www.`` or a 

836 two-letter locale segment (``deezer.com/br/track/123``, as Deezer's 

837 own share links carry). Deezer's short ``deezer.page.link`` share 

838 links aren't recognized - they'd need an extra redirect-following 

839 request just to find out what they point at. 

840 """ 

841 

842 match = _DEEZER_URL_RE.search(str(url or '')) 

843 if not match: 

844 return None 

845 return match.group(1).lower(), match.group(2) 

846 

847 

848class DeezerRefused(ValueError): 

849 """A 200 reply carrying an ``error`` object, with Deezer's error code 

850 (4 quota, 700 busy, 800 no data; 0 when it sent none).""" 

851 

852 def __init__(self, message: str, code: int = 0) -> None: 

853 super().__init__(message) 

854 self.code = code 

855 

856 

857def _get_json(url: str, **params: Any) -> dict[str, Any]: 

858 """A Deezer REST GET, or raise :class:`ValueError`. 

859 

860 A refusal raises :class:`DeezerRefused` (a ``ValueError``). 

861 

862 Same "HTTP 200 but an ``error`` object instead of data" trap as 

863 :func:`_search_rows` - an invalid id, a rate limit, all read this 

864 way rather than as an HTTP error status. 

865 """ 

866 

867 try: 

868 resp = httpx.get(url, params=params or None, timeout=_TIMEOUT) 

869 resp.raise_for_status() 

870 data = resp.json() 

871 except Exception as exc: 

872 logger.opt(exception=True).debug('Deezer request failed: {}', url) 

873 raise ValueError('Could not reach Deezer') from exc 

874 if not isinstance(data, dict): 

875 raise ValueError('Deezer sent an unexpected answer') 

876 if data.get('error'): 

877 logger.debug('Deezer refused {}: {}', url, data['error']) 

878 error = data['error'] 

879 code = error.get('code') if isinstance(error, dict) else 0 

880 raise DeezerRefused( 

881 'Deezer refused the request', 

882 code if isinstance(code, int) else 0, 

883 ) 

884 return data 

885 

886 

887def _artists_from_track_row(row: dict[str, Any]) -> list[str]: 

888 """Lead artist first, then any featured contributors - deduplicated, 

889 same convention as :func:`_chart_track_song`.""" 

890 

891 artist = row.get('artist') if isinstance(row.get('artist'), dict) else {} 

892 artists: list[str] = [] 

893 lead = str(artist.get('name') or '').strip() 

894 if lead: 

895 artists.append(lead) 

896 for contributor in row.get('contributors') or []: 

897 if not isinstance(contributor, dict): 

898 continue 

899 name = str(contributor.get('name') or '').strip() 

900 if name and name not in artists: 

901 artists.append(name) 

902 return artists 

903 

904 

905# Deezer's four fixed image sizes, smallest first - unlike a YouTube Music 

906# thumbnail (any pixel size, by editing its URL - see 

907# providers._resize_thumbnail), these are separately served images at 

908# exactly these dimensions and nothing in between. 

909_COVER_SIZES = (('small', 56), ('medium', 250), ('big', 500), ('xl', 1000)) 

910 

911 

912def _cover_from_images(d: dict[str, Any], prefix: str = 'cover') -> str: 

913 """The smallest of Deezer's four image sizes that still meets the 

914 configured cover size - the same ``cover_resolution`` setting Settings 

915 already uses for YouTube Music cover art (see 

916 :func:`downtify.providers.cover_resolution`). ``cover`` for a track/ 

917 album/playlist, ``picture`` for an artist. 

918 

919 When the configured size is bigger than every size Deezer offers 

920 (its largest, ``xl``, is 1000px), the largest one present is used 

921 instead - the best Deezer has, rather than nothing. 

922 """ 

923 

924 wanted = providers.cover_resolution() 

925 largest_seen = '' 

926 for suffix, pixels in _COVER_SIZES: 

927 url = d.get(f'{prefix}_{suffix}') 

928 if not url: 

929 continue 

930 largest_seen = url 

931 if pixels >= wanted: 

932 return url 

933 return largest_seen 

934 

935 

936def _year_from_release_date(value: str) -> str: 

937 text = str(value or '').strip() 

938 return text[:4] if len(text) >= 4 and text[:4].isdigit() else '' 

939 

940 

941def _song_from_full_track( 

942 row: dict[str, Any], 

943 *, 

944 track_number: int = 0, 

945 album_track_total: int = 0, 

946 release_date: str = '', 

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

948 """A full Deezer track resource - or an album/playlist tracklist row, 

949 same shape minus a couple of fields - as a downloadable Downtify song. 

950 

951 Unlike a chart row (:func:`_chart_track_song`), this fills in a 

952 release date whenever one is available: the caller's own 

953 (an album's ``release_date``, for every one of its tracks), else the 

954 row's or its embedded album's. 

955 """ 

956 

957 track_id = row.get('id') 

958 name = str(row.get('title') or row.get('title_short') or '').strip() 

959 if not track_id or not name: 

960 return None 

961 artists = _artists_from_track_row(row) 

962 if not artists: 

963 return None 

964 album = row.get('album') if isinstance(row.get('album'), dict) else {} 

965 preview = str(row.get('preview') or '') 

966 rd = ( 

967 release_date 

968 or str(row.get('release_date') or '').strip() 

969 or str(album.get('release_date') or '').strip() 

970 ) 

971 song: dict[str, Any] = { 

972 'song_id': f'deezer-{track_id}', 

973 'name': name, 

974 'artists': artists, 

975 'album_name': str(album.get('title') or '').strip(), 

976 'cover_url': _cover_from_images(album), 

977 'duration': int(row.get('duration') or 0), 

978 'url': str(row.get('link') or ''), 

979 'preview_url': preview if preview.startswith('https://') else '', 

980 'explicit': bool(row.get('explicit_lyrics')), 

981 'year': _year_from_release_date(rd), 

982 'release_date': rd, 

983 'source': 'deezer', 

984 } 

985 if 'contributors' not in row: 

986 # An album/playlist tracklist row names only the lead artist; the 

987 # guests are read from the track itself before it's downloaded 

988 # (see enrich_track_from_deezer_if_sparse). 

989 song['artists_unverified'] = True 

990 if track_number: 

991 song['track_number'] = track_number 

992 if album_track_total: 

993 song['album_track_total'] = album_track_total 

994 return song 

995 

996 

997def enrich_track_from_deezer_if_sparse(song: dict[str, Any]) -> dict[str, Any]: 

998 """*song* with every credited artist, for a Deezer album or playlist 

999 row that only named its lead artist (``artists_unverified``) - one 

1000 request for the track itself, made when it is downloaded rather than 

1001 for every row of an album when it is opened. Anything else, or a 

1002 failed request, is returned as it is.""" 

1003 

1004 if song.get('source') != 'deezer' or not song.get('artists_unverified'): 

1005 return song 

1006 track_id = str(song.get('song_id') or '').removeprefix('deezer-') 

1007 if not track_id.isdigit(): 

1008 return song 

1009 try: 

1010 row = _get_json(f'https://api.deezer.com/track/{track_id}') 

1011 except ValueError: 

1012 logger.debug('Deezer artists lookup failed for {}', track_id) 

1013 return song 

1014 artists = _artists_from_track_row(row) 

1015 if not artists: 

1016 return song 

1017 enriched = {**song, 'artists': artists} 

1018 enriched.pop('artists_unverified', None) 

1019 return enriched 

1020 

1021 

1022def track_from_id(track_id: str) -> dict[str, Any]: 

1023 """A single Deezer track, as a downloadable Downtify song. 

1024 

1025 Raises :class:`ValueError` when the id doesn't resolve (Deezer 

1026 answers a missing id with an ``error`` object, not an HTTP 404 - see 

1027 :func:`_get_json`) or has no title/artist to build a song from. 

1028 """ 

1029 

1030 row = _get_json(f'https://api.deezer.com/track/{track_id}') 

1031 song = _song_from_full_track( 

1032 row, track_number=int(row.get('track_position') or 0) 

1033 ) 

1034 if song is None: 

1035 raise ValueError('Deezer track has no title or artist') 

1036 song.update(_album_artist_of_track(row)) 

1037 return song 

1038 

1039 

1040def _album_artist_fields(album: dict[str, Any]) -> dict[str, Any]: 

1041 """``album_artist`` (and ``compilation``) fields from a Deezer album 

1042 resource's ``artist`` - matched by id, since Deezer localizes the 

1043 "Various Artists" name ("Vários intérpretes").""" 

1044 

1045 artist = ( 

1046 album.get('artist') if isinstance(album.get('artist'), dict) else {} 

1047 ) 

1048 return album_artist_fields( 

1049 artist.get('name'), artist_id=str(artist.get('id') or '') 

1050 ) 

1051 

1052 

1053def _album_artist_of_track(row: dict[str, Any]) -> dict[str, Any]: 

1054 """The album artist of a track resource's album, which the track 

1055 resource itself doesn't carry - one more request; ``{}`` (so the 

1056 track's first artist is used) when it fails.""" 

1057 

1058 album = row.get('album') if isinstance(row.get('album'), dict) else {} 

1059 album_id = album.get('id') 

1060 if not album_id: 

1061 return {} 

1062 try: 

1063 payload = _get_json(f'https://api.deezer.com/album/{album_id}') 

1064 except ValueError: 

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

1066 'Deezer album lookup failed for {}', album_id 

1067 ) 

1068 return {} 

1069 return _album_artist_fields(payload) 

1070 

1071 

1072def _paginate_tracks(first_page: dict[str, Any]) -> list[dict[str, Any]]: 

1073 """Every row of a Deezer tracklist, following ``next`` - a full URL 

1074 to the following page, present whenever there is one - until Deezer 

1075 stops offering one. Trusted the same way Spotify's playlist ``total`` 

1076 is: Deezer's own cursor, not re-derived from a track count.""" 

1077 

1078 rows: list[dict[str, Any]] = list(first_page.get('data') or []) 

1079 next_url = first_page.get('next') 

1080 while next_url: 

1081 page = _get_json(next_url) 

1082 rows.extend(page.get('data') or []) 

1083 next_url = page.get('next') 

1084 return rows 

1085 

1086 

1087def album_from_id(album_id: str) -> list[dict[str, Any]]: 

1088 """Every track of a Deezer album/single/EP, in tracklist order. 

1089 

1090 Each track's position in the list is its ``track_number`` - Deezer 

1091 already returns them in tracklist order - since the per-track rows 

1092 embedded in an album's response don't carry one of their own (unlike 

1093 a standalone :func:`track_from_id` lookup). The album's own 

1094 ``release_date`` fills in what those rows don't carry either. 

1095 

1096 Raises :class:`ValueError` when the id doesn't resolve or the 

1097 request fails. 

1098 """ 

1099 

1100 return _album_songs(_get_json(f'https://api.deezer.com/album/{album_id}')) 

1101 

1102 

1103def album_credits_from_id( 

1104 album_id: str, 

1105) -> tuple[str, list[str], list[dict[str, Any]]]: 

1106 """``(album_artist, main_artists, songs)`` for a Deezer album - its 

1107 tracks as :func:`album_from_id` lists them, plus whom the release is 

1108 credited to, in the same single request: the album artist and every 

1109 contributor Deezer gives the ``Main`` role (a joint album's second 

1110 artist; also, often, the guest of a "feat." single). 

1111 

1112 Raises :class:`ValueError` when the id doesn't resolve or the 

1113 request fails. 

1114 """ 

1115 

1116 payload = _get_json(f'https://api.deezer.com/album/{album_id}') 

1117 artist = ( 

1118 payload.get('artist') 

1119 if isinstance(payload.get('artist'), dict) 

1120 else {} 

1121 ) 

1122 main = [ 

1123 str(row.get('name') or '').strip() 

1124 for row in payload.get('contributors') or [] 

1125 if isinstance(row, dict) and row.get('role') == 'Main' 

1126 ] 

1127 return ( 

1128 str(artist.get('name') or '').strip(), 

1129 [name for name in main if name], 

1130 _album_songs(payload), 

1131 ) 

1132 

1133 

1134def _album_songs(payload: dict[str, Any]) -> list[dict[str, Any]]: 

1135 """Every track of an already-fetched ``GET /album/{id}`` response - 

1136 see :func:`album_from_id`.""" 

1137 

1138 rows = _paginate_tracks(payload.get('tracks') or {}) 

1139 release_date = str(payload.get('release_date') or '').strip() 

1140 album_fields = _album_artist_fields(payload) 

1141 total = len(rows) 

1142 songs: list[dict[str, Any]] = [] 

1143 for index, row in enumerate(rows): 

1144 if not isinstance(row, dict): 

1145 continue 

1146 song = _song_from_full_track( 

1147 row, 

1148 track_number=index + 1, 

1149 album_track_total=total, 

1150 release_date=release_date, 

1151 ) 

1152 if song: 

1153 songs.append({**song, **album_fields}) 

1154 return songs 

1155 

1156 

1157def playlist_info_and_tracks( 

1158 playlist_id: str, 

1159) -> tuple[str, list[dict[str, Any]]]: 

1160 """``(name, tracks)`` for a Deezer playlist, fetching every track via 

1161 :func:`_paginate_tracks`. 

1162 

1163 Deliberately doesn't number the tracks: unlike an album, a playlist's 

1164 position isn't a track's real position on its own album, and its 

1165 tracks come from many different albums anyway - each keeps whatever 

1166 ``release_date`` its own row/album happens to carry (usually none; 

1167 Deezer's playlist-track rows carry a slimmer album reference than 

1168 :func:`track_from_id`'s or :func:`album_from_id`'s do). 

1169 

1170 Raises :class:`ValueError` when the id doesn't resolve or the 

1171 request fails. 

1172 """ 

1173 

1174 name, _cover, songs = playlist_page_from_id(playlist_id) 

1175 return name, songs 

1176 

1177 

1178def playlist_page_from_id( 

1179 playlist_id: str, 

1180) -> tuple[str, str, list[dict[str, Any]]]: 

1181 """Name, official image and tracks from one playlist response.""" 

1182 

1183 payload = _get_json(f'https://api.deezer.com/playlist/{playlist_id}') 

1184 name = str(payload.get('title') or '').strip() or str(playlist_id) 

1185 rows = _paginate_tracks(payload.get('tracks') or {}) 

1186 songs: list[dict[str, Any]] = [] 

1187 for row in rows: 

1188 if not isinstance(row, dict): 

1189 continue 

1190 song = _song_from_full_track(row) 

1191 if song: 

1192 songs.append(song) 

1193 return name, _cover_from_images(payload, prefix='picture'), songs 

1194 

1195 

1196def playlist_cover_url_from_id(playlist_id: str) -> str: 

1197 """Largest cover art of a Deezer playlist, for saving alongside its 

1198 M3U file - same idea as 

1199 :func:`downtify.spotify.playlist_cover_url_from_id`. 

1200 

1201 A playlist's own image fields are named ``picture_*`` (like an 

1202 artist's), not ``cover_*`` (like a track/album's). 

1203 

1204 Raises :class:`ValueError` when the id doesn't resolve or the 

1205 request fails. 

1206 """ 

1207 

1208 payload = _get_json(f'https://api.deezer.com/playlist/{playlist_id}') 

1209 return _cover_from_images(payload, prefix='picture') 

1210 

1211 

1212# Deezer's own release-type classification (``record_type``), title-cased 

1213# the same way downtify.spotify._RELEASE_TYPES is - ReleaseCard.vue only 

1214# translates 'album'/'single'/'ep' and shows anything else (a 

1215# 'compile'/"Compilation" release) as-is. 

1216_RECORD_TYPE_LABELS = { 

1217 'album': 'Album', 

1218 'single': 'Single', 

1219 'ep': 'EP', 

1220 'compile': 'Compilation', 

1221} 

1222 

1223 

1224def _artist_release_row( 

1225 row: dict[str, Any], artist_name: str 

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

1227 """One row of a Deezer artist's discography as a release summary. 

1228 

1229 Unlike an album/playlist track row, an artist's own albums listing 

1230 doesn't repeat the artist's name on each row (it's implied), so 

1231 *artist_name* - the artist page's own name - fills it in. 

1232 """ 

1233 

1234 album_id = row.get('id') 

1235 name = str(row.get('title') or '').strip() 

1236 if not album_id or not name: 

1237 return None 

1238 return { 

1239 'album_id': str(album_id), 

1240 'name': name, 

1241 'artist': artist_name, 

1242 'cover_url': _cover_from_images(row), 

1243 'year': _year_from_release_date(row.get('release_date')), 

1244 # Its day: one in the future is announced, not out yet. 

1245 'release_date': str(row.get('release_date') or '').strip(), 

1246 'explicit': bool(row.get('explicit_lyrics')), 

1247 'url': str(row.get('link') or ''), 

1248 'source': 'deezer', 

1249 'release_type': _release_type_label(row.get('record_type')), 

1250 } 

1251 

1252 

1253def _release_type_label(record_type: Any) -> str: 

1254 """Deezer's ``record_type`` as a label (see :data:`_RECORD_TYPE_LABELS`), 

1255 ``Album`` when it has none.""" 

1256 

1257 text = str(record_type or '').strip().lower() 

1258 return _RECORD_TYPE_LABELS.get(text, text.title() or 'Album') 

1259 

1260 

1261def artist_page_from_id( 

1262 artist_id: str, 

1263) -> tuple[str, str, list[dict[str, Any]]]: 

1264 """``(name, cover_url, releases)`` for a Deezer artist - their full 

1265 discography (every album, single, EP and compilation Deezer has), 

1266 Deezer's own order (most recent first). 

1267 

1268 Raises :class:`ValueError` when the id doesn't resolve or the 

1269 request fails. 

1270 """ 

1271 

1272 info = _get_json(f'https://api.deezer.com/artist/{artist_id}') 

1273 name = str(info.get('name') or '').strip() or str(artist_id) 

1274 cover = _cover_from_images(info, prefix='picture') 

1275 first_page = _get_json( 

1276 f'https://api.deezer.com/artist/{artist_id}/albums', limit=100 

1277 ) 

1278 rows = _paginate_tracks(first_page) 

1279 releases: list[dict[str, Any]] = [] 

1280 for row in rows: 

1281 if not isinstance(row, dict): 

1282 continue 

1283 release = _artist_release_row(row, name) 

1284 if release: 

1285 releases.append(release) 

1286 return name, cover, releases 

1287 

1288 

1289# The Deezer equivalent of downtify.api.YOUTUBE_TOP_SONGS_LIMIT - Deezer's 

1290# own artist "top" endpoint is already ranked by popularity, so only its 

1291# head is worth listing. 

1292TOP_SONGS_LIMIT = 50 

1293 

1294 

1295def artist_top_songs_from_id( 

1296 artist_id: str, 

1297) -> tuple[str, str, list[dict[str, Any]]]: 

1298 """``(name, cover_url, songs)`` for a Deezer artist's own "top" 

1299 ranking (their most-played tracks - the same shelf ``deezer.com`` 

1300 shows on an artist's page). 

1301 

1302 Raises :class:`ValueError` when the id doesn't resolve or the 

1303 request fails. 

1304 """ 

1305 

1306 info = _get_json(f'https://api.deezer.com/artist/{artist_id}') 

1307 name = str(info.get('name') or '').strip() or str(artist_id) 

1308 cover = _cover_from_images(info, prefix='picture') 

1309 top = _get_json( 

1310 f'https://api.deezer.com/artist/{artist_id}/top', 

1311 limit=TOP_SONGS_LIMIT, 

1312 ) 

1313 songs: list[dict[str, Any]] = [] 

1314 for row in top.get('data') or []: 

1315 if not isinstance(row, dict): 

1316 continue 

1317 song = _song_from_full_track(row) 

1318 if song: 

1319 songs.append(song) 

1320 return name, cover, songs 

1321 

1322 

1323# ── Finder: free-text search, then artist → albums → tracks ──────────── 

1324# 

1325# Deezer-only, read-only browsing for the Finder page: a free-text search 

1326# across tracks/albums/artists, then - in columns, like macOS Finder's 

1327# column view - an artist's profile, their discography and one album's 

1328# tracklist. Each carries as much as the public REST API offers for it, 

1329# not just what a download needs. 

1330 

1331_FINDER_SEARCH_URL = 'https://api.deezer.com/search' 

1332_FINDER_WORKERS = 4 

1333 

1334# How many album ids one album_track_counts() call looks up at most. 

1335TRACK_COUNTS_MAX_IDS = 50 

1336 

1337# An artist's albums listing carries no track count (only an album search 

1338# row does - verified live), so the Finder asks for each album's on its 

1339# own, one GET per album. Deezer allows 50 requests per 5 seconds per IP; 

1340# staying under 40 leaves room for everything else running meanwhile. 

1341_THROTTLE_WINDOW = 5.0 

1342_THROTTLE_MAX = 40 

1343_throttle_lock = threading.Lock() 

1344_throttle_times: deque[float] = deque() 

1345 

1346# Album id -> track count. A released album's count doesn't change, so it 

1347# is kept for the life of the process (bounded, just in case). 

1348_ALBUM_TRACK_COUNTS: dict[str, int] = {} 

1349_ALBUM_TRACK_COUNTS_MAX = 5000 

1350 

1351 

1352def _throttle() -> None: 

1353 """Wait until another request fits under :data:`_THROTTLE_MAX` per 

1354 :data:`_THROTTLE_WINDOW` seconds, then claim it.""" 

1355 

1356 while True: 

1357 with _throttle_lock: 

1358 now = time.monotonic() 

1359 while ( 

1360 _throttle_times 

1361 and now - _throttle_times[0] >= _THROTTLE_WINDOW 

1362 ): 

1363 _throttle_times.popleft() 

1364 if len(_throttle_times) < _THROTTLE_MAX: 

1365 _throttle_times.append(now) 

1366 return 

1367 wait = _THROTTLE_WINDOW - (now - _throttle_times[0]) 

1368 time.sleep(max(wait, 0.05)) 

1369 

1370 

1371def _remember_track_count(album_id: str, count: int) -> None: 

1372 if len(_ALBUM_TRACK_COUNTS) >= _ALBUM_TRACK_COUNTS_MAX: 

1373 _ALBUM_TRACK_COUNTS.clear() 

1374 _ALBUM_TRACK_COUNTS[album_id] = count 

1375 

1376 

1377def _rows_or_empty(url: str, **params: Any) -> list[Any]: 

1378 """The ``data`` rows of a Deezer list endpoint, or ``[]`` when it 

1379 fails - for the parts of a Finder answer that are extras.""" 

1380 

1381 try: 

1382 return list(_get_json(url, **params).get('data') or []) 

1383 except ValueError: 

1384 return [] 

1385 

1386 

1387def _map_rows( 

1388 rows: list[Any], mapper: Callable[[dict[str, Any]], Any] 

1389) -> list[dict[str, Any]]: 

1390 mapped_rows: list[dict[str, Any]] = [] 

1391 for row in rows: 

1392 if not isinstance(row, dict): 

1393 continue 

1394 mapped = mapper(row) 

1395 if mapped: 

1396 mapped_rows.append(mapped) 

1397 return mapped_rows 

1398 

1399 

1400def _finder_song(row: dict[str, Any]) -> Optional[dict[str, Any]]: 

1401 """A search/top track row as a downloadable song, plus the Deezer ids 

1402 of its artist and album - what the Finder opens when it's clicked.""" 

1403 

1404 song = _song_from_full_track(row) 

1405 if song is None: 

1406 return None 

1407 artist = row.get('artist') if isinstance(row.get('artist'), dict) else {} 

1408 album = row.get('album') if isinstance(row.get('album'), dict) else {} 

1409 song['deezer_artist_id'] = str(artist.get('id') or '') 

1410 song['deezer_album_id'] = str(album.get('id') or '') 

1411 return song 

1412 

1413 

1414def _finder_artist_row(row: dict[str, Any]) -> Optional[dict[str, Any]]: 

1415 """A search/related artist row: :func:`_chart_artist_release` plus its 

1416 fan and album counts.""" 

1417 

1418 release = _chart_artist_release(row) 

1419 if release is None: 

1420 return None 

1421 release['fans'] = int(row.get('nb_fan') or 0) 

1422 release['album_count'] = int(row.get('nb_album') or 0) 

1423 return release 

1424 

1425 

1426def _finder_album_row( 

1427 row: dict[str, Any], artist_id: str = '' 

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

1429 """An album search row or a row of an artist's albums listing: 

1430 :func:`_artist_release_row` plus the artist's id, the full release 

1431 date, fans and the track count - ``None`` when the row doesn't carry 

1432 one and it isn't known yet (see :func:`album_track_counts`).""" 

1433 

1434 artist = row.get('artist') if isinstance(row.get('artist'), dict) else {} 

1435 release = _artist_release_row(row, str(artist.get('name') or '').strip()) 

1436 if release is None: 

1437 return None 

1438 album_id = release['album_id'] 

1439 count = row.get('nb_tracks') 

1440 if count is not None: 

1441 _remember_track_count(album_id, int(count)) 

1442 else: 

1443 count = _ALBUM_TRACK_COUNTS.get(album_id) 

1444 release.update({ 

1445 'artist_id': str(artist.get('id') or artist_id), 

1446 'release_date': str(row.get('release_date') or '').strip(), 

1447 'track_count': int(count) if count is not None else None, 

1448 'fans': int(row.get('fans') or 0), 

1449 }) 

1450 return release 

1451 

1452 

1453def finder_search( 

1454 query: str, limit: int = 25 

1455) -> dict[str, list[dict[str, Any]]]: 

1456 """``{songs, albums, artists}`` matching *query* on Deezer, each in 

1457 Deezer's own relevance order. 

1458 

1459 Songs are downloadable song rows (see :func:`_finder_song`); albums 

1460 and artists are summaries the Finder opens. Albums and artists are 

1461 extras: their failure leaves them empty, while a failed song search 

1462 raises :class:`ValueError` - the same split the regular search makes. 

1463 """ 

1464 

1465 text = query.strip() 

1466 if not text: 

1467 return {'songs': [], 'albums': [], 'artists': []} 

1468 size = max(1, min(limit, 50)) 

1469 with ThreadPoolExecutor(max_workers=3) as pool: 

1470 songs = pool.submit(_get_json, _FINDER_SEARCH_URL, q=text, limit=size) 

1471 albums = pool.submit( 

1472 _rows_or_empty, f'{_FINDER_SEARCH_URL}/album', q=text, limit=size 

1473 ) 

1474 artists = pool.submit( 

1475 _rows_or_empty, f'{_FINDER_SEARCH_URL}/artist', q=text, limit=size 

1476 ) 

1477 song_rows = list(songs.result().get('data') or []) 

1478 return { 

1479 'songs': _map_rows(song_rows, _finder_song), 

1480 'albums': _map_rows(albums.result(), _finder_album_row), 

1481 'artists': _map_rows(artists.result(), _finder_artist_row), 

1482 } 

1483 

1484 

1485# How many pages of a name search finder_artist_songs reads at most, 100 

1486# rows each - a big catalogue's first few hundred songs, a handful of 

1487# requests. 

1488ARTIST_SONGS_MAX_PAGES = 3 

1489 

1490 

1491def finder_artist_songs(artist_id: str, name: str) -> list[dict[str, Any]]: 

1492 """An artist's songs for the Finder, as :func:`_finder_song` rows in 

1493 Deezer's own relevance order: a plain search for *name*, keeping only 

1494 the rows whose main artist is *artist_id*. 

1495 

1496 Deezer's field search (``artist:"name"``) would be the direct way, but 

1497 for tracks it answers nothing at all today - for any artist, even the 

1498 documented ``artist:"..." track:"..."`` form (verified live). A plain 

1499 search for the name mostly finds that artist anyway, and matching the 

1500 id rather than the name keeps out a namesake, or a song merely called 

1501 that. Reads up to :data:`ARTIST_SONGS_MAX_PAGES` pages, each through 

1502 :func:`_throttle`. Raises :class:`ValueError` when Deezer can't be 

1503 asked or refuses. 

1504 """ 

1505 

1506 wanted = str(artist_id).strip() 

1507 text = name.strip() 

1508 if not wanted or not text: 

1509 return [] 

1510 rows: list[Any] = [] 

1511 params: dict[str, Any] = {'q': text, 'limit': 100} 

1512 url: Optional[str] = _FINDER_SEARCH_URL 

1513 for _ in range(ARTIST_SONGS_MAX_PAGES): 

1514 if not url: 

1515 break 

1516 _throttle() 

1517 page = _get_json(url, **params) 

1518 rows.extend(page.get('data') or []) 

1519 # Deezer's own "next" already carries the query and the offset. 

1520 url, params = page.get('next'), {} 

1521 

1522 def by_artist(row: dict[str, Any]) -> bool: 

1523 artist = ( 

1524 row.get('artist') if isinstance(row.get('artist'), dict) else {} 

1525 ) 

1526 return str(artist.get('id') or '') == wanted 

1527 

1528 return _map_rows( 

1529 [row for row in rows if isinstance(row, dict) and by_artist(row)], 

1530 _finder_song, 

1531 ) 

1532 

1533 

1534def _artist_full_or_none(artist_id: str, lang: str) -> Optional[dict]: 

1535 try: 

1536 return fetch_artist_full(artist_id, lang) 

1537 except ValueError: 

1538 return None 

1539 

1540 

1541def finder_artist(artist_id: str, lang: str = 'en') -> dict[str, Any]: 

1542 """Everything the Finder's first column shows about a Deezer artist: 

1543 photo, fans, album count, bio (as Deezer's HTML, in *lang* - see 

1544 :func:`fetch_artist_full`), social links, related artists and their 

1545 ten most-played tracks. Fetched in parallel. 

1546 

1547 Only the artist itself is required - raises :class:`ValueError` when 

1548 it doesn't resolve; every other part is left empty when it fails. 

1549 """ 

1550 

1551 base = f'https://api.deezer.com/artist/{artist_id}' 

1552 with ThreadPoolExecutor(max_workers=_FINDER_WORKERS) as pool: 

1553 info = pool.submit(_get_json, base) 

1554 related = pool.submit(_rows_or_empty, f'{base}/related', limit=20) 

1555 top = pool.submit(_rows_or_empty, f'{base}/top', limit=10) 

1556 full = pool.submit(_artist_full_or_none, artist_id, lang) 

1557 payload = info.result() 

1558 extra = full.result() or {} 

1559 return { 

1560 'artist_id': str(artist_id), 

1561 'name': str(payload.get('name') or '').strip() or str(artist_id), 

1562 'cover_url': ( 

1563 _cover_from_images(payload, prefix='picture') 

1564 if _has_real_picture(payload) 

1565 else '' 

1566 ), 

1567 'fans': int(payload.get('nb_fan') or 0), 

1568 'album_count': int(payload.get('nb_album') or 0), 

1569 'url': str(payload.get('link') or ''), 

1570 'source': 'deezer', 

1571 'bio_html': str(extra.get('bio_html') or ''), 

1572 'social': extra.get('social') or {}, 

1573 'related': _map_rows(related.result(), _finder_artist_row), 

1574 'top_songs': _map_rows(top.result(), _finder_song), 

1575 } 

1576 

1577 

1578def finder_artist_albums(artist_id: str) -> list[dict[str, Any]]: 

1579 """A Deezer artist's whole discography, most recent first (Deezer's 

1580 own order), as :func:`_finder_album_row` summaries. Track counts are 

1581 only filled in when already known - see :func:`album_track_counts`. 

1582 

1583 Raises :class:`ValueError` when the id doesn't resolve or the 

1584 request fails. 

1585 """ 

1586 

1587 first_page = _get_json( 

1588 f'https://api.deezer.com/artist/{artist_id}/albums', limit=100 

1589 ) 

1590 return _map_rows( 

1591 _paginate_tracks(first_page), 

1592 lambda row: _finder_album_row(row, artist_id=str(artist_id)), 

1593 ) 

1594 

1595 

1596def _album_track_count(album_id: str) -> Optional[int]: 

1597 """One album's track count - remembered, else the ``total`` of a 

1598 one-row page of its tracklist (much lighter than the whole album) - 

1599 or ``None`` when Deezer didn't answer.""" 

1600 

1601 cached = _ALBUM_TRACK_COUNTS.get(album_id) 

1602 if cached is not None: 

1603 return cached 

1604 _throttle() 

1605 try: 

1606 page = _get_json( 

1607 f'https://api.deezer.com/album/{album_id}/tracks', limit=1 

1608 ) 

1609 except ValueError: 

1610 return None 

1611 total = page.get('total') 

1612 if total is None: 

1613 return None 

1614 _remember_track_count(album_id, int(total)) 

1615 return int(total) 

1616 

1617 

1618def album_track_counts(album_ids: list[str]) -> dict[str, int]: 

1619 """``{album_id: track_count}`` for up to :data:`TRACK_COUNTS_MAX_IDS` 

1620 album ids - the ones Deezer answered for; a failed lookup (a rate 

1621 limit, say) is just left out, so the caller can ask again later. 

1622 

1623 Throttled to stay under Deezer's request quota (see 

1624 :func:`_throttle`), so a long list takes a few seconds; the caller 

1625 asks in small batches to show counts as they arrive. 

1626 """ 

1627 

1628 ids = list( 

1629 dict.fromkeys( 

1630 album_id 

1631 for album_id in (str(raw).strip() for raw in album_ids) 

1632 if album_id.isdigit() 

1633 ) 

1634 )[:TRACK_COUNTS_MAX_IDS] 

1635 if not ids: 

1636 return {} 

1637 # More workers than elsewhere: these are tiny requests, and _throttle 

1638 # keeps the overall rate in check anyway. 

1639 with ThreadPoolExecutor(max_workers=_FINDER_WORKERS * 2) as pool: 

1640 counts = list(pool.map(_album_track_count, ids)) 

1641 return { 

1642 album_id: count 

1643 for album_id, count in zip(ids, counts) 

1644 if count is not None 

1645 } 

1646 

1647 

1648def finder_album(album_id: str) -> dict[str, Any]: 

1649 """A Deezer album with every detail its own resource carries - label, 

1650 genres, UPC, length, fans, contributors - and its tracklist as 

1651 downloadable songs (see :func:`album_from_id`). 

1652 

1653 Raises :class:`ValueError` when the id doesn't resolve or the 

1654 request fails. 

1655 """ 

1656 

1657 payload = _get_json(f'https://api.deezer.com/album/{album_id}') 

1658 name = str(payload.get('title') or '').strip() or str(album_id) 

1659 artist = ( 

1660 payload.get('artist') 

1661 if isinstance(payload.get('artist'), dict) 

1662 else {} 

1663 ) 

1664 cover = _cover_from_images(payload) 

1665 songs = _album_songs(payload) 

1666 for song in songs: 

1667 song['cover_url'] = song['cover_url'] or cover 

1668 song['album_name'] = song['album_name'] or name 

1669 count = int(payload.get('nb_tracks') or len(songs)) 

1670 _remember_track_count(str(album_id), count) 

1671 release_date = str(payload.get('release_date') or '').strip() 

1672 genres = [ 

1673 str(genre['name']).strip() 

1674 for genre in (payload.get('genres') or {}).get('data') or [] 

1675 if isinstance(genre, dict) and genre.get('name') 

1676 ] 

1677 contributors = [ 

1678 { 

1679 'artist_id': str(person.get('id') or ''), 

1680 'name': str(person['name']).strip(), 

1681 'role': str(person.get('role') or '').strip(), 

1682 } 

1683 for person in payload.get('contributors') or [] 

1684 if isinstance(person, dict) and person.get('name') 

1685 ] 

1686 return { 

1687 'album_id': str(album_id), 

1688 'name': name, 

1689 'artist': str(artist.get('name') or '').strip(), 

1690 'artist_id': str(artist.get('id') or ''), 

1691 'cover_url': cover, 

1692 'release_date': release_date, 

1693 'year': _year_from_release_date(release_date), 

1694 'label': str(payload.get('label') or '').strip(), 

1695 'genres': genres, 

1696 'duration': int(payload.get('duration') or 0), 

1697 'track_count': count, 

1698 'fans': int(payload.get('fans') or 0), 

1699 'release_type': _release_type_label(payload.get('record_type')), 

1700 'explicit': bool(payload.get('explicit_lyrics')), 

1701 'upc': str(payload.get('upc') or '').strip(), 

1702 'url': str(payload.get('link') or ''), 

1703 'contributors': contributors, 

1704 'source': 'deezer', 

1705 'tracks': songs, 

1706 } 

1707 

1708 

1709# ── Discover: albums, editorial playlists and matching Spotify albums ── 

1710# 

1711# Discover (see downtify.discover) builds its album and playlist shelves 

1712# from Deezer first, then adds what Spotify picks on top, matched back to 

1713# Deezer. Everything here goes through _throttle: a cold Discover page 

1714# asks for a few dozen of these, next to its related-artist lookups. 

1715 

1716# Deezer's own editors publish a "100% <artist>" playlist - the very best 

1717# of one artist, the counterpart of Spotify's "This Is <artist>" - under 

1718# this account name (verified live for a range of artists). 

1719EDITORIAL_OWNER = 'Deezer Artist Editor' 

1720_EDITORIAL_PREFIX = '100%' 

1721 

1722 

1723def artist_discography(artist_id: str) -> list[dict[str, Any]]: 

1724 """Every release of a Deezer artist, as :func:`finder_artist_albums` 

1725 rows (with ``fans`` and ``release_type``), each page throttled. 

1726 

1727 Raises :class:`ValueError` when Deezer can't be asked or refuses. 

1728 """ 

1729 

1730 _throttle() 

1731 page = _get_json( 

1732 f'https://api.deezer.com/artist/{artist_id}/albums', limit=100 

1733 ) 

1734 rows = list(page.get('data') or []) 

1735 while page.get('next'): 

1736 _throttle() 

1737 page = _get_json(page['next']) 

1738 rows.extend(page.get('data') or []) 

1739 return _map_rows( 

1740 rows, lambda row: _finder_album_row(row, artist_id=str(artist_id)) 

1741 ) 

1742 

1743 

1744def editorial_playlist(name: str) -> Optional[dict[str, Any]]: 

1745 """Deezer's editorial "100% <name>" playlist, or ``None`` when its 

1746 editors have none for that artist. 

1747 

1748 ``{playlist_id, name, owner, cover_url, url}``. Only a playlist by 

1749 :data:`EDITORIAL_OWNER` whose title is exactly "100%" and the artist's 

1750 name (compared the way a file name is, see 

1751 :func:`~downtify.file_naming.file_name_key`) counts - a fan's 

1752 "100% Radiohead & friends" doesn't. Raises :class:`ValueError` when 

1753 Deezer can't be asked or refuses, so a failure isn't taken for "none". 

1754 """ 

1755 

1756 wanted = file_name_key(name) 

1757 if not wanted: 

1758 return None 

1759 _throttle() 

1760 rows = ( 

1761 _get_json( 

1762 f'{_FINDER_SEARCH_URL}/playlist', 

1763 q=f'{_EDITORIAL_PREFIX} {name}', 

1764 limit=10, 

1765 ).get('data') 

1766 or [] 

1767 ) 

1768 for row in rows: 

1769 if not isinstance(row, dict): 

1770 continue 

1771 user = row.get('user') if isinstance(row.get('user'), dict) else {} 

1772 if str(user.get('name') or '') != EDITORIAL_OWNER: 

1773 continue 

1774 title = str(row.get('title') or '').strip() 

1775 if not title.startswith(_EDITORIAL_PREFIX): 

1776 continue 

1777 if file_name_key(title[len(_EDITORIAL_PREFIX) :]) != wanted: 

1778 continue 

1779 playlist_id = row.get('id') 

1780 if not playlist_id: 

1781 continue 

1782 return { 

1783 'playlist_id': str(playlist_id), 

1784 'name': title, 

1785 'owner': EDITORIAL_OWNER, 

1786 'cover_url': _cover_from_images(row, prefix='picture'), 

1787 'url': str( 

1788 row.get('link') 

1789 or f'https://www.deezer.com/playlist/{playlist_id}' 

1790 ), 

1791 } 

1792 return None 

1793 

1794 

1795def search_albums_by(artist: str, title: str) -> list[dict[str, Any]]: 

1796 """Deezer albums that may be *artist*'s *title*, as 

1797 :func:`_finder_album_row` rows, best match first - for matching an 

1798 album found elsewhere (Spotify) back to Deezer. 

1799 

1800 Deezer's field search (``artist:"..." album:"..."``) first; when none 

1801 of its rows is by *artist* - it's strict about punctuation, and loose 

1802 enough to answer with other artists' albums instead of nothing (seen 

1803 live for Blur's "Blur") - a plain search for both. Deciding which row 

1804 really is the album is the caller's job. Raises :class:`ValueError` 

1805 when Deezer can't be asked or refuses. 

1806 """ 

1807 

1808 wanted = file_name_key(artist) 

1809 queries = [f'artist:"{artist}" album:"{title}"', f'{artist} {title}'] 

1810 found: list[dict[str, Any]] = [] 

1811 for query in queries: 

1812 _throttle() 

1813 rows = ( 

1814 _get_json(f'{_FINDER_SEARCH_URL}/album', q=query, limit=10).get( 

1815 'data' 

1816 ) 

1817 or [] 

1818 ) 

1819 found = _map_rows(rows, _finder_album_row) 

1820 if any(file_name_key(row['artist']) == wanted for row in found): 

1821 break 

1822 return found