Skip to content

Python API

A Python program can use tunedex without the command line:

import tunedex

with tunedex.open_library() as engine:  # the home of the command line, or pass a path
    for track in tunedex.select(engine.store, where=[tunedex.parse_where("bpm>=170")]):
        print(track.artist, track.title)
    plan = engine.plan_scan("/path/to/music")
    print(tunedex.render_text(plan))

The names on this page are the API programs may rely on. Every other module is internal and may change in any release. Importing tunedex does not load the command-line layer.

See Using tunedex from another program for a walk-through.

Opening a library

open_library

open_library(
    home: str | PathLike[str] | None = None,
    *,
    create: bool = False,
    progress: Progress | None = None,
) -> contextlib.AbstractContextManager[Engine]

An engine on the library of home, resolved as the command line does.

Use it as with open_library() as engine:. In a home without a library, the engine plans on an empty in-memory library and creates nothing; pass create to create the library, or apply with Home.apply.

Home dataclass

A tunedex home directory: the library database and the snapshots.

exists property

exists: bool

Whether the library database was created.

engine

engine(
    *,
    create: bool = False,
    progress: Progress | None = None,
) -> Generator[Engine]

An engine on the library.

Without create, a home that has no library yet gets an in-memory one, so planning there creates nothing.

apply

apply(
    engine: Engine,
    plan: Plan,
    confirm: Confirm = assume_yes,
    *,
    progress: WriteProgress | None = None,
) -> ApplyResult

Apply plan, made with engine on this home.

A plan made on the in-memory library of a new home is applied to a library created in the home, so planning first and applying later works in a new home too. progress is told how many audio files were written, for tag writes.

resolve_home

resolve_home(
    path: str | PathLike[str] | None = None,
) -> Path

path, else TUNEDEX_HOME, else the default home; ~ expanded, made absolute.

default_home

default_home() -> Path

The per-OS user data directory for tunedex.

Planning and applying

Engine

Plans and applies changes to the library in store and to export targets.

__init__

__init__(
    store: Store,
    snapshots: SnapshotStore,
    *,
    clock: Callable[[], datetime] | None = None,
    progress: Progress | None = None,
    _write_file: WriteFile = write_atomically,
    _trash: Trash | None = None,
    _write_tags: WriteTags = write_tags,
) -> None

progress is told how many files were seen while walking a folder.

plan_scan

plan_scan(root: str | PathLike[str]) -> Plan

Plan bringing the library in line with the music folder root.

plan_import

plan_import(
    adapter: Adapter,
    location: str | PathLike[str],
    *,
    path_mapping: PathMapping | None = None,
    find_in: str | PathLike[str] | None = None,
) -> Plan

Plan importing what adapter reads at location into the library.

With find_in, tracks whose files are not on this computer are looked for in that folder, and only the found ones are imported.

plan_fix

plan_fix(
    ruleset: RuleSet,
    under: str | PathLike[str] | None = None,
) -> Plan

Plan the edits that ruleset's fixes and rules make to the library's tracks.

With under, only to the tracks under that folder.

find_duplicates

find_duplicates(
    under: str | PathLike[str] | None = None,
) -> tuple[Group, ...]

The library's duplicate groups, each with its suggested track first. Read-only.

With under, only the groups with a track under that folder.

plan_merge

plan_merge(
    decisions: Mapping[GroupKey, Decision] | None = None,
    *,
    keep_files: bool = False,
    under: str | PathLike[str] | None = None,
) -> Plan

Plan merging each duplicate group into one track, trashing the others' files.

decisions choose the track to keep, or skip or ignore a group; the other groups keep their suggested track. keep_files leaves every file in place.

plan_relocate

plan_relocate(folder: str | PathLike[str]) -> Plan

Plan new paths under folder for the tracks whose files are not here.

plan_enrich

plan_enrich(
    services: Services,
    *,
    under: str | PathLike[str] | None = None,
    steps: Steps | None = None,
) -> Plan

Plan tags from MusicBrainz for the tracks AcoustID recognizes by their sound.

This is the only plan that uses the network, through services.

plan_export

plan_export(
    adapter: Adapter,
    location: str | PathLike[str],
    *,
    playlists: Sequence[str] | None = None,
    modified_only: bool = False,
    path_mapping: PathMapping | None = None,
) -> Plan

Plan writing the library's playlists to location.

By default every playlist is written. playlists selects nodes by path, and modified_only selects those changed since the last export to this target.

plan_write_tags

plan_write_tags(
    under: str | PathLike[str] | None = None,
) -> Plan

Plan writing the library's values into the tags of the tracks' files.

With under, only of the tracks under that folder. Files changed since the last scan, missing files and formats that are not written are skipped.

plan_rename

plan_rename(
    pattern: Pattern | str | None = None,
    under: str | PathLike[str] | None = None,
) -> Plan

Plan renaming the tracks' files from pattern, by default {artist} - {title}.

With under, only the files of the tracks under that folder. Files keep their folder and extension; names already taken are skipped, never overwritten.

apply

apply(
    plan: Plan,
    confirm: Confirm,
    *,
    progress: WriteProgress | None = None,
) -> ApplyResult

Apply plan if confirm accepts it. Empty or declined plans write nothing.

progress is told how many audio files were written, for tag writes.

Plan dataclass

Every change a command would make, computed without writing anything.

target instance-attribute

target: str

Snapshot target name: library or <adapter>-<12 hex digits>.

refreshed class-attribute instance-attribute

refreshed: int = 0

File states refreshed without any field change (scans only).

rebased class-attribute instance-attribute

rebased: int = 0

Tracks whose merge base was updated without any field change (imports only).

untouched_nodes class-attribute instance-attribute

untouched_nodes: int = 0

Playlists in the target that the library does not have (exports only).

tags class-attribute instance-attribute

tags: tuple[TrackChange, ...] = ()

Files whose tags are written, with their fields: the file's value, then the library's.

snapshot_bytes property

snapshot_bytes: int

For tag writes, about how much the tag snapshot takes.

ApplyResult dataclass

What applying a plan did: applied, declined, or nothing to do.

Confirm module-attribute

Confirm = Callable[[Plan], bool]

Asked with the plan before applying it; returns whether to go ahead.

assume_yes

assume_yes(plan: Plan) -> bool

A confirmation that accepts every plan, for scripted use.

render_text

render_text(plan: Plan, *, limit: int = 20) -> str

The plan for a terminal, listing at most limit items per section.

to_json

to_json(
    plan: Plan, result: ApplyResult | None = None
) -> dict[str, JSONValue]

The complete plan as a JSON-compatible document.

Browsing

select

select(
    store: Store,
    *,
    where: Sequence[Condition] = (),
    under: str | PathLike[str] | None = None,
    playlists: Sequence[str] = (),
    missing: bool = False,
) -> list[Track]

The tracks every given filter keeps, by artist, title and path, ignoring case.

playlists are paths such as Sets/Friday; a folder stands for every playlist and smartlist under it.

parse_where

parse_where(text: str) -> Condition

The condition text describes; RuleError naming text when it is not valid.

FIELD= with no value matches an empty field and FIELD!= a field with a value. On tags, = and != mean contains and does not contain.

find_track

find_track(store: Store, ref: str) -> Track

The track whose id or path is ref; NotFoundError naming it otherwise.

track_view

track_view(store: Store, ref: str) -> TrackView

The track whose id or path is ref, with its playlists and sources.

TrackView dataclass

One track with where it is used: its playlists and the sources it came from.

present instance-attribute

present: bool

Whether the file is on this computer.

playlists instance-attribute

playlists: tuple[str, ...]

Paths of the playlists and smartlists that hold the track, in tree order.

sources instance-attribute

sources: tuple[str, ...]

The names of the sources the track was imported from, sorted.

status

status(store: Store, snapshots: SnapshotStore) -> Status

The summary that tunedex status shows.

Status dataclass

Counts that summarize the library, its sources and its snapshots.

snapshots instance-attribute

snapshots: tuple[Snapshot, ...]

The newest snapshot of each target, by target name.

playlist_tree

playlist_tree(store: Store) -> list[TreeNode]

Every folder, playlist and smartlist, depth first in tree order.

TreeNode dataclass

A folder, playlist or smartlist in the playlist tree.

tracks instance-attribute

tracks: int | None

Tracks in a playlist or selected by a smartlist; None for folders.

Errors

Every expected failure raises one of these. The command line turns them into the error codes.

PlanError

Bases: Exception

Base class for planning and applying errors.

StaleTargetError

Bases: PlanError

The target changed after the plan was computed; nothing was written.

ApplyFailedError

Bases: PlanError

Applying failed after writing started.

restored says whether the target was put back as it was; when it was not, snapshot names the snapshot to restore by hand.

UnknownPlaylistError

Bases: PlanError

No playlist or folder is at the given path; suggestions holds close names.

AdapterError

Bases: Exception

Base class for adapter failures.

EnrichError

Bases: Exception

Enrichment cannot run: a missing tool, an unreachable service or a bad answer.

RuleError

Bases: ValueError

A rule, condition or fix is invalid; the message names where.

SnapshotError

Bases: Exception

Base class for snapshot failures.

StoreError

Bases: Exception

Base class for store failures.