beetbox / beetbox/beets

Simplifying item/album handling in the plugin API

Open
#5,310 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
15.7k
Forks
2.1k
Avg merge
4d 21h
Merged PRs (30d)
31

Description

I'm trying to improve the type annotations in `beets/plugins.py`, and I noticed that the plugin API deals with item and album types really weirdly. Plugins are expected to (optionally) define `item_types` and `album_types` (which are not defined in the `BeetsPlugin` superclass, losing out on type information), which are then dynamically queried using `getattr(..., f"{cls.__name__.lower()}_types")` for the `Item` and `Album` classes. The same applies to `{item,album}_queries`. See [here](https://github.com/beetbox/beets/blob/494c67603a6b76dc7d81591b9326c0749d3b6549/beets/plugins.py#L338-L352).

Getting good type-checking with such a system is really difficult, and it doesn't look like this is used for anything more than the `Item` and `Album` types. I propose deprecating any functions relying on such a system (e.g. `plugins.types()` and `plugins.named_queries()`). There are two possible solutions here:

1. Support the possibility of other kinds of objects. Define a single field for `{item,album}_types`, as a `dict` mapping from the kind of object (either as a string or the `Item` / `Album` classes) to a list of database types specific to that kind of object.

2. Only allow for `Item` and `Album`. Explicitly define `item_types` and `album_types` in `BeetsPlugin` and provide `plugins.item_types()` and `plugins.album_types()`.

I'm happy to make a PR implementing either solution. Regardless of what is picked, the old functions can be maintained for backward compatibility with external code (should any exist?).

Contributor guide

Open the contributing guide

Research direction

Start with beets/plugins.py around lines 338-352 and trace plugins.types() and plugins.named_queries(), including the item_types, album_types, item_queries, and album_queries attributes. The issue presents two incompatible API directions, so first confirm which approach maintainers want and identify the backward-compatibility requirements for existing functions. Done means the selected API has improved type information while preserving required compatibility.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.