Library

Functionality relating to a generic remote library.

Classes:

RemoteLibrary(api[, playlist_filter])

Represents a remote library, providing various methods for manipulating tracks and playlists across an entire remote library collection.

class musify.libraries.remote.core.library.RemoteLibrary(api, playlist_filter=())

Bases: RemoteCollection, Library, ABC, Generic

Represents a remote library, providing various methods for manipulating tracks and playlists across an entire remote library collection.

Parameters:

• api (TypeVar(A, bound= RemoteAPI)) – The instantiated and authorised API object for this source type.

• playlist_filter (Union[Collection[str], Filter[str]] (default: ())) – An optional Filter to apply or collection of playlist names to include when loading playlists. Playlist names will be passed to this filter to limit which playlists are loaded.

Attributes:

factory	Stores the key object classes for a remote source.
api	Authorised API object for making authenticated calls to a user's library
name	The username associated with this library
id	The user ID associated with this library
playlists	The playlists in this library
tracks	All user's saved tracks
artists	All user's saved artists
albums	All user's saved albums
logger	The MusifyLogger for this object
playlist_filter	Filter to filter out the playlists loaded by name.

Methods:

extend(_RemoteLibrary__items[, allow_duplicates])	Append many items to the items in this collection
load()	Loads all data from the remote API for this library and log results.
load_playlists()	Load all playlists from the API that match the filter rules in this library.
log_playlists()	Log stats on currently loaded playlists
load_tracks()	Load all user's saved tracks from the API.
enrich_tracks(*_, **__)	Call API to enrich elements of track objects improving metadata coverage.
log_tracks()	Log stats on currently loaded tracks
load_saved_albums()	Load all user's saved albums from the API.
enrich_saved_albums(*_, **__)	Call API to enrich elements of user's saved album objects improving metadata coverage.
log_albums()	Log stats on currently loaded albums
load_saved_artists()	Load all user's saved artists from the API.
enrich_saved_artists(*_, **__)	Call API to enrich elements of user's saved artist objects improving metadata coverage.
log_artists()	Log stats on currently loaded artists
backup_playlists()	Produce a backup map of <playlist name>: [<URIs] for all playlists in this library which can be saved to JSON for backup purposes.
restore_playlists(playlists[, dry_run])	Restore playlists from a backup to loaded playlist objects.
sync([playlists, kind, reload, dry_run])	Synchronise this playlist object with the remote playlist it is associated with.
log_sync(results)	Log stats from the results of a sync operation

property factory: RemoteObjectFactory

Stores the key object classes for a remote source.

property api

Authorised API object for making authenticated calls to a user’s library

property name

The username associated with this library

property id

The user ID associated with this library

property playlists: dict[str, PL]

The playlists in this library

property tracks: list[TR]

All user’s saved tracks

property artists: list[AR]

All user’s saved artists

property albums: list[AL]

All user’s saved albums

logger: MusifyLogger

The MusifyLogger for this object

playlist_filter: Filter[str]

Filter to filter out the playlists loaded by name.

extend(_RemoteLibrary__items, allow_duplicates=True)

Append many items to the items in this collection

Return type:

None

load()

Loads all data from the remote API for this library and log results.

Return type:

None

load_playlists()

Load all playlists from the API that match the filter rules in this library. Also loads all their tracks. WARNING: Overwrites any currently loaded playlists.

Return type:

None

log_playlists()

Log stats on currently loaded playlists

Return type:

None

load_tracks()

Load all user’s saved tracks from the API. Updates currently loaded tracks in-place or appends if not already loaded.

Return type:

None

enrich_tracks(*_, **__)

Call API to enrich elements of track objects improving metadata coverage. This is an optionally implementable method. Defaults to doing nothing.

Return type:

None

log_tracks()

Log stats on currently loaded tracks

Return type:

None

load_saved_albums()

Load all user’s saved albums from the API. Updates currently loaded albums in-place or appends if not already loaded.

Return type:

None

enrich_saved_albums(*_, **__)

Call API to enrich elements of user’s saved album objects improving metadata coverage. This is an optionally implementable method. Defaults to doing nothing.

Return type:

None

log_albums()

Log stats on currently loaded albums

Return type:

None

load_saved_artists()

Load all user’s saved artists from the API. Updates currently loaded artists in-place or appends if not already loaded.

Return type:

None

enrich_saved_artists(*_, **__)

Call API to enrich elements of user’s saved artist objects improving metadata coverage. This is an optionally implementable method. Defaults to doing nothing.

Return type:

None

log_artists()

Log stats on currently loaded artists

Return type:

None

backup_playlists()

Produce a backup map of <playlist name>: [<URIs] for all playlists in this library which can be saved to JSON for backup purposes.

Return type:

dict[str, list[str]]

restore_playlists(playlists, dry_run=True)

Restore playlists from a backup to loaded playlist objects.

This function does not sync the updated playlists with the remote library.

When dry_run is False, this function does create new playlists on the remote library for playlists given that do not exist in this Library.

Parameters:

• playlists (Library | Collection[Playlist] | Mapping[str, Iterable[Track]] | Mapping[str, Iterable[str]]) – Values that represent the playlists to restore from.

• dry_run (bool (default: True)) – When True, do not create playlists and just skip any playlists that are not already currently loaded.

Return type:

None

sync(playlists=None, kind='new', reload=True, dry_run=True)

Synchronise this playlist object with the remote playlist it is associated with.

Clear options:

• ‘new’: Do not clear any items from the remote playlist and only add any tracks

  from this playlist object not currently in the remote playlist.

• ‘refresh’: Clear all items from the remote playlist first, then add all items from this playlist object.

• ‘sync’: Clear all items not currently in this object’s items list, then add all tracks

  from this playlist object not currently in the remote playlist.

Parameters:

• playlists (Library | Mapping[str, Iterable[MusifyItem]] | Collection[Playlist] | None (default: None)) – Provide a library, map of playlist name to playlist or collection of playlists to synchronise to the remote library. Use the currently loaded playlists in this object if not given.

• kind (Literal['new', 'refresh', 'sync'] (default: 'new')) – Sync option for the remote playlist. See description.

• reload (bool (default: True)) – When True, once synchronisation is complete, reload this RemotePlaylist object to reflect the changes on the remote playlist if enabled. Skip if False.

• dry_run (bool (default: True)) – Run function, but do not modify the remote playlists at all.

Returns:

dict[str, SyncResultRemotePlaylist] – Map of playlist name to the results of the sync as a SyncResultRemotePlaylist object.

log_sync(results)

Log stats from the results of a sync operation

Return type:

None