beetbox / beetbox/beets

Make path utilities accept only `pathlib.Path`

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

Parent issue: #1409

Depends on: all preceding pathlib migration sub-issues.

## Problem

The initial migration keeps path utilities generic over `str`, `bytes`, and other path-like values so callers can move incrementally. Once production code and tests use `Path`, this compatibility becomes unnecessary complexity and allows byte paths to re-enter the codebase.

## Expected behavior

- Change filesystem utility interfaces to accept `Path` and return `Path` wherever they produce paths.
- Remove `AnyStr`, `PathBytes`, and broad `PathLike` annotations from Path-only utility APIs.
- Remove type-directed byte/string branches, implicit encoding, and compatibility conversions from those utilities.
- Replace remaining `os.path` manipulation with equivalent `Path` operations where practical.
- Remove obsolete helpers such as `bytestring_path`, `syspath`, and `normpath` once all call sites and explicit serialization boundaries have replacements.
- Keep encoding and decoding confined to private database, persisted-state, and external-format boundaries.
- Update internal callers, plugins, type annotations, and documentation with the interface changes.

## Acceptance criteria

- Passing `str` or `bytes` to filesystem utilities is unsupported and rejected by static typing.
- Path-producing utilities preserve `Path` without conversion.
- No production filesystem workflow depends on `PathBytes` or byte-specific utility behavior.
- Utility tests use `Path` exclusively, with byte round-trip tests located at explicit boundaries.

Contributor guide

Open the contributing guide

Research direction

Start with parent issue #1409 and the preceding pathlib migration sub-issues to identify the filesystem utilities and their callers. Review the utility tests first, then trace internal callers, plugins, annotations, and documentation. Done means utilities accept and preserve Path values, byte-specific compatibility is removed, and byte round-trip coverage remains only at explicit boundaries.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.