Coverage for downtify/artist_photo_proxy.py: 95%
102 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"""DISPLAY-ONLY proxy for photos of artists that have no photo saved.
3This module exists so the UI can show a face where there is no saved photo
4- next to a related artist the user does not own, in the Library's artists
5grid, and as the round photo on an artist's own page, for an artist
6without a picked photo (Deezer's API sends no CORS headers, so the
7browser cannot ask for it directly). It is a pass-through, nothing more:
9* The image bytes are returned to the caller and forgotten. Nothing is
10 written to disk, ever - not here, not via
11 :func:`downtify.artist_profile.save_image` or
12 :func:`downtify.artist_profile.fetch_and_save_image` (do not import
13 them). Only a name -> Deezer CDN URL mapping is kept, in memory, for
14 three hours.
15* It is NOT a photo/banner source. A photo picked for an artist in the
16 library goes through the artist-art picker and is saved as a sidecar
17 file, as before. Do not call :func:`fetch_proxied_photo` from the
18 download pipeline, ``ensure_profile`` or anything else that persists.
19* The browser is told to cache the response for three hours
20 (:data:`BROWSER_CACHE_SECONDS`), which is the only cache that holds
21 the pixels.
22* Only a real answer is ever cached - the photo, or Deezer saying this
23 artist has none. Anything that goes wrong (Deezer unreachable, over its
24 limit of 50 requests per 5 seconds, a refused or broken download) raises
25 :class:`PhotoUnavailable` instead, which is neither remembered here nor
26 cached by the browser: the next request simply tries again.
27* A caller that already holds the artist's picture URL skips the search
28 by name with :func:`fetch_photo_at`: Discover's suggestions and the
29 Finder bring a Deezer one, the search page a YouTube Music one (relayed
30 from here, Google's image CDN doesn't throttle the browser's burst of
31 hotlinked photos), and a pasted artist link Spotify's, Deezer's or
32 YouTube Music's. It only ever downloads from those image CDNs (see
33 :func:`_is_relay_url`) - this is not a way to fetch arbitrary URLs.
34"""
36from __future__ import annotations
38import re
39import threading
40import time
41from typing import Optional
43import httpx
44from loguru import logger
46from . import deezer
48BROWSER_CACHE_SECONDS = 3 * 3600
49_URL_TTL = 3 * 3600.0
50_MAX_ENTRIES = 1000
51_MAX_CONCURRENT = 4
52_MAX_BYTES = 2 * 1024 * 1024
53_TIMEOUT = 10
54_CDN_SUFFIX = 'dzcdn.net'
55# YouTube Music's artist photos - exact hosts, not a whole domain.
56_YTM_IMAGE_HOSTS = frozenset({
57 'lh3.googleusercontent.com',
58 'yt3.googleusercontent.com',
59 'yt3.ggpht.com',
60})
61# Spotify's artist photos: i.scdn.co, or image-cdn-<region>.spotifycdn.com.
62_SPOTIFY_IMAGE_HOST = re.compile(
63 r'^(?:i\.scdn\.co|image-cdn-[a-z0-9]+\.spotifycdn\.com)$'
64)
66# name (lower-cased) -> (cdn url or None for "no match", monotonic stamp)
67_url_cache: dict[str, tuple[Optional[str], float]] = {}
68_cache_lock = threading.Lock()
69_slots = threading.BoundedSemaphore(_MAX_CONCURRENT)
70_inflight: dict[str, threading.Lock] = {}
73class PhotoUnavailable(Exception):
74 """The photo couldn't be looked up or downloaded right now.
76 Not "this artist has no photo" (that is a ``None`` answer): a failure,
77 so nothing about it is remembered or cached anywhere.
78 """
81def _is_cdn_url(url: str) -> bool:
82 try:
83 parsed = httpx.URL(url)
84 except Exception:
85 return False
86 host = parsed.host or ''
87 return parsed.scheme == 'https' and (
88 host == _CDN_SUFFIX or host.endswith(f'.{_CDN_SUFFIX}')
89 )
92def _is_relay_url(url: str) -> bool:
93 """Whether :func:`fetch_photo_at` may download *url*: an https image
94 on Deezer's CDN, one of YouTube Music's image hosts or Spotify's."""
96 if _is_cdn_url(url):
97 return True
98 try:
99 parsed = httpx.URL(url)
100 except Exception:
101 return False
102 host = parsed.host or ''
103 return parsed.scheme == 'https' and (
104 host in _YTM_IMAGE_HOSTS or bool(_SPOTIFY_IMAGE_HOST.match(host))
105 )
108def _cached_url(key: str) -> tuple[bool, Optional[str]]:
109 with _cache_lock:
110 entry = _url_cache.get(key)
111 if entry is None:
112 return False, None
113 url, stamp = entry
114 if time.monotonic() - stamp > _URL_TTL:
115 del _url_cache[key]
116 return False, None
117 return True, url
120def _remember_url(key: str, url: Optional[str]) -> None:
121 with _cache_lock:
122 if len(_url_cache) >= _MAX_ENTRIES and key not in _url_cache:
123 # Oldest first; dicts keep insertion order.
124 del _url_cache[next(iter(_url_cache))]
125 _url_cache[key] = (url, time.monotonic())
128def _lookup_url(name: str) -> Optional[str]:
129 """The Deezer CDN URL for *name*, or ``None`` when Deezer says the
130 artist has no photo. Both are cached, and deduped so a burst of
131 identical requests makes one search call; a failed lookup is neither
132 (:class:`PhotoUnavailable`)."""
134 key = name.strip().lower()
135 hit, url = _cached_url(key)
136 if hit:
137 return url
138 with _cache_lock:
139 gate = _inflight.setdefault(key, threading.Lock())
140 try:
141 with gate:
142 hit, url = _cached_url(key)
143 if hit:
144 return url
145 try:
146 with _slots:
147 url = deezer.exact_artist_picture(name)
148 except ValueError as exc:
149 # Deezer unreachable or rate limiting us - not "no photo",
150 # so it is not remembered: the next request tries again.
151 raise PhotoUnavailable('Deezer did not answer') from exc
152 if url is not None and not _is_cdn_url(url):
153 # Not something to download - an oddity, not an answer.
154 raise PhotoUnavailable('Deezer sent an unexpected URL')
155 _remember_url(key, url)
156 return url
157 finally:
158 with _cache_lock:
159 _inflight.pop(key, None)
162def fetch_proxied_photo(name: str) -> Optional[tuple[bytes, str]]:
163 """``(image bytes, content type)`` for *name*'s Deezer photo, or
164 ``None`` when Deezer has no exact match for the name or only its
165 placeholder - the one answer that is a miss.
167 Raises :class:`PhotoUnavailable` when anything fails: the lookup, the
168 download, or what came back not being a usable image. Display only -
169 see the module docstring. The bytes are not kept.
170 """
172 if not name.strip():
173 return None
174 url = _lookup_url(name)
175 if url is None:
176 return None
177 return _download(url)
180def fetch_photo_at(url: str) -> tuple[bytes, str]:
181 """``(image bytes, content type)`` of the photo at *url* - for a caller
182 that already has the artist's picture URL (Deezer's, YouTube Music's or
183 Spotify's), so no search by name is needed.
185 Raises :class:`ValueError` when *url* isn't on one of those image CDNs
186 - it is never fetched - and :class:`PhotoUnavailable` when the download
187 fails or isn't a usable image, as :func:`fetch_proxied_photo` does.
188 Display only - see the module docstring. The bytes are not kept.
189 """
191 if not _is_relay_url(url):
192 raise ValueError('Not a Deezer, YouTube Music or Spotify image URL')
193 return _download(url)
196def _download(url: str) -> tuple[bytes, str]:
197 """The image at an allowed CDN *url* (see :func:`_is_relay_url`):
198 ``(bytes, content type)``, or :class:`PhotoUnavailable`."""
200 try:
201 with _slots:
202 resp = httpx.get(url, timeout=_TIMEOUT)
203 resp.raise_for_status()
204 except Exception as exc:
205 logger.opt(exception=True).debug('Artist photo proxy fetch failed')
206 raise PhotoUnavailable('Could not download the photo') from exc
207 data = resp.content
208 if not data or len(data) > _MAX_BYTES:
209 raise PhotoUnavailable('The photo is empty or too large')
210 content_type = resp.headers.get('content-type', 'image/jpeg')
211 if not content_type.startswith('image/'):
212 raise PhotoUnavailable('The photo is not an image')
213 return data, content_type.split(';')[0].strip()