beetbox / beetbox/beets

Migrate byte-only path contracts to `pathlib.Path`

Open
#6,809 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

Depends on: the generic path utilities and initial test-suite migration sub-issues.

Child issues:

- Migrate artwork and media path APIs to `Path`.
- Make `Library.directory` and music-directory context Path-based.
- Migrate importer path APIs and persisted state to `Path`, including `sorted_walk` and `albums_in_dir`.
- Migrate model filesystem helpers to `Path`.
- Replace runtime `item.path` and `album.artpath` consumers with `filepath` and `art_filepath`.
- Use `Path` in models while keeping SQL path storage as bytes.

## Problem

Core runtime interfaces still expose filesystem paths as `bytes`, propagating encoding and byte-valued model fields through import, artwork, plugin, and UI code. The remaining tests therefore cannot adopt `Path`.

## Affected areas

- Library/database integration: `Library.directory`, music-directory context, path queries, and byte-valued model backing fields.
- Import pipeline: `ImportSession`, task classes and factories, and persisted `ImportState`.
- Artwork/media utilities: `fetchart.Candidate.path`, `ArtResizer`, extension handling, and shared art helpers.
- Plugins/UI: direct model-field access, importer paths, and path configuration values.

## Expected behavior

- Use `Path` for filesystem paths in runtime and plugin APIs.
- Prefer `LibModel.filepath` and `Album.art_filepath`; access their byte-valued backing fields only at the database compatibility boundary.
- Migrate importer state and APIs, artwork utilities, plugin state, and event payloads to `Path`, while decoding legacy state.
- Encode or decode only at explicit boundaries. SQLite path BLOBs and binary file or URI content remain bytes.
- Preserve undecodable filesystem paths through surrogate-escape round trips.

## Acceptance criteria

- Direct `LibModel.path` and `Album.artpath` use is limited to persistence and compatibility code.
- Filesystem, importer, and artwork APIs accept or return `Path` without caller-side encoding.
- Art, importer, core, and plugin tests migrate with their production interfaces.
- Boundary tests cover database round trips, legacy state, undecodable paths, and platform behavior.
- `poe test` and `poe lint` pass with coverage at or above 80%.

Contributor guide

Open the contributing guide

Research direction

Start with the generic path utilities and initial test-suite migration sub-issues, then trace the listed Library, ImportSession, ImportState, fetchart, ArtResizer, model, plugin, and UI areas. Use the acceptance criteria and boundary-test requirements to define completion, including Path-based APIs, legacy-state handling, undecodable paths, and passing poe test and poe lint with at least 80% coverage.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend, cli, database
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.