Coverage for downtify/album_artist.py: 100%
33 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"""Which artist an album is filed and tagged under, and when an album is a
2various-artists compilation.
4A leaf module (it imports nothing from Downtify), like ``file_naming``, so
5the Spotify, Deezer and YouTube Music scrapers and the downloader can share
6the one rule.
8The album artist is always the one the source declares for the album, never
9something worked out from its tracks: a single-artist album with a guest on
10one track ("Alice feat. Bob") still belongs to Alice, and a duo album has
11the same two artists on every track without being a compilation. Only when
12the source credits the album to "Various Artists" is it a compilation -
13which media servers like Navidrome want marked on every track (``TCMP`` /
14``COMPILATION`` / ``cpil``), or they break the album up by artist.
15"""
17from __future__ import annotations
19import re
20from typing import Any
22from loguru import logger
24VARIOUS_ARTISTS = 'Various Artists'
26# The "Various Artists" entity on each service. Deezer localizes its name
27# ("Vários intérpretes" for a Brazilian client), so its ids are what count
28# there; Spotify only exposes its id on the playlist GraphQL path. The two
29# id spaces can't collide (Deezer's are numeric, Spotify's base62).
30_VARIOUS_ARTISTS_IDS = frozenset({
31 '0LyfQWJT6nXafLPZqxe9Of', # Spotify
32 '5080', # Deezer
33 '108420982', # Deezer, a second "Various Artists" entity
34})
36# Names a source may use for it, case-insensitive. Only the first is what
37# Spotify and YouTube Music have been seen to send; the rest are the
38# translations services use, in case one turns up.
39_VARIOUS_ARTISTS_NAMES = frozenset({
40 'various artists',
41 'various',
42 'vários artistas',
43 'varios artistas',
44 'vários intérpretes',
45 'varios intérpretes',
46 'varios interpretes',
47 'artistes divers',
48 'artistes variés',
49 'verschiedene interpreten',
50 'artisti vari',
51 'artisti varie',
52})
55def is_various_artists(name: Any, *, artist_id: Any = '') -> bool:
56 """Whether *name* (or *artist_id*, a Spotify or Deezer artist id) is
57 the "Various Artists" placeholder rather than a real artist."""
59 if str(artist_id or '').strip() in _VARIOUS_ARTISTS_IDS:
60 return True
61 text = ' '.join(str(name or '').split()).casefold()
62 if text not in _VARIOUS_ARTISTS_NAMES:
63 return False
64 if text != VARIOUS_ARTISTS.casefold():
65 logger.info('Treating album artist {!r} as Various Artists', name)
66 return True
69# What sits between the members' names in an act's own name: "Henrique &
70# Juliano", "Simon + Garfunkel", "Sandy e Junior", "Zé Neto, Cristiano".
71# Not "x": "Anitta x Pedro Sampaio" names a collaboration, not an act.
72_ACT_NAME_JOINER = r'\s*(?:&|\+|,|/|\b(?:e|and|y)\b)\s*'
75def is_act_of(names: list[str], act: Any) -> bool:
76 """Whether *act* is the name of an act made of exactly *names* (two or
77 more), joined the way an act's name joins its members, in any order:
78 ``(['Mateus', 'Jorge'], 'Jorge & Mateus')`` -> True. Mirrored by
79 ``isActOf`` in ``frontend/src/lib/library.js``."""
81 if len(names) < 2:
82 return False
83 members = [
84 part
85 for part in re.split(_ACT_NAME_JOINER, str(act or '').casefold())
86 if part.strip()
87 ]
88 return sorted(part.strip() for part in members) == sorted(
89 str(name).strip().casefold() for name in names
90 )
93def filing_artist(song: dict[str, Any]) -> str:
94 """The artist a downloaded *song* is filed under ("Organize by artist")
95 and whose profile it seeds: its album artist, so every track of an
96 album lands together - except for a various-artists compilation, whose
97 tracks go to their own first artist instead of a "Various Artists"
98 folder (the tags still say "Various Artists", which is what keeps the
99 album whole in a media server). ``''`` when there is no artist."""
101 album_artist = str(song.get('album_artist') or '').strip()
102 if (
103 album_artist
104 and not song.get('compilation')
105 and not is_various_artists(album_artist)
106 ):
107 return album_artist
108 artists = song.get('artists') or []
109 return str(artists[0]).strip() if artists else ''
112def album_artist_fields(name: Any, *, artist_id: Any = '') -> dict[str, Any]:
113 """The song fields for an album credited to *name*: ``album_artist``,
114 plus ``compilation: True`` (and the canonical "Various Artists") when
115 it is a various-artists compilation. Empty when *name* is blank, so
116 the caller falls back to the track's first artist."""
118 if is_various_artists(name, artist_id=artist_id):
119 return {'album_artist': VARIOUS_ARTISTS, 'compilation': True}
120 text = str(name or '').strip()
121 return {'album_artist': text} if text else {}