Object

Functionality relating to generic remote objects.

Implements core MusifyItem and MusifyCollection classes for remote object types.

Classes:

`RemoteTrack`(response[, api, skip_checks])	Extracts key `track` data from a remote API JSON response.
`RemoteCollection`()	Generic class for storing a collection of remote objects.
`RemoteCollectionLoader`(response[, api, ...])	Generic class for storing a collection of remote objects that can be loaded from an API response.
`SyncResultRemotePlaylist`(start, added, ...)	Stores the results of a sync with a remote playlist.
`RemotePlaylist`(response[, api, skip_checks])	Extracts key `playlist` data from a remote API JSON response.
`RemoteAlbum`(response[, api, skip_checks])	Extracts key `album` data from a remote API JSON response.
`RemoteArtist`(response[, api, skip_checks])	Extracts key `artist` data from a remote API JSON response.

class musify.libraries.remote.core.object.RemoteTrack(response, api=None, skip_checks=False)

Bases: Track, RemoteItem, ABC

Extracts key track data from a remote API JSON response.

class musify.libraries.remote.core.object.RemoteCollection

Bases: MusifyCollection, ABC, Generic

Generic class for storing a collection of remote objects.

class musify.libraries.remote.core.object.RemoteCollectionLoader(response, api=None, skip_checks=False)

Bases: RemoteObject, RemoteCollection, ABC, Generic

Generic class for storing a collection of remote objects that can be loaded from an API response.

Methods:

load(value, api[, items])

Generate a new object, calling all required endpoints to get a complete set of data for this item type.

abstract classmethod load(value, api, items=(), *args, **kwargs)

Generate a new object, calling all required endpoints to get a complete set of data for this item type.

value may be:

A string representing a URL/URI/ID.
A remote API JSON response for a collection with a valid ID value under an id key.
An object of the same type as this collection. The remote API JSON response will be used to load a new object.

You may also provide a set of kwargs relating that will extend aspects of the response before using it to initialise a new object. See reload() for possible extensions.

Parameters:

value (str | Mapping[str, Any] | Self) – The value representing some remote collection. See description for allowed value types.
api (RemoteAPI) – An authorised API object to load the object from.
items (Iterable[T] (default: ())) – Optionally, give a list of available items to build a response for this collection. In doing so, the method will first try to find the API responses for the items of this collection in the given list before calling the API for any items not found there. This helps reduce the number of API calls made on initialisation.

Return type:

Self

class musify.libraries.remote.core.object.SyncResultRemotePlaylist(start, added, removed, unchanged, difference, final)

Bases: Result

Stores the results of a sync with a remote playlist.

Attributes:

`start`	The total number of tracks in the playlist before the sync.
`added`	The number of tracks added to the playlist.
`removed`	The number of tracks removed from the playlist.
`unchanged`	The number of tracks that were in the playlist before and after the sync.
`difference`	The difference between the total number tracks in the playlist from before and after the sync.
`final`	The total number of tracks in the playlist after the sync.

start: int: The total number of tracks in the playlist before the sync.

added: int: The number of tracks added to the playlist.

removed: int: The number of tracks removed from the playlist.

unchanged: int: The number of tracks that were in the playlist before and after the sync.

difference: int: The difference between the total number tracks in the playlist from before and after the sync.

final: int: The total number of tracks in the playlist after the sync.

class musify.libraries.remote.core.object.RemotePlaylist(response, api=None, skip_checks=False)

Bases: Playlist, RemoteCollectionLoader, ABC, Generic

Extracts key playlist data from a remote API JSON response.

Attributes:

`owner_id`	The ID of the owner of this playlist
`owner_name`	The name of the owner of this playlist
`followers`	The number of followers this playlist has
`date_added`	A map of `{<URI>: <date>}` for each item for when that item was added to the playlist
`writeable`	Is this playlist writeable i.e. can this program modify it.

Methods:

`create`(api, name[, public, collaborative])	Create an empty playlist for the current user with the given name and initialise and return a new RemotePlaylist object from this new playlist.
`delete`()	Unfollow/delete the current playlist and clear the stored response for this object.
`sync`([items, kind, reload, dry_run])	Synchronise this playlist object's items with the remote playlist it is associated with.

abstract property owner_id: str: The ID of the owner of this playlist

abstract property owner_name: str: The name of the owner of this playlist

abstract property followers: int: The number of followers this playlist has

abstract property date_added: dict[str, datetime]: A map of {<URI>: <date>} for each item for when that item was added to the playlist

property writeable: bool: Is this playlist writeable i.e. can this program modify it

classmethod create(api, name, public=True, collaborative=False)

Create an empty playlist for the current user with the given name and initialise and return a new RemotePlaylist object from this new playlist.

Parameters:

api (RemoteAPI) – An API object with authorised access to a remote User to create playlists for.
name (str) – Name of playlist to create.
public (bool (default: True)) – Set playlist availability as public if True and private if False.
collaborative (bool (default: False)) – Set playlist to collaborative i.e. other users may edit the playlist.

Returns:

Self – RemotePlaylist object for the generated playlist.

delete()

Unfollow/delete the current playlist and clear the stored response for this object. WARNING: This function will destructively modify your remote playlists.

Return type:: None

sync(items=(), kind='new', reload=True, dry_run=True)

Synchronise this playlist object’s items with the remote playlist it is associated with.

Sync 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:

items (Iterable[MusifyItem] (default: ())) – Provide an item collection or list of items to synchronise to the remote playlist. Use the currently loaded tracks 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:

SyncResultRemotePlaylist – The results of the sync as a SyncResultRemotePlaylist object.

class musify.libraries.remote.core.object.RemoteAlbum(response, api=None, skip_checks=False)

Bases: Album, RemoteCollectionLoader, ABC, Generic

Extracts key album data from a remote API JSON response.

Attributes:

artists

List of artists ordered by frequency of appearance on the tracks on this album

abstract property artists: list[RemoteArtist[T]]: List of artists ordered by frequency of appearance on the tracks on this album

class musify.libraries.remote.core.object.RemoteArtist(response, api=None, skip_checks=False)

Bases: Artist, RemoteCollectionLoader, ABC, Generic

Extracts key artist data from a remote API JSON response.

Attributes:

`tracks`	The tracks by this artist
`artists`	List of other artists ordered by frequency of appearance on the albums by this artist
`albums`	List of albums ordered by frequency of appearance on the tracks by this artist
`track_total`	The total number of tracks by this artist
`image_links`	The images associated with this artist in the form `{<image name/type>: <image link>}`
`has_image`	Does this artist have images associated with them
`length`	Total duration of all tracks by this artist in seconds

property tracks: list[T]: The tracks by this artist

property artists: List of other artists ordered by frequency of appearance on the albums by this artist

abstract property albums: list[RemoteAlbum[T]]: List of albums ordered by frequency of appearance on the tracks by this artist

property track_total: The total number of tracks by this artist

abstract property image_links: dict[str, str]: The images associated with this artist in the form {<image name/type>: <image link>}

property has_image: bool: Does this artist have images associated with them

property length: Total duration of all tracks by this artist in seconds