library

Data classes to hold standardized metadata about songs, artists, and albums.

CLASS	DESCRIPTION
AlbumType	Classification of album release types.
ResourceType	Enum representing the type of resource being handled. The UNKNOWN value is used when a provider has IDs that are
BaseLibraryItem	Base class for all library item types.
User	Base class for a user of a music library.
Artist	Holds info about an artist.
Album	Holds info about an album. cover should be a string containing a valid URL.
Song	Holds info about a song.
Playlist	Holds info about a playlist.

__all__ module-attribute

__all__ = [
    "Album",
    "AlbumType",
    "Artist",
    "ResourceType",
    "Song",
    "User",
    "Playlist",
    "BaseLibraryItem",
]

AlbumType

Bases: Enum

Classification of album release types.

ALBUM class-attribute instance-attribute

ALBUM = auto()

A full-length album release.

SINGLE class-attribute instance-attribute

SINGLE = auto()

A single release. Usually one track, but some releases also contains more tracks for instrumental versions, remixes, etc.

COMPILATION class-attribute instance-attribute

COMPILATION = auto()

A compilation or "greatest hits" collection.

ResourceType

Bases: Enum

Enum representing the type of resource being handled. The UNKNOWN value is used when a provider has IDs that are valid for multiple types, but can't determine which exact type.

SONG class-attribute instance-attribute

SONG = auto()

ALBUM class-attribute instance-attribute

ALBUM = auto()

ARTIST class-attribute instance-attribute

ARTIST = auto()

PLAYLIST class-attribute instance-attribute

PLAYLIST = auto()

USER class-attribute instance-attribute

USER = auto()

UNKNOWN class-attribute instance-attribute

UNKNOWN = auto()

BaseLibraryItem dataclass

BaseLibraryItem()

Base class for all library item types.

Provides common functionality for converting provider-specific data into standardized Downmixer types. Subclasses should set _resource_type and override from_provider() in their provider-specific adapter classes.

get_resource_type classmethod

get_resource_type() -> ResourceType

Returns the resource type for this class.

Source code in src/downmixer/types/library.py

@classmethod
def get_resource_type(cls) -> ResourceType:
    """Returns the resource type for this class."""
    return cls._resource_type

from_provider classmethod

from_provider(data: Any, extra_data: dict = None)

Create an instance of this class from data coming from a provider's API.

PARAMETER	DESCRIPTION
data	Data from the provider's API. TYPE: Any
extra_data	Extra data from provider's API to be used to make instances of this class. TYPE: dict DEFAULT: None

RETURNS	DESCRIPTION
	An instance of this class.

Source code in src/downmixer/types/library.py

@classmethod
def from_provider(cls, data: Any, extra_data: dict = None):
    """Create an instance of this class from data coming from a provider's API.

    Args:
        data (Any): Data from the provider's API.
        extra_data (dict, optional): Extra data from provider's API to be used to make instances of this class.

    Returns:
         An instance of this class.
    """
    pass

from_provider_list classmethod

from_provider_list(
    data: list[Any], extra_data: dict = None
) -> list

Creates a list of instances of this class from a list of objects with data coming from a provider's API.

PARAMETER	DESCRIPTION
data	List of objects with data from the provider's API. TYPE: list[Any]
extra_data	Extra data from provider's API to be used to make instances of this class. TYPE: dict DEFAULT: None

RETURNS	DESCRIPTION
list	A list with instances of this class.

Source code in src/downmixer/types/library.py

@classmethod
def from_provider_list(cls, data: list[Any], extra_data: dict = None) -> list:
    """Creates a list of instances of this class from a list of objects with data coming from a provider's API.

    Args:
        data (list[Any]): List of objects with data from the provider's API.
        extra_data (dict, optional): Extra data from provider's API to be used to make instances of this class.

    Returns:
        A list with instances of this class.
    """
    return [cls.from_provider(x, extra_data) for x in data]

to_dict

to_dict() -> dict

Returns this class as a dict. Useful for serialization. Uses the native Python dataclass.asdict() function.

RETURNS	DESCRIPTION
dict	Dictionary with a deep copy of the object. TYPE: dict

Source code in src/downmixer/types/library.py

def to_dict(self) -> dict:
    """Returns this class as a dict. Useful for serialization.
    Uses the native Python `dataclass.asdict()` function.

    Returns:
        dict: Dictionary with a deep copy of the object.
    """
    return asdict(self)

from_dict classmethod

from_dict(data: dict) -> 'BaseLibraryItem'

Returns an instance of this class with parameters from the given dictionary.

PARAMETER	DESCRIPTION
data	Dictionary containing all the parameters of this object and their values. TYPE: dict

RETURNS	DESCRIPTION
'BaseLibraryItem'	An instance of this class.

Source code in src/downmixer/types/library.py

@classmethod
def from_dict(cls, data: dict) -> "BaseLibraryItem":
    """Returns an instance of this class with parameters from the given dictionary.

    Args:
        data: Dictionary containing all the parameters of this object and their values.

    Returns:
        An instance of this class.
    """
    return cls(**data)

User dataclass

User(
    id: str = None,
    name: str | None = None,
    handle: str | None = None,
)

Bases: BaseLibraryItem

Base class for a user of a music library.

id class-attribute instance-attribute

id: str = None

name class-attribute instance-attribute

name: str | None = None

handle class-attribute instance-attribute

handle: str | None = None

__hash__

__hash__()

Source code in src/downmixer/types/library.py

def __hash__(self):
    if self.id:
        return hash(self.id)
    elif self.handle:
        return hash(self.handle)
    else:
        return hash(self.name)

__str__

__str__()

Source code in src/downmixer/types/library.py

def __str__(self):
    return f"{self.name} ({self.id})" if self.name else self.id

Artist dataclass

Artist(
    name: str,
    images: list[str] | None = None,
    genres: list[str] | None = None,
    id: str | None = None,
    url: str | None = None,
)

Bases: BaseLibraryItem

Holds info about an artist.

name instance-attribute

name: str

images class-attribute instance-attribute

images: list[str] | None = None

genres class-attribute instance-attribute

genres: list[str] | None = None

id class-attribute instance-attribute

id: str | None = None

url class-attribute instance-attribute

url: str | None = None

slug

slug() -> 'Artist'

Returns self with sluggified text attributes.

Source code in src/downmixer/types/library.py

def slug(self) -> "Artist":
    """Returns self with sluggified text attributes."""
    return Artist(
        name=slugify(self.name),
        images=self.images,
        genres=[slugify(x) for x in self.genres] if self.genres else None,
        id=self.id,
        url=self.url,
    )

__hash__

__hash__()

Source code in src/downmixer/types/library.py

def __hash__(self):
    if self.id:
        return hash(self.id)
    else:
        return hash(self.name)

__str__

__str__()

Source code in src/downmixer/types/library.py

def __str__(self):
    return self.name

Album dataclass

Album(
    name: str,
    available_markets: list[str] | None = None,
    artists: list[Artist] | None = None,
    date: str | None = None,
    tracks: list["Song"] | None = None,
    track_count: int | None = None,
    cover: str | None = None,
    upc: str | None = None,
    id: str | None = None,
    url: str | None = None,
)

Bases: BaseLibraryItem

Holds info about an album. cover should be a string containing a valid URL.

name instance-attribute

name: str

available_markets class-attribute instance-attribute

available_markets: list[str] | None = None

artists class-attribute instance-attribute

artists: list[Artist] | None = None

date class-attribute instance-attribute

date: str | None = None

tracks class-attribute instance-attribute

tracks: list['Song'] | None = None

track_count class-attribute instance-attribute

track_count: int | None = None

cover class-attribute instance-attribute

cover: str | None = None

upc class-attribute instance-attribute

upc: str | None = None

id class-attribute instance-attribute

id: str | None = None

url class-attribute instance-attribute

url: str | None = None

title property

title: str

str: Title of the album, including artist, in the format '[primary artist] - [album name]'.

full_title property

full_title: str

str: Full title of the album, including all artists, in the format [artist 1, artist 2, ...] - [album name].

all_artists property

all_artists: str

str: All artists' names, separated by a comma.

__hash__

__hash__()

Source code in src/downmixer/types/library.py

def __hash__(self):
    if self.id:
        return hash(self.id)
    else:
        return hash(self.full_title)

slug

slug() -> 'Album'

Returns self with sluggified text attributes.

Source code in src/downmixer/types/library.py

def slug(self) -> "Album":
    """Returns self with sluggified text attributes."""
    return Album(
        name=slugify(self.name),
        available_markets=self.available_markets,
        artists=[x.slug for x in self.artists] if self.artists else None,
        date=self.date,
        track_count=self.track_count,
        cover=self.cover,
        id=self.id,
        url=self.url,
    )

__str__

__str__()

Source code in src/downmixer/types/library.py

def __str__(self):
    return self.full_title

Song dataclass

Song(
    name: str,
    artists: list[Artist],
    duration: float = 0,
    album: Album | None = None,
    available_markets: list[str] | None = None,
    date: str | None = None,
    track_number: int | None = None,
    isrc: str | None = None,
    lyrics: str | None = None,
    id: str | None = None,
    url: str | None = None,
    cover: str | None = None,
)

Bases: BaseLibraryItem

Holds info about a song.

name instance-attribute

name: str

artists instance-attribute

artists: list[Artist]

duration class-attribute instance-attribute

duration: float = 0

album class-attribute instance-attribute

album: Album | None = None

available_markets class-attribute instance-attribute

available_markets: list[str] | None = None

date class-attribute instance-attribute

date: str | None = None

track_number class-attribute instance-attribute

track_number: int | None = None

isrc class-attribute instance-attribute

isrc: str | None = None

lyrics class-attribute instance-attribute

lyrics: str | None = None

id class-attribute instance-attribute

id: str | None = None

url class-attribute instance-attribute

url: str | None = None

cover class-attribute instance-attribute

cover: str | None = None

title property

title: str

str: Title of the song, including artist, in the format '[primary artist] - [song name]'.

full_title property

full_title: str

str: Full title of the song, including all artists, in the format [artist 1, artist 2, ...] - [song name].

all_artists property

all_artists: str

str: All artists' names, separated by a comma.

slug

slug() -> 'Song'

Returns self with sluggified text attributes.

Source code in src/downmixer/types/library.py

def slug(self) -> "Song":
    """Returns self with sluggified text attributes."""
    return Song(
        name=slugify(self.name),
        artists=[x.slug() for x in self.artists],
        album=self.album.slug() if self.album else None,
        available_markets=self.available_markets,
        date=self.date,
        duration=self.duration,
        track_number=self.track_number,
        isrc=self.isrc,
        id=self.id,
        url=self.url,
        lyrics=slugify(self.lyrics) if self.lyrics else None,
    )

__hash__

__hash__()

Source code in src/downmixer/types/library.py

def __hash__(self):
    if self.id:
        return hash(self.id)
    else:
        return hash(self.full_title)

__str__

__str__()

Source code in src/downmixer/types/library.py

def __str__(self):
    return self.full_title

Playlist dataclass

Playlist(
    name: str,
    description: str | None = None,
    tracks: list[Song] | None = None,
    images: list[dict] | None = None,
    fingerprint: str | None = None,
    id: str | None = None,
    url: str | None = None,
    owner: User | None = None,
)

Bases: BaseLibraryItem

Holds info about a playlist.

name instance-attribute

name: str

description class-attribute instance-attribute

description: str | None = None

tracks class-attribute instance-attribute

tracks: list[Song] | None = None

images class-attribute instance-attribute

images: list[dict] | None = None

fingerprint class-attribute instance-attribute

fingerprint: str | None = None

id class-attribute instance-attribute

id: str | None = None

url class-attribute instance-attribute

url: str | None = None

owner class-attribute instance-attribute

owner: User | None = None

title property

title: str

__hash__

__hash__()

Source code in src/downmixer/types/library.py

def __hash__(self):
    if self.id and self.fingerprint:
        return hash(self.id + self.fingerprint)
    elif self.id:
        return hash(self.id)
    else:
        return hash(self.title)

__str__

__str__()

Source code in src/downmixer/types/library.py

def __str__(self):
    return self.title