beetbox / beetbox/beets

Split ImportTask Architecture for Albums and Singletons

Open
#6,686 0 comments 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

## Summary
Split importer task responsibilities into explicit album and singleton task types so each flow has a focused contract and fewer conditional branches.

## Problem
`ImportTask` currently mixes behaviors for both album and singleton flows:
- mixed state and branching around `is_album`
- loose coupling between `choice_flag` and `match`
- methods that only apply to one flow but exist on both
- sentinel/import-progress behavior inheriting importer task logic it does not need

This increases type looseness, forces runtime conditionals, and makes behavior harder to reason about.

## Proposed Split
Create explicit task roles with clear ownership:
- `AlbumImportTask`: album matching, album duplicate handling, album add/reimport flow.
- `SingletonImportTask`: track-only matching, item duplicate handling, singleton add/reimport flow.
- `SentinelImportTask` (or equivalent progress marker): progress/history signaling only, without inheriting full album/singleton task behavior.

Keep shared functionality only where genuinely common (path handling, progress plumbing, common file operations), either in `BaseImportTask` or focused mixins.

## Scope
- Remove core album/singleton behavior branching from shared task methods.
- Make source/candidate properties task-specific and strongly typed.
- Make choice state transitions explicit per task type.
- Restrict methods to relevant task classes (no placeholder/unsupported methods where avoidable).
- Preserve existing plugin hooks and external behavior.

## Acceptance Criteria
- [ ] Album and singleton tasks expose separate, explicit task contracts.
- [ ] Core flow no longer depends on `is_album` checks across shared logic.
- [ ] `set_choice` and `match` typing is explicit and does not rely on `type: ignore`.
- [ ] Sentinel/progress tasks do not inherit unrelated album/singleton behavior.
- [ ] Importer behavior remains backward compatible from user and plugin perspectives.
- [ ] Targeted tests cover album and singleton task flows independently.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.