mirror of
https://github.com/beetbox/beets.git
synced 2025-12-06 08:39:17 +01:00
64 lines
2 KiB
ReStructuredText
64 lines
2 KiB
ReStructuredText
Handling Paths
|
|
==============
|
|
|
|
``pathlib`` provides a clean, cross-platform API for working with filesystem
|
|
paths.
|
|
|
|
Use the ``.filepath`` property on ``Item`` and ``Album`` library objects to
|
|
access paths as ``pathlib.Path`` objects. This produces a readable, native
|
|
representation suitable for printing, logging, or further processing.
|
|
|
|
Normalize paths using ``Path(...).expanduser().resolve()``, which expands ``~``
|
|
and resolves symlinks.
|
|
|
|
Cross-platform differences—such as path separators, Unicode handling, and
|
|
long-path support (Windows) are automatically managed by ``pathlib``.
|
|
|
|
When storing paths in the database, however, convert them to bytes with
|
|
``bytestring_path()``. Paths in Beets are currently stored as bytes, although
|
|
there are plans to eventually store ``pathlib.Path`` objects directly. To access
|
|
media file paths in their stored form, use the ``.path`` property on ``Item``
|
|
and ``Album``.
|
|
|
|
Legacy utilities
|
|
----------------
|
|
|
|
Historically, Beets used custom utilities to ensure consistent behavior across
|
|
Linux, macOS, and Windows before ``pathlib`` became reliable:
|
|
|
|
- ``syspath()``: worked around Windows Unicode and long-path limitations by
|
|
converting to a system-safe string (adding the ``\\?\`` prefix where needed).
|
|
- ``normpath()``: normalized slashes and removed ``./`` or ``..`` parts but did
|
|
not expand ``~``.
|
|
- ``bytestring_path()``: converted paths to bytes for database storage (still
|
|
used for that purpose today).
|
|
- ``displayable_path()``: converted byte paths to Unicode for display or
|
|
logging.
|
|
|
|
These functions remain safe to use in legacy code, but new code should rely
|
|
solely on ``pathlib.Path``.
|
|
|
|
Examples
|
|
--------
|
|
|
|
Old style
|
|
|
|
.. code-block:: python
|
|
|
|
displayable_path(item.path)
|
|
normpath("~/Music/../Artist")
|
|
syspath(path)
|
|
|
|
New style
|
|
|
|
.. code-block:: python
|
|
|
|
item.filepath
|
|
Path("~/Music/../Artist").expanduser().resolve()
|
|
Path(path)
|
|
|
|
When storing paths in the database
|
|
|
|
.. code-block:: python
|
|
|
|
path_bytes = bytestring_path(Path("/some/path/to/file.mp3"))
|