Simplifying item/album handling in the plugin API
- 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
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