Implement aliases

Author: JOJ0

beetsplug/lastgenre/__init__.py

@@ -37,7 +37,7 @@
 from beets.library import Album, Item
 from beets.ui import UserError
 from beets.util import plurality, unique_list
-from beetsplug.lastgenre.utils import is_ignored
+from beetsplug.lastgenre.utils import is_ignored, normalize_genre
 
 from .client import LastFmClient
 
@@ -48,7 +48,7 @@
     from beets.importer import ImportSession, ImportTask
     from beets.library import LibModel
 
-    from .utils import Ignorelist
+    from .utils import Aliases, Ignorelist
 
     Whitelist = set[str]
     """Set of valid genre names (lowercase). Empty set means all genres allowed."""
@@ -118,6 +118,7 @@ def sort_by_depth(tags: list[str], branches: CanonTree) -> list[str]:
 
 WHITELIST = os.path.join(os.path.dirname(__file__), "genres.txt")
 C14N_TREE = os.path.join(os.path.dirname(__file__), "genres-tree.yaml")
+ALIASES = os.path.join(os.path.dirname(__file__), "aliases.yaml")
 
 
 class LastGenrePlugin(plugins.BeetsPlugin):
@@ -140,6 +141,7 @@ def __init__(self) -> None:
                 "title_case": True,
                 "pretend": False,
                 "ignorelist": False,
+                "aliases": True,
             }
         )
         self.setup()
@@ -153,8 +155,12 @@ def setup(self) -> None:
         self.c14n_branches: CanonTree
         self.c14n_branches, self.canonicalize = self._load_c14n_tree()
         self.ignorelist: Ignorelist = self._load_ignorelist()
+        self.aliases: Aliases = self._load_aliases()
         self.client = LastFmClient(
-            self._log, self.config["min_weight"].get(int), self.ignorelist
+            self._log,
+            self.config["min_weight"].get(int),
+            self.ignorelist,
+            self.aliases,
         )
 
     def _load_whitelist(self) -> Whitelist:
@@ -250,6 +256,18 @@ def _load_ignorelist(self) -> Ignorelist:
         self._log.extra_debug("Ignorelist: {}", ignorelist_raw)
         return self._compile_ignorelist_patterns(ignorelist_raw)
 
+    @staticmethod
+    def _compile_pattern(raw: str) -> re.Pattern[str]:
+        """Compile *raw* as a case-insensitive full-match regex.
+
+        Tries regex compilation first; falls back to treating the string as a
+        literal (via ``re.escape``) if it is not valid regex.
+        """
+        try:
+            return re.compile(raw, re.IGNORECASE)
+        except re.error:
+            return re.compile(re.escape(raw), re.IGNORECASE)
+
     @staticmethod
     def _compile_ignorelist_patterns(
         ignorelist: RawIgnorelist,
@@ -265,17 +283,67 @@ def _compile_ignorelist_patterns(
             defaultdict(list)
         )
         for artist, patterns in ignorelist.items():
-            compiled_patterns = []
-            for pattern in patterns:
-                try:
-                    compiled_patterns.append(re.compile(pattern, re.IGNORECASE))
-                except re.error:
-                    compiled_patterns.append(
-                        re.compile(re.escape(pattern), re.IGNORECASE)
-                    )
-            compiled_ignorelist[artist] = compiled_patterns
+            compiled_ignorelist[artist] = [
+                LastGenrePlugin._compile_pattern(p) for p in patterns
+            ]
         return compiled_ignorelist
 
+    def _load_aliases(self) -> Aliases:
+        """Load the genre alias table from the beets config.
+
+        Reads ``lastgenre.aliases`` as a mapping of canonical genre names
+        (the replacement template) to lists of regex patterns::
+
+            lastgenre:
+                aliases:
+                    drum and bass:
+                        - d(rum)?[ &n/]*b(ass)?
+                    \\g<1> hop:
+                        - (glitch|hip|jazz|trip)y?[ /-]*hop
+
+        The key (canonical name) is used as a ``re.Match.expand()`` template,
+        so ``\\g<N>`` back-references to capture groups are supported.  Plain
+        string keys work without any special syntax.
+
+        Setting ``aliases: true`` (the default) loads the bundled
+        ``aliases.yaml`` file.  Setting ``aliases: false`` disables
+        normalization entirely.
+
+        Patterns are applied in order; the first full-match wins.
+
+        Raises:
+            UserError: if the config value is not a mapping, or if an entry's
+            value is not a list of strings.
+        """
+        aliases_config = self.config["aliases"].get()
+        if aliases_config is False:
+            return []
+        if aliases_config in (True, "", None):
+            self._log.debug("Loading default aliases from {}", ALIASES)
+            with Path(ALIASES).open(encoding="utf-8") as f:
+                aliases_config = yaml.safe_load(f)
+            if not aliases_config:
+                return []
+        if not isinstance(aliases_config, dict):
+            raise UserError(
+                "Invalid value for lastgenre.aliases: expected a mapping "
+                f"(canonical \u2192 list of patterns), got {aliases_config!r}"
+            )
+
+        entries: Aliases = []
+        for canonical, patterns in aliases_config.items():
+            if not isinstance(patterns, list):
+                raise UserError(
+                    f"Invalid lastgenre.aliases entry for {canonical!r}: "
+                    f"expected a list of patterns, got {patterns!r}"
+                )
+            template = str(canonical).lower()
+            for raw in patterns:
+                entries.append((self._compile_pattern(str(raw)), template))
+
+        self._log.extra_debug("Loaded {} alias entries", len(entries))
+        return entries
+
     @property
     def sources(self) -> tuple[str, ...]:
         """A tuple of allowed genre sources. May contain 'track',
@@ -297,6 +365,8 @@ def _resolve_genres(
         """Canonicalize, sort and filter a list of genres.
 
         - Returns an empty list if the input tags list is empty.
+        - If aliases are configured, variant spellings are normalised first
+          (e.g. 'hip-hop' → 'hip hop', 'dnb' → 'drum and bass').
         - If canonicalization is enabled, it extends the list by incorporating
           parent genres from the canonicalization tree. When a whitelist is set,
           only parent tags that pass the whitelist filter are included;
@@ -316,6 +386,12 @@ def _resolve_genres(
         if not tags:
             return []
 
+        # Normalize variant spellings before any other processing.
+        if self.aliases:
+            tags = [
+                normalize_genre(self._log, self.aliases, tag) for tag in tags
+            ]
+
         count = self.config["count"].get(int)
 
         # Canonicalization (if enabled)

beetsplug/lastgenre/client.py

@@ -25,14 +25,14 @@
 
 from beets import plugins
 
-from .utils import is_ignored
+from .utils import is_ignored, normalize_genre
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
     from beets.logging import BeetsLogger
 
-    from .utils import Ignorelist
+    from .utils import Aliases, Ignorelist
 
     GenreCache = dict[str, list[str]]
     """Cache mapping entity keys to their genre lists.
@@ -52,7 +52,11 @@ class LastFmClient:
     """Client for fetching genres from Last.fm."""
 
     def __init__(
-        self, log: BeetsLogger, min_weight: int, ignorelist: Ignorelist
+        self,
+        log: BeetsLogger,
+        min_weight: int,
+        ignorelist: Ignorelist,
+        aliases: Aliases,
     ):
         """Initialize the client.
 
@@ -62,6 +66,7 @@ def __init__(
         self._log = log
         self._min_weight = min_weight
         self._ignorelist: Ignorelist = ignorelist
+        self._aliases: Aliases = aliases
         self._genre_cache: GenreCache = {}
 
     def fetch_genre(
@@ -138,13 +143,15 @@ def _last_lookup(
             "last.fm (unfiltered) {} tags: {}", entity, genres
         )
 
-        # Filter forbidden genres on every call so ignorelist hits are logged.
-        # Artist is always the first element in args (album, artist, track lookups).
-        return [
-            g
-            for g in genres
-            if not is_ignored(self._log, self._ignorelist, g, args[0])
-        ]
+        result = []
+        for genre in genres:
+            if self._aliases:
+                genre = normalize_genre(self._log, self._aliases, genre)
+
+            if not is_ignored(self._log, self._ignorelist, genre, args[0]):
+                result.append(genre)
+
+        return result
 
     def fetch_album_genre(self, albumartist: str, albumtitle: str) -> list[str]:
         """Return genres from Last.fm for the album by albumartist."""

beetsplug/lastgenre/utils.py

@@ -27,6 +27,12 @@
     Ignorelist = dict[str, list[re.Pattern[str]]]
     """Mapping of artist name to list of compiled case-insensitive patterns."""
 
+    AliasEntry = tuple[re.Pattern[str], str]
+    """A compiled full-match pattern paired with its replacement template."""
+
+    Aliases = list[AliasEntry]
+    """Ordered list of (pattern, replacement_template) alias entries."""
+
 
 def is_ignored(
     logger: BeetsLogger,
@@ -47,3 +53,21 @@ def is_ignored(
             logger.extra_debug("ignored (artist: {}): {}", artist, genre)
             return True
     return False
+
+
+def normalize_genre(logger: BeetsLogger, aliases: Aliases, genre: str) -> str:
+    """Return the canonical form of *genre* using *aliases*.
+
+    Tries each alias entry in order. The first full-match wins; the
+    replacement template is expanded via ``re.Match.expand()`` so
+    ``\\g<N>`` back-references work. Returns *genre* unchanged when
+    no alias matches.
+    """
+    genre_lower = genre.lower()
+    for pattern, template in aliases:
+        if m := pattern.fullmatch(genre_lower):
+            expanded = m.expand(template)
+            if expanded != genre:
+                logger.extra_debug("aliased: {} -> {}", genre, expanded)
+            return expanded
+    return genre_lower