Coverage for downtify/deezer.py: 93%
675 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""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).
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.
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"""
30from __future__ import annotations
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
40import httpx
41from loguru import logger
43from . import providers
44from .album_artist import album_artist_fields
45from .file_naming import file_name_key, title_key
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
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}
117fragment ArtistMasthead on Artist {
118 ...ArtistBase
119 ...ArtistBio
120 ...ArtistSocial
121 onTour
122 status
123 __typename
124}
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}
141fragment PictureSmall on Picture {
142 id
143 small: urls(pictureRequest: {height: 100, width: 100})
144 explicitStatus
145 __typename
146}
148fragment PictureMedium on Picture {
149 id
150 medium: urls(pictureRequest: {width: 264, height: 264})
151 explicitStatus
152 __typename
153}
155fragment PictureLarge on Picture {
156 id
157 large: urls(pictureRequest: {width: 500, height: 500})
158 explicitStatus
159 __typename
160}
162fragment ArtistBio on Artist {
163 bio {
164 full
165 __typename
166 }
167 __typename
168}
170fragment ArtistSocial on Artist {
171 social {
172 twitter
173 facebook
174 website
175 instagram
176 __typename
177 }
178 __typename
179}"""
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'
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`)."""
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
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``.
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 """
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))
231def _search_rows(text: str, limit: int) -> list[Any]:
232 """The rows of Deezer's artist search for *text*.
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 """
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 []
260def search_artist(query: str, limit: int = 10) -> list[dict[str, Any]]:
261 """Artist photo candidates for *query*, largest Deezer offers each.
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 """
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 []
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
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`).
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`).
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 """
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
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."""
331 try:
332 return lookup_artist_id(name)
333 except ValueError:
334 return None
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``.
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.
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 """
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
362def _picture(row: dict[str, Any]) -> str:
363 """A row's largest real photo, or ``""`` for Deezer's placeholder."""
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 )
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.
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.
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 """
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')
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
423def _preview_link(url: Any) -> str:
424 """*url* when it's an https link to Deezer's clip CDN, else ``""``."""
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 ''
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 ``""``.
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.
449 Raises :class:`ValueError` when Deezer didn't really answer (see
450 :func:`_search_rows`), so ``""`` always means "no clip found".
451 """
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')
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]
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 ``""``.
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 """
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 ''
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.
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.
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 """
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')
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
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 }
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`.
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 """
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
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.
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 """
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 }
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``.
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 """
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 }
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``.
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 """
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 }
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``.
757 Same read-only reasoning as :func:`_chart_album_release`: Downtify has
758 no way to resolve a Deezer playlist into a tracklist.
759 """
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 }
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
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}``.
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`).
801 Raises :class:`ValueError` when Deezer can't be reached or refuses
802 (see :func:`_chart_payload`).
803 """
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 }
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.
825_DEEZER_URL_RE = re.compile(
826 r'deezer\.com/(?:[a-z]{2}/)?(track|album|playlist|artist)/(\d+)',
827 re.IGNORECASE,
828)
831def parse_deezer_url(url: str) -> Optional[tuple[str, str]]:
832 """``(kind, id)`` for a Deezer track/album/playlist/artist URL, or
833 ``None``.
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 """
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)
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)."""
852 def __init__(self, message: str, code: int = 0) -> None:
853 super().__init__(message)
854 self.code = code
857def _get_json(url: str, **params: Any) -> dict[str, Any]:
858 """A Deezer REST GET, or raise :class:`ValueError`.
860 A refusal raises :class:`DeezerRefused` (a ``ValueError``).
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 """
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
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`."""
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
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))
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.
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 """
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
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 ''
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.
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 """
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
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."""
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
1022def track_from_id(track_id: str) -> dict[str, Any]:
1023 """A single Deezer track, as a downloadable Downtify song.
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 """
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
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")."""
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 )
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."""
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)
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."""
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
1087def album_from_id(album_id: str) -> list[dict[str, Any]]:
1088 """Every track of a Deezer album/single/EP, in tracklist order.
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.
1096 Raises :class:`ValueError` when the id doesn't resolve or the
1097 request fails.
1098 """
1100 return _album_songs(_get_json(f'https://api.deezer.com/album/{album_id}'))
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).
1112 Raises :class:`ValueError` when the id doesn't resolve or the
1113 request fails.
1114 """
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 )
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`."""
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
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`.
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).
1170 Raises :class:`ValueError` when the id doesn't resolve or the
1171 request fails.
1172 """
1174 name, _cover, songs = playlist_page_from_id(playlist_id)
1175 return name, songs
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."""
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
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`.
1201 A playlist's own image fields are named ``picture_*`` (like an
1202 artist's), not ``cover_*`` (like a track/album's).
1204 Raises :class:`ValueError` when the id doesn't resolve or the
1205 request fails.
1206 """
1208 payload = _get_json(f'https://api.deezer.com/playlist/{playlist_id}')
1209 return _cover_from_images(payload, prefix='picture')
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}
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.
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 """
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 }
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."""
1257 text = str(record_type or '').strip().lower()
1258 return _RECORD_TYPE_LABELS.get(text, text.title() or 'Album')
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).
1268 Raises :class:`ValueError` when the id doesn't resolve or the
1269 request fails.
1270 """
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
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
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).
1302 Raises :class:`ValueError` when the id doesn't resolve or the
1303 request fails.
1304 """
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
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.
1331_FINDER_SEARCH_URL = 'https://api.deezer.com/search'
1332_FINDER_WORKERS = 4
1334# How many album ids one album_track_counts() call looks up at most.
1335TRACK_COUNTS_MAX_IDS = 50
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()
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
1352def _throttle() -> None:
1353 """Wait until another request fits under :data:`_THROTTLE_MAX` per
1354 :data:`_THROTTLE_WINDOW` seconds, then claim it."""
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))
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
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."""
1381 try:
1382 return list(_get_json(url, **params).get('data') or [])
1383 except ValueError:
1384 return []
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
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."""
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
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."""
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
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`)."""
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
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.
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 """
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 }
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
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*.
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 """
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'), {}
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
1528 return _map_rows(
1529 [row for row in rows if isinstance(row, dict) and by_artist(row)],
1530 _finder_song,
1531 )
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
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.
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 """
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 }
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`.
1583 Raises :class:`ValueError` when the id doesn't resolve or the
1584 request fails.
1585 """
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 )
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."""
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)
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.
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 """
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 }
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`).
1653 Raises :class:`ValueError` when the id doesn't resolve or the
1654 request fails.
1655 """
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 }
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.
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%'
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.
1727 Raises :class:`ValueError` when Deezer can't be asked or refuses.
1728 """
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 )
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.
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 """
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
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.
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 """
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