typing: type bpd plugin

[snejus]

Part of #6924.

• This PR makes the beetsplug.bpd server stack easier to understand by adding explicit type annotations across the main layers: BaseServer, Server, Connection, MPDConnection, ControlConnection, Command, and GstPlayer.

• At an architectural level, it clarifies how data moves through the plugin:

  • command handlers now have clearer input and return types,
  • shared server state like playlist, connections, and notification sets is declared directly,
  • internal playback paths that do not come from a live client are modeled explicitly with MPDConnection | None.

• It also includes a few small refactors that support that clearer structure without changing the design:

  • _parse_range is moved into BaseServer so the shared logic is actually available where it is used,
  • command parsing is simplified,
  • socket reads now separate raw bytes from decoded text,
  • VFS and library lookups are guarded more carefully.

• High-level impact: this is mainly a maintainability and correctness change, not a feature change. It makes internal interfaces in bpd more explicit, improves static type checking, and reduces the chance of type-related bugs while keeping the plugin's overall behavior and architecture the same.

[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 beetsplug.bpd server stack easier to reason about by adding types and small refactor, so static check can catch more bug while runtime stay same.

Changes:

• add many type annotations across server/connection/command layers in beetsplug.bpd
• move + type shared helpers like range parsing and command parsing
• add extra guards around bytes vs text reads, VFS + library lookups

Reviewed changes

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

File	Description
beetsplug/bpd/init.py	main typing pass over BPD server + protocol handlers; refactor parsing and add guards
beetsplug/bpd/gstplayer.py	add typing + small import cleanup for GstPlayer and decoder helpers

Suppressed comments (2)

beetsplug/bpd/init.py:660

• grug see _parse_range take MPD range text like "1:10". annotation say int, but real input is str sometimes. make type match so static check useful.

    def _parse_range(
        items: int, accept_single_number: bool = False
    ) -> list[int] | range:

beetsplug/bpd/init.py:675

• grug see cmd_playlistinfo index come from wire, so it is str ("5" or "1:3"). annotation say int, so type check lie. accept str too.

    def cmd_playlistinfo(
        self, conn: MPDConnection, index: int | None = None
    ) -> Iterator[Any]:

---

💡 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 90.81633% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.02%. Comparing base (725ef3e) to head (f48f6e8).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
beetsplug/bpd/__init__.py	91.22%	10 Missing and 5 partials ⚠️
beetsplug/bpd/gstplayer.py	88.00%	3 Missing ⚠️

Additional details and impacted files

@@                 Coverage Diff                 @@
##           remove-do-query    #6936      +/-   ##
===================================================
- Coverage            76.03%   76.02%   -0.01%     
===================================================
  Files                  164      164              
  Lines                21559    21572      +13     
  Branches              3334     3340       +6     
===================================================
+ Hits                 16392    16400       +8     
- Misses                4378     4380       +2     
- Partials               789      792       +3     

Files with missing lines	Coverage Δ
beetsplug/bpd/gstplayer.py	41.50% <88.00%> (+1.12%)	⬆️
beetsplug/bpd/__init__.py	75.62% <91.22%> (-0.29%)	⬇️

🚀 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 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (4)

beetsplug/bpd/init.py:675

• grug see typing lie: cmd_playlistinfo index can be range string like "0:10" from client, but signature say int. make accept str|int so handler type match real caller.

    def cmd_playlistinfo(
        self, conn: MPDConnection, index: int | None = None
    ) -> Iterator[Any]:

beetsplug/bpd/init.py:1370

• grug see bug: if node is int but lib.get_item(node) return None, code fall into elif node: and try use node.files on int. boom AttributeError. need handle int case separate and stop after lookup miss.

        if isinstance(node, int) and (item := self.lib.get_item(node)):
            # Could be more efficient if we built up all the IDs and
            # then issued a single SELECT.
            yield item
        elif node:
            # Recurse into a directory.

beetsplug/bpd/init.py:660

• grug see typing lie: MPD range arg can be "START:STOP" string, but _parse_range say items int. make accept str too so types match real protocol input.

This issue also appears on line 673 of the same file.

    def _parse_range(
        items: int, accept_single_number: bool = False
    ) -> list[int] | range:

beetsplug/bpd/gstplayer.py:133

• grug worry play_file URI build break on Windows: code encode str to bytes then urllib.parse.quote will percent-escape drive colon and backslashes. better build URI from decoded path string, normalize separators, keep drive colon safe.

    def play_file(self, path: str | bytes) -> None:
        """Immediately begin playing the audio file at the given
        path.
        """