typing: type aura, web plugin and export plugin

[snejus]

Part of #6924.

• This change tightens typing across beetsplug/aura.py, beetsplug/export.py, and beetsplug/web/__init__.py so plugin interfaces better match real runtime behavior.

• High-level impact: no big feature shift, but architecture become more explicit. Plugin boundaries, data shapes, and format handling are clearer, which should make future changes safer and type errors easier to catch.

aura

• base document methods are more explicit
• request args are lined up with MultiDict
• add safer handling for missing included resources.

I could not resolve typing without using type: ignore in two places and I found both pieces of logic should be removed:

1. Field value conversion
   • It caused sqlite3.InterfaceError when using filter[genres], because it was split into, e.g. "genres" -> ["g", "e", "n", "r", "e", "s"].
   • The rest of the field types are either str and int. MatchQuery happily accepts a str pattern when matching int fields.
2. When sorting by a field, excluding empty/null values: I'm pretty sure this is not the behaviour we want 😅.

Extended tests to prove both of the above.

export

• simplify format selection and moves export flow to a single iterable-based pipeline
• json, jsonlines, csv, and xml now share one higher-level data path, with path-like byte fields normalized before writing

web

• add clearer endpoint and decorator annotations
• a small safety fix for missing item files returning 404 instead of failing later

[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 make typing more sharp in plugin boundary. goal: type checker stop lying, and runtime edge case less crash.

Changes:

• Add/adjust type annotations in aura + safer handling when included resource missing.
• Refactor export into one iterable pipeline across json/jsonlines/csv/xml, plus path-byte stringify.
• Add clearer web plugin endpoint/decorator annotations, plus 404 when item missing.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
beetsplug/aura.py	Tighten document/query typing and make included resource fetching safer.
beetsplug/export.py	Unify export data flow across formats and improve typing around formats/paths.
beetsplug/web/init.py	Add endpoint/decorator typing and small runtime safety for missing items.

Suppressed comments (2)

beetsplug/web/init.py:281

• grug see QueryConverter.to_url annotation say str, but to_python make list[str]. if str passed, code iterate chars and make bad url. type should be list[str] to match.

    def to_url(self, value: str) -> str:
        return "/".join([v.replace(os.sep, "\\") for v in value])

beetsplug/aura.py:289

• grug see get_included append Artist/Image resource_object even when None. then response have null in included list, JSON:API not like, and clients sad. only append when resource object not None, and keep included typed list[JSONDict].

        included: list[JSONDict | None] = []
        for identifier in unique_identifiers:
            res_type = identifier["type"]
            if res_type == "track":
                track_id = int(identifier["id"])

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 91.48936% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.01%. Comparing base (f48f6e8) to head (87da1ca).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
beetsplug/export.py	87.23%	5 Missing and 1 partial ⚠️
beetsplug/aura.py	92.15%	2 Missing and 2 partials ⚠️
beetsplug/web/__init__.py	95.34%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           type-bpd    #6937      +/-   ##
============================================
- Coverage     76.02%   76.01%   -0.02%     
============================================
  Files           164      164              
  Lines         21572    21577       +5     
  Branches       3340     3341       +1     
============================================
+ Hits          16400    16401       +1     
- Misses         4380     4381       +1     
- Partials        792      795       +3     

Files with missing lines	Coverage Δ
beetsplug/web/__init__.py	71.22% <95.34%> (-0.52%)	⬇️
beetsplug/aura.py	57.77% <92.15%> (-0.10%)	⬇️
beetsplug/export.py	88.49% <87.23%> (-0.11%)	⬇️

🚀 New features to boost your workflow:

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

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (2)

beetsplug/aura.py:181

• grug see filter convert use list(...) when field type is multi-value (like genres/composers). list('rock') become ['r','o','c','k'] and MatchQuery then never match list field. grug think keep string for list-typed field.

                value = converter(v)  # type: ignore[arg-type, misc]

beetsplug/web/init.py:86

• grug see json_generator always yield strings (docstring say so). return type Iterator[Any] too loose, typing gain gone. grug want Iterator[str].

def json_generator(
    items: Sequence[LibModel], root: str, expand: bool = False
) -> Iterator[Any]: