Collection

Implements all collection types for a local library.

Classes:

LocalCollection([remote_wrangler])	Generic class for storing a collection of local tracks.
BasicLocalCollection(name, tracks[, ...])
LocalCollectionFiltered(tracks[, name, ...])	Generic class for storing and filtering on a collection of local tracks with methods for enriching the attributes of this object from the attributes of the collection of tracks
LocalFolder([tracks, name, remote_wrangler])	Object representing a collection of tracks in a folder on the local drive.
LocalAlbum(tracks[, name, remote_wrangler])	Object representing a collection of tracks of an album.
LocalArtist(tracks[, name, remote_wrangler])	Object representing a collection of tracks by a single artist.
LocalGenres(tracks[, name, remote_wrangler])	Object representing a collection of tracks within a genre.

class musify.libraries.local.collection.LocalCollection(remote_wrangler=None)

Bases: MusifyCollection, Generic

Generic class for storing a collection of local tracks.

Parameters:

remote_wrangler (RemoteDataWrangler (default: None)) – Optionally, provide a RemoteDataWrangler object for processing URIs on items. If given, the wrangler can be used when calling __get_item__ to get an item from the collection from its URI.

Attributes:

items	The tracks in this collection
tracks	The tracks in this collection
track_total	The total number of tracks in this collection
last_modified	Timestamp of the last modified track in this collection
last_added	Timestamp of the track last added to the library in this collection
last_played	Timestamp of the last played track in this collection
play_count	Total number of plays of all tracks in this collection
logger	The MusifyLogger for this object
remote_wrangler	A RemoteDataWrangler object for processing remote data

Methods:

save_tracks([tags, replace, dry_run])	Saves the tags of all tracks in this collection.
log_save_tracks_result(results[, log_values])	Log stats from the results of a save_tracks operation
merge_tracks(tracks[, tags])	Merge this collection with another collection or list of items by performing an inner join on a given set of tags

property items: list[T]

The tracks in this collection

abstract property tracks: list[T]

The tracks in this collection

property track_total: int

The total number of tracks in this collection

property last_modified: datetime

Timestamp of the last modified track in this collection

property last_added: datetime | None

Timestamp of the track last added to the library in this collection

property last_played: datetime | None

Timestamp of the last played track in this collection

property play_count: int

Total number of plays of all tracks in this collection

logger: MusifyLogger

The MusifyLogger for this object

remote_wrangler

A RemoteDataWrangler object for processing remote data

async save_tracks(tags=LocalTrackField.ALL, replace=False, dry_run=True)

Saves the tags of all tracks in this collection. Use arguments from LocalTrack.save()

Parameters:

• tags (UnitIterable[LocalTrackField] (default: <LocalTrackField.ALL: 0>)) – Tags to be updated.

• replace (bool (default: False)) – Destructively replace tags in each file.

• dry_run (bool (default: True)) – Run function, but do not modify the file on the disk.

Returns:

dict[T, SyncResultTrack] – A map of the LocalTrack saved to its result as a SyncResultTrack object only for tracks that were saved or would have been saved in the case of a dry run.

log_save_tracks_result(results, log_values=False)

Log stats from the results of a save_tracks operation

Parameters:

• results (Mapping[T, SyncResultTrack]) – The results to log.

• log_values (bool (default: False)) – Log the values of the track’s tags.

Return type:

None

merge_tracks(tracks, tags=Fields.ALL)

Merge this collection with another collection or list of items by performing an inner join on a given set of tags

Parameters:

• tracks (Collection[Track]) – List of items or MusifyCollection to merge with

• tags (GenericAlias[TagField] (default: <Fields.ALL: 0>)) – List of tags to merge on.

Return type:

None

class musify.libraries.local.collection.BasicLocalCollection(name, tracks, remote_wrangler=None)

Bases: LocalCollection, Generic

Attributes:

name	The name of this collection
tracks	The tracks in this collection
length	Total duration of all items in this collection in seconds

property name

The name of this collection

property tracks: list[T]

The tracks in this collection

property length

Total duration of all items in this collection in seconds

class musify.libraries.local.collection.LocalCollectionFiltered(tracks, name=None, remote_wrangler=None)

Bases: LocalCollection, Generic

Generic class for storing and filtering on a collection of local tracks with methods for enriching the attributes of this object from the attributes of the collection of tracks

Parameters:

• tracks (Collection[T]) – A list of loaded tracks.

• name (str | None (default: None)) – The name of this collection. If given, the object only stores tracks that match the name given on the attribute of this object. If None, the list of tracks given are taken to be all the tracks contained in this collection.

• remote_wrangler (RemoteDataWrangler (default: None)) – Optionally, provide a RemoteDataWrangler object for processing URIs on tracks. If given, the wrangler can be used when calling __get_item__ to get an item from the collection from its URI.

Raises:

LocalCollectionError – If the given tracks contain more than one unique value for the attribute of this collection when name is None.

Attributes:

name	The name of the key property of this collection
tracks	The tracks in this collection
artists	List of artists ordered by frequency of appearance on the tracks in this collection

property name

The name of the key property of this collection

property tracks

The tracks in this collection

property artists: list[str]

List of artists ordered by frequency of appearance on the tracks in this collection

class musify.libraries.local.collection.LocalFolder(tracks=(), name=None, remote_wrangler=None)

Bases: LocalCollectionFiltered[LocalTrack], Folder[LocalTrack]

Object representing a collection of tracks in a folder on the local drive.

Parameters:

• tracks (Collection[LocalTrack] (default: ())) – A list of loaded tracks.

• name (str | None (default: None)) – The name of this folder. If given, the object only stores tracks that match the folder name given. If None, the list of tracks given are taken to be all the tracks contained in this folder.

• remote_wrangler (RemoteDataWrangler (default: None)) – Optionally, provide a RemoteDataWrangler object for processing URIs on tracks. If given, the wrangler can be used when calling __get_item__ to get an item from the collection from its URI.

Raises:

LocalCollectionError – If the given tracks contain more than one unique value for folder when name is None.

Attributes:

albums	List of albums ordered by frequency of appearance on the tracks in this folder
genres	List of genres ordered by frequency of appearance on the tracks in this collection
compilation	Folder is a compilation if over 50% of tracks are marked as compilation

Methods:

load_folder(path[, remote_wrangler])

Load tracks in a folder at the given path.

property albums

List of albums ordered by frequency of appearance on the tracks in this folder

property genres: list[str]

List of genres ordered by frequency of appearance on the tracks in this collection

property compilation

Folder is a compilation if over 50% of tracks are marked as compilation

async classmethod load_folder(path, remote_wrangler=None)

Load tracks in a folder at the given path.

Parameters:

• path (str | Path | None) – The path of the folder to load.

• remote_wrangler (RemoteDataWrangler (default: None)) – Optionally, provide a RemoteDataWrangler object for processing URIs on tracks. If given, the wrangler can be used when calling __get_item__ to get an item from the collection from its URI.

Return type:

Self

class musify.libraries.local.collection.LocalAlbum(tracks, name=None, remote_wrangler=None)

Bases: LocalCollectionFiltered[LocalTrack], Album[LocalTrack]

Object representing a collection of tracks of an album.

Parameters:

• tracks (Collection[LocalTrack]) – A list of loaded tracks.

• name (str | None (default: None)) – The name of this album. If given, the object only stores tracks that match the album name given. If None, the list of tracks given are taken to be all the tracks for this album.

• remote_wrangler (RemoteDataWrangler (default: None)) – Optionally, provide a RemoteDataWrangler object for processing URIs on tracks. If given, the wrangler can be used when calling __get_item__ to get an item from the collection from its URI.

Raises:

LocalCollectionError – If the given tracks contain more than one unique value for album when name is None.

Attributes:

album_artist	The most common artist on this album
genres	List of genres ordered by frequency of appearance on the tracks in this collection
date	A date object representing the release date of this album.
year	The most common release year of all tracks on this album
month	The most common release month of all tracks on this album
day	The most common release day of all tracks on this album
compilation	Album is a compilation if over 50% of tracks are marked as compilation
image_links	The images associated with this album in the form {<image name/type>: <image link>}
has_image	Does this album have an image
rating	Average rating of all tracks on this album

property album_artist

The most common artist on this album

property genres: list[str]

List of genres ordered by frequency of appearance on the tracks in this collection

property date

A date object representing the release date of this album. Determined by the most common release date of all tracks on this album.

property year

The most common release year of all tracks on this album

property month

The most common release month of all tracks on this album

property day

The most common release day of all tracks on this album

property compilation

Album is a compilation if over 50% of tracks are marked as compilation

property image_links

The images associated with this album in the form {<image name/type>: <image link>}

property has_image

Does this album have an image

property rating

Average rating of all tracks on this album

class musify.libraries.local.collection.LocalArtist(tracks, name=None, remote_wrangler=None)

Bases: LocalCollectionFiltered[LocalTrack], Artist[LocalTrack]

Object representing a collection of tracks by a single artist.

Parameters:

• tracks (Collection[LocalTrack]) – A list of loaded tracks.

• name (str | None (default: None)) – The name of this artist. If given, the object only stores tracks that match the artist name given. If None, the list of tracks given are taken to be all the tracks by this artist.

• remote_wrangler (RemoteDataWrangler (default: None)) – Optionally, provide a RemoteDataWrangler object for processing URIs on tracks. If given, the wrangler can be used when calling __get_item__ to get an item from the collection from its URI.

Raises:

LocalCollectionError – If the given tracks contain more than one unique value for artist when name is None.

Attributes:

albums	List of albums ordered by frequency of appearance on the tracks by this artist
genres	List of genres ordered by frequency of appearance on the tracks in this collection
rating	Average rating of all tracks by this artist

property albums

List of albums ordered by frequency of appearance on the tracks by this artist

property genres: list[str]

List of genres ordered by frequency of appearance on the tracks in this collection

property rating

Average rating of all tracks by this artist

class musify.libraries.local.collection.LocalGenres(tracks, name=None, remote_wrangler=None)

Bases: LocalCollectionFiltered[LocalTrack], Genre[LocalTrack]

Object representing a collection of tracks within a genre.

Parameters:

• tracks (Collection[LocalTrack]) – A list of loaded tracks.

• name (str | None (default: None)) – The name of this genre. If given, the object only stores tracks that match the genre name given. If None, the list of tracks given are taken to be all the tracks within this genre.

• remote_wrangler (RemoteDataWrangler (default: None)) – Optionally, provide a RemoteDataWrangler object for processing URIs on tracks. If given, the wrangler can be used when calling __get_item__ to get an item from the collection from its URI.

Raises:

LocalCollectionError – If the given tracks contain more than one unique value for genre when name is None.

Attributes:

albums	List of albums ordered by frequency of appearance on the tracks for this genre
related_genres	List of related genres ordered by frequency of appearance on the tracks for this genre

property albums

List of albums ordered by frequency of appearance on the tracks for this genre

property related_genres: list[str]

List of related genres ordered by frequency of appearance on the tracks for this genre