Object

Inheritance diagram of musify.libraries.remote.core.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.

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

SelfRemotePlaylist 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

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