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

1"""DISPLAY-ONLY proxy for photos of artists that have no photo saved. 

2 

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: 

8 

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

35 

36from __future__ import annotations 

37 

38import re 

39import threading 

40import time 

41from typing import Optional 

42 

43import httpx 

44from loguru import logger 

45 

46from . import deezer 

47 

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) 

65 

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] = {} 

71 

72 

73class PhotoUnavailable(Exception): 

74 """The photo couldn't be looked up or downloaded right now. 

75 

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

79 

80 

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 ) 

90 

91 

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

95 

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 ) 

106 

107 

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 

118 

119 

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

126 

127 

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

133 

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) 

160 

161 

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. 

166 

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

171 

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) 

178 

179 

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. 

184 

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

190 

191 if not _is_relay_url(url): 

192 raise ValueError('Not a Deezer, YouTube Music or Spotify image URL') 

193 return _download(url) 

194 

195 

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

199 

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