Migrate byte-only path contracts to `pathlib.Path`
- 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
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