protocols

Protocol definitions for music provider capabilities.

This module defines Protocol classes that represent different capabilities a music provider can implement. Providers can implement one or more of these protocols to indicate what features they support (metadata fetching or library access).

Audio download and lyrics protocols live in the consuming application (e.g. ripper), as they depend on application-level types like LocalFile.

CLASS	DESCRIPTION
SupportsMetadata	Protocol for providers that can search and fetch music metadata.
SupportsLibrary	Protocol for providers that can access a user's music library.

SupportsMetadata

Bases: Protocol

Protocol for providers that can search and fetch music metadata.

Implement this protocol to enable searching for music and retrieving detailed information about songs, albums, artists, playlists, and users from a provider.

search

search(
    query: str,
    accepted_types: list[ResourceType] = None,
    compare_with: Song = None,
) -> list[SearchResult]

Search for music resources matching the given query.

PARAMETER	DESCRIPTION
query	The search query string. TYPE: str
accepted_types	Optional list of resource types to filter results. If None, all resource types are included. TYPE: list[ResourceType] DEFAULT: None
compare_with	Optional Song object to match and sort results from. TYPE: Song DEFAULT: None

RETURNS	DESCRIPTION
list[SearchResult]	A list of SearchResult objects matching the query.

Source code in src/downmixer/providers/protocols.py

def search(
    self,
    query: str,
    accepted_types: list[ResourceType] = None,
    compare_with: Song = None,
) -> List[SearchResult]:
    """Search for music resources matching the given query.

    Args:
        query: The search query string.
        accepted_types: Optional list of resource types to filter results.
            If None, all resource types are included.
        compare_with: Optional Song object to match and sort results from.

    Returns:
        A list of SearchResult objects matching the query.
    """
    raise NotImplementedError

fetch_song abstractmethod

fetch_song(id: str) -> Song

Fetch detailed information about a song.

PARAMETER	DESCRIPTION
id	The provider-specific identifier for the song. TYPE: str

RETURNS	DESCRIPTION
Song	A Song object containing the song's metadata.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_song(self, id: str) -> Song:
    """Fetch detailed information about a song.

    Args:
        id: The provider-specific identifier for the song.

    Returns:
        A Song object containing the song's metadata.
    """
    raise NotImplementedError

fetch_album abstractmethod

fetch_album(id: str) -> Album

Fetch detailed information about an album.

PARAMETER	DESCRIPTION
id	The provider-specific identifier for the album. TYPE: str

RETURNS	DESCRIPTION
Album	An Album object containing the album's metadata.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_album(self, id: str) -> Album:
    """Fetch detailed information about an album.

    Args:
        id: The provider-specific identifier for the album.

    Returns:
        An Album object containing the album's metadata.
    """
    raise NotImplementedError

fetch_artist abstractmethod

fetch_artist(id: str) -> Artist

Fetch detailed information about an artist.

PARAMETER	DESCRIPTION
id	The provider-specific identifier for the artist. TYPE: str

RETURNS	DESCRIPTION
Artist	An Artist object containing the artist's metadata.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_artist(self, id: str) -> Artist:
    """Fetch detailed information about an artist.

    Args:
        id: The provider-specific identifier for the artist.

    Returns:
        An Artist object containing the artist's metadata.
    """
    raise NotImplementedError

fetch_playlist abstractmethod

fetch_playlist(id: str) -> Playlist

Fetch detailed information about a playlist.

PARAMETER	DESCRIPTION
id	The provider-specific identifier for the playlist. TYPE: str

RETURNS	DESCRIPTION
Playlist	A Playlist object containing the playlist's metadata.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_playlist(self, id: str) -> Playlist:
    """Fetch detailed information about a playlist.

    Args:
        id: The provider-specific identifier for the playlist.

    Returns:
        A Playlist object containing the playlist's metadata.
    """
    raise NotImplementedError

fetch_user abstractmethod

fetch_user(id: str) -> User

Fetch detailed information about a user.

PARAMETER	DESCRIPTION
id	The provider-specific identifier for the user. TYPE: str

RETURNS	DESCRIPTION
User	A User object containing the user's profile information.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_user(self, id: str) -> User:
    """Fetch detailed information about a user.

    Args:
        id: The provider-specific identifier for the user.

    Returns:
        A User object containing the user's profile information.
    """
    raise NotImplementedError

fetch_list_songs abstractmethod

fetch_list_songs(id: str) -> list[Song]

Retrieves the all the songs from a playlist or album as a list. Args: id (str): A string containing a valid ID for the provider.

RETURNS	DESCRIPTION
list[Song]	All songs in the object.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_list_songs(self, id: str) -> list[Song]:
    """Retrieves the all the songs from a playlist or album as a list.
    Args:
        id (str): A string containing a valid ID for the provider.

    Returns:
        All songs in the object.
    """
    raise NotImplementedError

SupportsLibrary

Bases: Protocol

Protocol for providers that can access a user's music library.

Implement this protocol to enable fetching the authenticated user's saved playlists, albums, songs, and followed artists from a provider.

fetch_user_playlists abstractmethod

fetch_user_playlists() -> list[Playlist]

Retrieves the all the user's playlists in a list.

RETURNS	DESCRIPTION
list[Playlist]	User's playlists as a list of Playlist objects.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_user_playlists(self) -> list[Playlist]:
    """Retrieves the all the user's playlists in a list.

    Returns:
        User's playlists as a list of Playlist objects.
    """
    raise NotImplementedError

fetch_user_albums abstractmethod

fetch_user_albums() -> list[Album]

Retrieves the all the user's saved albums in a list.

RETURNS	DESCRIPTION
list[Album]	User's albums as a list of Album objects.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_user_albums(self) -> list[Album]:
    """Retrieves the all the user's saved albums in a list.

    Returns:
        User's albums as a list of Album objects.
    """
    raise NotImplementedError

fetch_user_songs abstractmethod

fetch_user_songs() -> list[Song]

Retrieves the all the user's liked/saved songs in a list (for example, on Spotify, should return user's saved tracks).

RETURNS	DESCRIPTION
list[Song]	User's playlists as a list of Playlist objects.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_user_songs(self) -> list[Song]:
    """Retrieves the all the user's liked/saved songs in a list (for example, on Spotify, should return user's
    saved tracks).

    Returns:
        User's playlists as a list of Playlist objects.
    """
    raise NotImplementedError

fetch_user_artists abstractmethod

fetch_user_artists() -> list[Artist]

Retrieves the all the user's followed artists in a list.

RETURNS	DESCRIPTION
list[Artist]	User's followed artists as a list of artist names.

Source code in src/downmixer/providers/protocols.py

@abstractmethod
def fetch_user_artists(self) -> list[Artist]:
    """Retrieves the all the user's followed artists in a list.

    Returns:
        User's followed artists as a list of artist names.
    """
    raise NotImplementedError