Coverage for downtify/itunes.py: 78%

227 statements  

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

1"""Fetch genre metadata from the iTunes Search API. 

2 

3The public ``itunes.apple.com/search`` endpoint returns 

4``primaryGenreName`` for every song result — no API key or 

5authentication required. This module provides a single entry-point, 

6:func:`fetch_genre`, that looks up a track and returns the genre 

7string (or ``""`` when nothing matches). 

8""" 

9 

10from __future__ import annotations 

11 

12import re 

13import time 

14import unicodedata 

15from threading import Lock 

16from typing import Any, Optional 

17from urllib.parse import quote_plus 

18 

19import httpx 

20from loguru import logger 

21 

22_ITUNES_SEARCH_URL = 'https://itunes.apple.com/search' 

23_TIMEOUT = 10 # seconds 

24_MIN_INTERVAL = 0.35 # seconds between API calls (rate-limit courtesy) 

25# A rate-limited request (HTTP 429, or the 403 Apple sometimes answers 

26# with instead) is tried again after these waits, in seconds. 

27_RETRY_STATUSES = frozenset({403, 429}) 

28_RETRY_WAITS = (2.0, 5.0) 

29 

30# ── In-memory cache ──────────────────────────────────────────────── 

31# key = "normalized_artist|normalized_album" → genre string. 

32# Avoids repeated API calls when downloading a full album (all tracks 

33# share the same album and therefore the same genre). 

34_genre_cache: dict[str, str] = {} 

35_cache_lock = Lock() 

36 

37# Same idea for cover art, which a library upgrade asks about once per 

38# track: every track of an album shares one artwork URL. 

39_artwork_cache: dict[str, str] = {} 

40 

41# Timestamp of the last outgoing request – used for rate pacing. 

42_last_request_time: float = 0.0 

43_rate_lock = Lock() 

44 

45 

46# ── Text normalisation ──────────────────────────────────────────── 

47def _normalise(text: str) -> str: 

48 """Lowercase, strip accents, collapse whitespace.""" 

49 if not text: 

50 return '' 

51 # Decompose → strip combining marks → recompose 

52 nfkd = unicodedata.normalize('NFKD', text) 

53 stripped = ''.join(ch for ch in nfkd if unicodedata.category(ch) != 'Mn') 

54 folded = stripped.casefold() 

55 # Remove common noise: feat., ft., parenthetical extras 

56 folded = re.sub(r'\s*\(.*?\)', '', folded) 

57 folded = re.sub(r'\s*\[.*?\]', '', folded) 

58 folded = re.sub(r'\b(feat\.?|ft\.?)\b.*', '', folded) 

59 return re.sub(r'\s+', ' ', folded).strip() 

60 

61 

62def _names_match(a: str, b: str) -> bool: 

63 """Fuzzy comparison after normalisation.""" 

64 na, nb = _normalise(a), _normalise(b) 

65 if not na or not nb: 

66 return False 

67 if na == nb: 

68 return True 

69 # One contains the other (handles "The Night Owls" vs 

70 # "The Night Owls & …" or "Do I Still Recall?" vs 

71 # "Do I Still Recall? - Single Version"). 

72 return na in nb or nb in na 

73 

74 

75# ── iTunes API call ─────────────────────────────────────────────── 

76def _rate_wait() -> None: 

77 """Block until at least ``_MIN_INTERVAL`` seconds have elapsed 

78 since the last request.""" 

79 global _last_request_time 

80 with _rate_lock: 

81 now = time.monotonic() 

82 wait = _MIN_INTERVAL - (now - _last_request_time) 

83 if wait > 0: 

84 time.sleep(wait) 

85 _last_request_time = time.monotonic() 

86 

87 

88def _search_itunes( 

89 query: str, limit: int = 5, *, entity: str = 'song', country: str = '' 

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

91 """Call the iTunes Search API and return the ``results`` list. 

92 

93 *country* picks the store (two letters; Apple's default, ``US``, 

94 when empty) - its prices, currency and links. 

95 """ 

96 return _search_or_none(query, limit, entity=entity, country=country) or [] 

97 

98 

99def _search_or_none( 

100 query: str, limit: int = 5, *, entity: str = 'song', country: str = '' 

101) -> Optional[list[dict[str, Any]]]: 

102 """:func:`_search_itunes`, but ``None`` when the request failed 

103 (rate limit, network) rather than found nothing.""" 

104 _rate_wait() 

105 params = f'term={quote_plus(query)}&entity={entity}&limit={limit}' 

106 if country: 

107 params += f'&country={country}' 

108 url = f'{_ITUNES_SEARCH_URL}?{params}' 

109 logger.debug('iTunes lookup: {}', url) 

110 data = None 

111 for attempt in range(1 + len(_RETRY_WAITS)): 

112 try: 

113 resp = httpx.get(url, timeout=_TIMEOUT) 

114 resp.raise_for_status() 

115 data = resp.json() 

116 break 

117 except Exception as exc: 

118 status = getattr(getattr(exc, 'response', None), 'status_code', 0) 

119 if status in _RETRY_STATUSES and attempt < len(_RETRY_WAITS): 

120 # Apple's limit is per minute: a short wait usually clears it. 

121 time.sleep(_RETRY_WAITS[attempt]) 

122 continue 

123 logger.opt(exception=True).debug('iTunes Search API failed') 

124 return None 

125 if not isinstance(data, dict): 

126 return None 

127 results = data.get('results') or [] 

128 logger.debug( 

129 'iTunes Search returned {} result(s) for q={!r}', 

130 len(results), 

131 query[:100], 

132 ) 

133 return results 

134 

135 

136# ── Best-match selection ────────────────────────────────────────── 

137def _pick_best( 

138 results: list[dict[str, Any]], 

139 artist: str, 

140 title: str, 

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

142 """Return the result whose artist + track name best match.""" 

143 for r in results: 

144 if r.get('wrapperType') != 'track': 

145 continue 

146 if r.get('kind') != 'song': 

147 continue 

148 r_artist = r.get('artistName', '') 

149 r_title = r.get('trackName', '') 

150 if _names_match(r_artist, artist) and _names_match(r_title, title): 

151 return r 

152 # Fallback: accept any result whose title matches (artist may 

153 # differ due to "feat." / collaboration discrepancies). 

154 for r in results: 

155 if r.get('wrapperType') != 'track' or r.get('kind') != 'song': 

156 continue 

157 if _names_match(r.get('trackName', ''), title): 

158 return r 

159 return None 

160 

161 

162# ── Public API ──────────────────────────────────────────────────── 

163def fetch_genre(song: dict[str, Any]) -> str: 

164 """Return the genre string for *song*, or ``""`` if unavailable. 

165 

166 ``song`` is the standard Downtify track dict with at least 

167 ``name``, ``artists`` (list[str]) and optionally ``album_name``. 

168 """ 

169 

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

171 artist = artists[0] if artists else (song.get('artist') or '') 

172 title = song.get('name', '') 

173 album = song.get('album_name', '') 

174 

175 if not artist and not title: 

176 return '' 

177 

178 # ── Check album-level cache first ───────────────────────────── 

179 cache_key = f'{_normalise(artist)}|{_normalise(album)}' if album else '' 

180 if cache_key: 

181 with _cache_lock: 

182 cached = _genre_cache.get(cache_key) 

183 if cached is not None: 

184 logger.debug( 

185 'iTunes genre cache hit: {} → {!r}', cache_key, cached 

186 ) 

187 return cached 

188 

189 # ── Search iTunes ───────────────────────────────────────────── 

190 query = f'{artist} {title}'.strip() 

191 results = _search_itunes(query, limit=5) 

192 match = _pick_best(results, artist, title) 

193 

194 if match is None and album: 

195 # Retry with album name in query for disambiguation. 

196 query_alt = f'{artist} {title} {album}'.strip() 

197 results_alt = _search_itunes(query_alt, limit=5) 

198 match = _pick_best(results_alt, artist, title) 

199 

200 genre = '' 

201 if match: 

202 genre = (match.get('primaryGenreName') or '').strip() 

203 logger.info( 

204 'iTunes genre resolved: {!r} by {!r} → {!r}', 

205 title, 

206 artist, 

207 genre, 

208 ) 

209 else: 

210 logger.info('iTunes genre: no match for {!r} by {!r}', title, artist) 

211 

212 # ── Populate album cache ────────────────────────────────────── 

213 if cache_key and genre: 

214 with _cache_lock: 

215 _genre_cache[cache_key] = genre 

216 elif cache_key: 

217 # Negative cache: avoid retrying the same album repeatedly. 

218 with _cache_lock: 

219 _genre_cache.setdefault(cache_key, '') 

220 

221 return genre 

222 

223 

224# ── Cover art ───────────────────────────────────────────────────── 

225#: Every artwork URL iTunes returns ends in ``<size>x<size>bb.<ext>``; 

226#: asking for a larger size returns a genuinely larger image, up to the 

227#: original master (commonly 1400px, sometimes 3000px). 

228_ARTWORK_SIZE_SUFFIX = re.compile(r'/\d+x\d+bb\.(jpg|png)$') 

229 

230 

231def artwork_url_at(url: str, size: int) -> str: 

232 """Rewrite an iTunes artwork URL to ask for a ``size``-pixel square.""" 

233 

234 if not url: 

235 return '' 

236 return _ARTWORK_SIZE_SUFFIX.sub( 

237 lambda m: f'/{size}x{size}bb.{m.group(1)}', url 

238 ) 

239 

240 

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

242 """Search the iTunes podcast directory for *query*. 

243 

244 Keyless, like the song search above. Each result carries a 

245 ``feedUrl`` — the show's public RSS feed — when one is on file; 

246 Spotify-exclusive shows and other feed-less listings come back 

247 without it, which callers must treat as "can't be downloaded" 

248 rather than retrying or guessing a feed. 

249 """ 

250 

251 if not query.strip(): 

252 return [] 

253 _rate_wait() 

254 params = f'term={quote_plus(query)}&entity=podcast&limit={max(1, limit)}' 

255 url = f'{_ITUNES_SEARCH_URL}?{params}' 

256 try: 

257 resp = httpx.get(url, timeout=_TIMEOUT) 

258 resp.raise_for_status() 

259 results = resp.json().get('results') or [] 

260 except Exception: 

261 logger.opt(exception=True).debug('iTunes podcast search failed') 

262 return [] 

263 return [r for r in results if r.get('feedUrl')] 

264 

265 

266def resolve_podcast_feed(show_name: str) -> Optional[dict[str, Any]]: 

267 """The best iTunes match for a show name, or ``None``. 

268 

269 Used to turn a Spotify show/episode link — which only ever gives a 

270 name, never a feed — into an RSS feed URL. Matching is the same 

271 "does the name line up" heuristic as songs; a podcast can't be 

272 disambiguated by album the way a song can, so a false-positive 

273 match here means the wrong show's episodes. 

274 """ 

275 

276 name = (show_name or '').strip() 

277 if not name: 

278 return None 

279 for r in search_podcasts(name, limit=10): 

280 if _names_match(r.get('collectionName', ''), name): 

281 return { 

282 'name': r.get('collectionName', name), 

283 'author': r.get('artistName', ''), 

284 'feed_url': r.get('feedUrl', ''), 

285 'artwork_url': r.get('artworkUrl600', ''), 

286 } 

287 logger.info('iTunes podcast: no feed match for {!r}', name) 

288 return None 

289 

290 

291def fetch_artwork_url(song: dict[str, Any], size: int = 1200) -> str: 

292 """Return an iTunes cover URL for *song* at *size* px, or ``""``. 

293 

294 Same matching as :func:`fetch_genre`: artist and title must line up, 

295 with a title-only fallback for differing "feat." credits. 

296 """ 

297 

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

299 artist = artists[0] if artists else (song.get('artist') or '') 

300 title = song.get('name', '') or song.get('title', '') 

301 album = song.get('album_name', '') or song.get('album', '') 

302 

303 if not title: 

304 return '' 

305 

306 cache_key = f'{_normalise(artist)}|{_normalise(album)}' if album else '' 

307 if cache_key: 

308 with _cache_lock: 

309 cached = _artwork_cache.get(cache_key) 

310 if cached is not None: 

311 return artwork_url_at(cached, size) if cached else '' 

312 

313 query = f'{artist} {title}'.strip() 

314 rows = _search_or_none(query, limit=5) 

315 failed = rows is None 

316 match = _pick_best(rows or [], artist, title) 

317 if match is None and album: 

318 rows = _search_or_none(f'{artist} {title} {album}'.strip(), limit=5) 

319 failed = failed or rows is None 

320 match = _pick_best(rows or [], artist, title) 

321 

322 base = str((match or {}).get('artworkUrl100') or '').strip() 

323 # A failed request (rate limit, network) isn't "iTunes has no cover": 

324 # remembering it would leave the whole album without iTunes art. 

325 if cache_key and (base or not failed): 

326 with _cache_lock: 

327 _artwork_cache.setdefault(cache_key, base) 

328 if not base: 

329 logger.debug( 

330 'iTunes artwork: no match for {!r} by {!r}', title, artist 

331 ) 

332 return '' 

333 return artwork_url_at(base, size) 

334 

335 

336# ── Store links ─────────────────────────────────────────────────── 

337#: What :func:`store_match` asks iTunes for, per kind of item. 

338_STORE_ENTITIES = {'track': 'song', 'album': 'album', 'artist': 'musicArtist'} 

339#: Answers kept, negative ones included (the same song is asked about by 

340#: every page that shows it); cleared whole once this many pile up. 

341_STORE_CACHE_MAX = 2000 

342_store_cache: dict[str, Optional[dict[str, Any]]] = {} 

343 

344 

345def _store_item( 

346 kind: str, row: dict[str, Any], artist: str, title: str, album: str 

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

348 """*row* as ``{url, price, currency}`` when it is the item asked for: 

349 the artist and the title (album, for an album) must both line up - 

350 a buy link to someone else's cover is worse than none.""" 

351 

352 if not _names_match(str(row.get('artistName') or ''), artist): 

353 return None 

354 if kind == 'track': 

355 if row.get('kind') != 'song' or not _names_match( 

356 str(row.get('trackName') or ''), title 

357 ): 

358 return None 

359 url, price = row.get('trackViewUrl'), row.get('trackPrice') 

360 elif kind == 'album': 

361 if row.get('wrapperType') != 'collection' or not _names_match( 

362 str(row.get('collectionName') or ''), album 

363 ): 

364 return None 

365 url, price = row.get('collectionViewUrl'), row.get('collectionPrice') 

366 else: 

367 if row.get('wrapperType') != 'artist': 

368 return None 

369 url, price = row.get('artistLinkUrl'), None 

370 url = str(url or '').strip() 

371 if not url.startswith('https://'): 

372 return None 

373 # -1 (or nothing) when the item isn't sold on its own ("album only"). 

374 try: 

375 amount = float(price) if price is not None else 0.0 

376 except (TypeError, ValueError): 

377 amount = 0.0 

378 return { 

379 'url': url, 

380 'price': amount if amount > 0 else None, 

381 'currency': str(row.get('currency') or '') if amount > 0 else '', 

382 } 

383 

384 

385def store_match( 

386 kind: str, 

387 artist: str, 

388 title: str = '', 

389 album: str = '', 

390 country: str = 'US', 

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

392 """The iTunes Store page of a song (``kind`` ``track``), an album or 

393 an artist in *country*'s store, as ``{url, price, currency}`` - 

394 ``price`` is ``None`` for an artist and for something not sold on its 

395 own. ``None`` when nothing in the store clearly is it.""" 

396 

397 entity = _STORE_ENTITIES.get(kind) 

398 if entity is None or not artist: 

399 return None 

400 name = {'track': title, 'album': album}.get(kind, '') 

401 if kind != 'artist' and not name: 

402 return None 

403 key = '|'.join(( 

404 kind, 

405 country, 

406 _normalise(artist), 

407 _normalise(title), 

408 _normalise(album), 

409 )) 

410 with _cache_lock: 

411 if key in _store_cache: 

412 return _store_cache[key] 

413 query = f'{artist} {name}'.strip() 

414 rows = _search_itunes(query, limit=10, entity=entity, country=country) 

415 if not rows: 

416 # Nothing, or the request failed: worth asking again later. 

417 return None 

418 found = None 

419 for row in rows: 

420 found = _store_item(kind, row, artist, title, album) 

421 if found is not None: 

422 break 

423 with _cache_lock: 

424 if len(_store_cache) >= _STORE_CACHE_MAX: 

425 _store_cache.clear() 

426 _store_cache[key] = found 

427 return found