Coverage for downtify/itunes.py: 78%
227 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"""Fetch genre metadata from the iTunes Search API.
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"""
10from __future__ import annotations
12import re
13import time
14import unicodedata
15from threading import Lock
16from typing import Any, Optional
17from urllib.parse import quote_plus
19import httpx
20from loguru import logger
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)
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()
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] = {}
41# Timestamp of the last outgoing request – used for rate pacing.
42_last_request_time: float = 0.0
43_rate_lock = Lock()
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()
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
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()
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.
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 []
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
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
162# ── Public API ────────────────────────────────────────────────────
163def fetch_genre(song: dict[str, Any]) -> str:
164 """Return the genre string for *song*, or ``""`` if unavailable.
166 ``song`` is the standard Downtify track dict with at least
167 ``name``, ``artists`` (list[str]) and optionally ``album_name``.
168 """
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', '')
175 if not artist and not title:
176 return ''
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
189 # ── Search iTunes ─────────────────────────────────────────────
190 query = f'{artist} {title}'.strip()
191 results = _search_itunes(query, limit=5)
192 match = _pick_best(results, artist, title)
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)
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)
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, '')
221 return genre
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)$')
231def artwork_url_at(url: str, size: int) -> str:
232 """Rewrite an iTunes artwork URL to ask for a ``size``-pixel square."""
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 )
241def search_podcasts(query: str, limit: int = 10) -> list[dict[str, Any]]:
242 """Search the iTunes podcast directory for *query*.
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 """
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')]
266def resolve_podcast_feed(show_name: str) -> Optional[dict[str, Any]]:
267 """The best iTunes match for a show name, or ``None``.
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 """
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
291def fetch_artwork_url(song: dict[str, Any], size: int = 1200) -> str:
292 """Return an iTunes cover URL for *song* at *size* px, or ``""``.
294 Same matching as :func:`fetch_genre`: artist and title must line up,
295 with a title-only fallback for differing "feat." credits.
296 """
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', '')
303 if not title:
304 return ''
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 ''
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)
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)
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]]] = {}
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."""
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 }
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."""
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