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 70.14925% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.49%. Comparing base (6dd6251) to head (ef39cd2).
⚠️ Report is 2 commits behind head on master.

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

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6606      +/-   ##
==========================================
+ Coverage   72.46%   72.49%   +0.02%     
==========================================
  Files         161      161              
  Lines       20719    20766      +47     
  Branches     3280     3288       +8     
==========================================
+ Hits        15014    15054      +40     
- Misses       4979     4986       +7     
  Partials      726      726              

Files with missing lines	Coverage Δ
beetsplug/listenbrainz.py	60.26% <70.14%> (+6.41%)	⬆️

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

[Maxr1998]

Made the requested changes in 1e089ec.

[snejus]

@Maxr1998 See test failures.

[snejus]

Just add a return type here for clarity as well please!

[Maxr1998]

Done. Let me know if you want me to squash the commits before you merge.

[snejus]

No worries about that. Would you mind defining a specific TypedDict type for those listens?

[Maxr1998]

Done. I hope all the checks pass cleanly. I can also extract the types to a separate file like the Deezer plugin does, but that's definitely a separate PR.

I also feel like the recording_mbid behavior change should be a separate PR. Please tell me if you agree, then I will extract that part first. (Alternatively, I could reorder and squash my commits so that they stack cleanly when you do a normal merge commit or rebase merge.)