`library.py` file¶

Every provider implementing the SupportsLibrary or SupportsMetadata protocol should include a library.py file containing adapter classes that convert provider API data into Downmixer's internal data models.

Purpose¶

Different music services return data in different formats. The library.py file bridges this gap by:

Defining subclasses of the base library types
Overriding the from_provider method to parse API-specific data structures
Returning instances of the base types (not the subclass)

Required Classes¶

The following BaseLibraryItem subclasses should be overridden as needed:

Class	Description
`Artist`	Artist metadata (name, images, genres)
`Album`	Album metadata (name, artists, cover, date)
`Song`	Song metadata (name, artists, album, duration, ISRC)
`Playlist`	Playlist metadata (name, tracks, owner)
`User`	User metadata (name, handle)

Methods to Override¶

`from_provider`¶

The from_provider class method is the primary method to override. It receives raw API data and returns an instance of the base library type.

class SpotifyArtist(Artist):
    @classmethod
    def from_provider(cls, data: dict, extra_data: dict = None) -> Artist:
        return Artist(
            name=data["name"],
            images=data.get("images"),
            id=data["uri"],
            url=data["external_urls"]["spotify"],
        )

`from_provider_list`¶

Override from_provider_list when the API returns lists in a non-standard format (e.g., wrapped in additional objects):

@classmethod
def from_provider_list(cls, data: list, extra_data: dict = None) -> list[Song]:
    # Handle Spotify's {"track": {...}} wrapper
    return [cls.from_provider(x["track"], extra_data) for x in data]

The default implementation simply iterates and calls from_provider on each item.

Example¶

See the bundled providers for complete implementations:

See the types reference for complete API documentation of the base classes.

library.py file¶