listenbrainz: add option to import listens from ListenBrainz data export zip

[Maxr1998]

Description

Since importing listens from the API is rather slow and puts unnecessary load on the servers, importing a dump exported from https://listenbrainz.org/settings/export/ should also be possible. This change introduces the export-file parameter to the lbimport command, which takes all listens from the zipfile to update the play counts.

I also fixed an issue where mbid_mapping could be None if explicitly set to null in the JSON (which happens for these exports sometimes), and changed the recording mbid logic to prefer one explicitly supplied by the player in the additional_data, instead of relying on the (sometimes inaccurate) mapper.

Since the --max parameter isn't documented either, I'm unsure whether I should add the parameter to the plugin docs. In theory, the --help parameter already tells you enough.

I'm also not sure if the --max parameter should apply to exported files, especially since the order of zip file entries isn't deterministic.

To Do

• Documentation. (If you've added a new command-line flag, for example, find the appropriate page under docs/ to describe it.)
• Changelog. (Add an entry to docs/changelog.rst to the bottom of one of the lists near the top of the document.)
• Tests. (Very much encouraged but not strictly required.)

[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.

[Copilot]

Pull request overview

grug see PR try make lbimport faster and nicer to ListenBrainz server. it add way to read listens from ListenBrainz export zip, then update play counts in beets.

Changes:

• add lbimport --export-file PATH to read listens from ListenBrainz data export zip instead of API
• add zip/jsonl import helper and wire it into _lbupdate
• tweak MBID pick logic to handle mbid_mapping: null and prefer explicit MBID when present

[codecov]

Codecov Report

❌ Patch coverage is 74.35897% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.44%. Comparing base (44f7bf8) to head (9ecca69).
⚠️ Report is 13 commits behind head on master.

Files with missing lines	Patch %	Lines
beetsplug/listenbrainz.py	74.35%	9 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6606      +/-   ##
==========================================
+ Coverage   72.43%   72.44%   +0.01%     
==========================================
  Files         160      160              
  Lines       20681    20714      +33     
  Branches     3272     3279       +7     
==========================================
+ Hits        14980    15006      +26     
- Misses       4976     4983       +7     
  Partials      725      725              

Files with missing lines	Coverage Δ
beetsplug/listenbrainz.py	57.67% <74.35%> (+3.82%)	⬆️

🚀 New features to boost your workflow:

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

[Serene-Arc]

Thanks for the PR! I'm of the opinion that more documentation is always better. If there's an option that isn't currently documented, then please do add documentation for it, either in this PR or another one.

As for the --max option I agree that it shouldn't apply to imported files. From the code, it seems to be an API-limiting option which doesn't really apply to when you're importing offline data. Further, I would expect someone who has downloaded that data to either filter the new dataset themselves or else want to import the whole thing, especially if the process isn't deterministic.

grug is correct that this interaction should be noted in the documentation though.

[Maxr1998]

@Serene-Arc thanks, I made some further adjustments, added some documentation, tests, and a changelog entry. Should be ready to review now.