beetbox / beetbox/beets

Migrate model filesystem helpers to `pathlib.Path`

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

Part of: #1409

Depends on: the library-directory Path migration.

## Problem

Item and album helper methods already describe filesystem behavior, but some still accept or pass byte paths internally. This spreads path conversion through model operations such as reading, writing, moving, destination calculation, playlist generation, and art handling.

## Expected behavior

- Model helper methods that perform filesystem work use `Path` inputs and outputs.
- `Item.from_path`, `Item.read`, `Item.write`, `Item.destination`, `Item.move`, `Item.move_file`, album art helpers, and related utility-facing calls operate on `Path`.
- Event payloads for moved, copied, linked, and art-updated models use `Path` for source and destination paths.
- Tests assert `Path` behavior through `filepath` and `art_filepath`.
- Byte storage remains an internal compatibility detail until the SQL boundary issue lands.

## Suggested fix

Convert the model helper surface before changing the central database type. This lets model behavior become Path-native while keeping existing storage semantics available for compatibility.

## Acceptance criteria

- Public model filesystem helpers accept and return `Path` where practical.
- Existing file move, copy, link, write, art, playlist, and destination tests pass.
- Remaining byte access is explicit and tied to persistence compatibility.
- `poe test` and `poe lint` pass with coverage at or above 80%.

Contributor guide

Open the contributing guide

Research direction

Start with the model helper entry points named in the issue, including Item.from_path, read, write, destination, move, move_file, album art, playlist, and event-related calls. Run the existing file move, copy, link, write, art, playlist, and destination tests first, then use poe test and poe lint; done means the helpers and event payloads are Path-based while byte storage remains explicit for persistence compatibility.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend, cli
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.