lastgenre: Genre spelling normalization (aliases)

[JOJ0]

Description

This PR introduces a regex-based normalization (alias) system to unify variant genre tags and improves the plugin's documentation.

The normalization feature uses an ordered list of regular expression aliases to map variant spellings or synonyms to a single canonical name. The mapping keys act as re.Match.expand() templates, supporting \g<N> (or shorter, eg. \1) back-references to regex capture groups:

lastgenre:
    aliases:
        # Maps 'hip-hop' -> 'hip hop' using back-references 
        # (regex full-match)
        \1hop:
            - (hip|trip|jazz)y?[ /-]*hop
        
        # Static normalization examples
        drum and bass:
            - dnb
            - d&b

• Where?: Integrated normalize_genre before is_ignored in both the LastFmClient (for clean lookup/filtering) and the core _resolve_genres loop (for uniform processing of existing file tags).
• Updated default whitelist and genre tree files for canonical-name consistency, and curated the bundled aliases.yaml from the top 1,000 Last.fm tags to cover common inconsistencies without over-normalizing.
• Any normalization that occurs is logged (extra debug log level beet -vvv ...)
• Additional documentation changes:
  • Added a Choosing the Right Tool guide. This is for endusers but note that it might even be a primary starting point for maintainer review.
  • Added non-whitelist mode details to the Canonicalization chapter.
• Additional unrelated changes:
  • Fixes a few variable name inconsistencies in the recently merged ignorelist features' tests.
  • Improved naming of ignorelist related type IgnorePatternsByArtist

[github-actions]

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

[codecov]

Codecov Report

❌ Patch coverage is 88.13559% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.97%. Comparing base (dab3bd3) to head (c51f575).
⚠️ Report is 8 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
beetsplug/lastgenre/client.py	60.00%	4 Missing and 2 partials ⚠️
beetsplug/lastgenre/__init__.py	96.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6466      +/-   ##
==========================================
+ Coverage   74.91%   74.97%   +0.06%     
==========================================
  Files         163      163              
  Lines       21176    21209      +33     
  Branches     3342     3349       +7     
==========================================
+ Hits        15863    15902      +39     
+ Misses       4546     4538       -8     
- Partials      767      769       +2     

Files with missing lines	Coverage Δ
beetsplug/lastgenre/utils.py	100.00% <100.00%> (ø)
beetsplug/lastgenre/__init__.py	82.62% <96.66%> (+0.94%)	⬆️
beetsplug/lastgenre/client.py	66.66% <60.00%> (+13.00%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

[JOJ0]

This is closely related to #6449 and might make sense to have a look when reviewing the former @snejus Many thanks in advance! 🙌

[JOJ0]

Hi @snejus I commented inline (sorry it's pretty messy here already :-/) addressed all suggestions and I am happy with the result. Please have a (hopefully final) look :-)

Note to myself: I'll probably simply squash all the commits or maybe reset and recommit everything so at least changes not directly involved with this new feature stay separate!

[JOJ0]

@snejus adressed all the code suggestions. That part is ready to merge I think.

What do you think of this change? 1ccdc2d

What should we do about alternative and minimal? Open for any suggestions as long as we finally get this merged :-)

Anything else left to do? You might want to review the changelog. Tried to explain what the goal was with default aliases and genre changes.

What do you think of this future feature ideas? It might address the real issues here:

• Allow a combination of multiple genre tags to be combined: If something is tagged on last.fm as alternative and rock -> alternative rock, Same example with minimal/techno. A kind of "rule system".

And another one, which could make life easier for the user? Not sure:

• Allow extending the default list, instead of just replacing it?

[JOJ0]

@snejus regarding alternative and minimal, what do you think of this solution: 9db9704

if we don't put them into the tree at all but allow them in the whitelist. they simply stay as a valid genre but wont get canonicalized (given that wl and canonical are enabled)

[snejus]

What do you think of this change? 1ccdc2d

Seems like breaks is now gone from genres.txt?

[snejus]

Thanks, I had another look.

Regarding alternative and minimal, I think the solution in 9db9704 is exactly what I had in mind: don't translate them, but keep them in the whitelist and out of the tree. This way they remain valid genres even when both the whitelist and canonicalization are enabled, but we don't assign them a more specific meaning. Users can still add the translation themselves if they want to treat them as alternative rock and minimal techno.

There are still three failing tests, by the way: chill → chillout, alt → alternative rock and alternative → alternative rock. Would you mind updating or removing those cases?

The changelog makes sense to me. However, I'd probably avoid saying that the files were "audited" and that long-standing mismatches were "resolved" since this sounds a bit too definitive. I'd simply say that the default aliases normalize common Last.fm spelling and naming variants and that the whitelist and genre tree were updated with additional common Last.fm tags.

Regarding the future features:

Allow a combination of multiple genre tags to be combined

Makes sense! alternative + rock gives us the context which is missing when looking at alternative alone. On the other hand, I think this should be a separate feature since it needs to operate on the whole list of tags. We would need to decide whether matched tags are removed or retained and in which order the rules are applied.

Allow extending the default list, instead of just replacing it?

This also makes sense to me and is probably simpler. Maybe a separate aliases_add option would make the distinction between extending and replacing explicit?

I don't think either of these needs to be part of this PR.

[JOJ0]

Hi @snejus thanks for the last feedback on future ideas (yes future as in separate feature requests), and for the finalization: As we discussed internally, let's keep everything as minimal and limited to spelling correction / and obvious duplication fixes only. Please go ahead and push a commit if you find the time. I'll fix all tests once that's done.

[snejus]

See #6823

[JOJ0]

See #6823

Wohoo! It's merged! Thanks for the support! ❤️