Migrate byte-only path contracts to `pathlib.Path`
Author: snejusCreated Jun 30, 2026Updated Sep 1, 2026
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.directoryand music-directory context Path-based. - Migrate importer path APIs and persisted state to
Path, includingsorted_walkandalbums_in_dir. - Migrate model filesystem helpers to
Path. - Replace runtime
item.pathandalbum.artpathconsumers withfilepathandart_filepath. - Use
Pathin 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 persistedImportState. - 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
Pathfor filesystem paths in runtime and plugin APIs. - Prefer
LibModel.filepathandAlbum.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.pathandAlbum.artpathuse is limited to persistence and compatibility code. - Filesystem, importer, and artwork APIs accept or return
Pathwithout 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 testandpoe lintpass with coverage at or above 80%.
Source: beetbox/beets