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.
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.
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.
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.
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 ¶
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.