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

Extracts key track data from a remote API JSON response.

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

Bases: MusifyCollection, Generic

Generic class for storing a collection of remote objects.

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

Bases: RemoteCollection, RemoteItem, 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.

abstractmethod async 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 (APIInputValueSingle[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, 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

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

async 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

async 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, 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, 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