sublime_music.adapters.adapter_base module

class sublime_music.adapters.adapter_base.Adapter(config_store, data_directory)[source]

Bases: abc.ABC

Defines the interface for a Sublime Music Adapter.

All functions that actually retrieve data have a corresponding: can_-prefixed property (which can be dynamic) which specifies whether or not the adapter supports that operation at the moment.

Parameters

config_store (sublime_music.adapters.adapter_base.ConfigurationStore) –
data_directory (pathlib.Path) –

abstract __init__(config_store, data_directory)[source]

This function should be overridden by inheritors of Adapter and should be used to do whatever setup is required for the adapter.

This should do the bare minimum to get things set up, since this blocks the main UI loop. If you need to do longer initialization, use the initial_sync function.

Parameters

config – The adapter configuration. The keys of are the configuration parameter names as defined by the return value of the get_config_parameters function. The values are the actual value of the configuration parameter.
data_directory (pathlib.Path) – the directory where the adapter can store data. This directory is guaranteed to exist.
config_store (sublime_music.adapters.adapter_base.ConfigurationStore) –

property can_be_cached: bool

Whether or not this adapter can be used as the ground-truth adapter behind a caching adapter.

The default is True, since most adapters will want to take advantage of the built-in filesystem cache.

property can_be_ground_truth: bool: Whether or not this adapter can be used as a ground truth adapter.

property can_create_playlist: bool: Whether or not the adapter supports create_playlist.

property can_delete_playlist: bool: Whether or not the adapter supports delete_playlist.

property can_get_album: bool: Whether or not the adapter supports get_album.

property can_get_albums: bool: Whether or not the adapter supports get_albums.

property can_get_artist: bool: Whether or not the adapter supports get_aritst.

property can_get_artists: bool: Whether or not the adapter supports get_aritsts.

property can_get_cover_art_uri: bool: Whether or not the adapter supports get_cover_art_uri.

property can_get_directory: bool: Whether or not the adapter supports get_directory.

property can_get_genres: bool: Whether or not the adapter supports get_genres.

property can_get_ignored_articles: bool: Whether or not the adapter supports get_ignored_articles.

property can_get_play_queue: bool: Whether or not the adapter supports get_play_queue.

property can_get_playlist_details: bool: Whether or not the adapter supports get_playlist_details.

property can_get_playlists: bool: Whether or not the adapter supports get_playlist.

property can_get_song_details: bool: Whether or not the adapter supports get_song_details.

property can_get_song_file_uri: bool: Whether or not the adapter supports get_song_file_uri.

property can_get_song_rating: bool: Whether or not the adapter supports get_song_rating.

property can_get_song_stream_uri: bool: Whether or not the adapter supports get_song_stream_uri.

property can_save_play_queue: bool: Whether or not the adapter supports save_play_queue.

property can_scrobble_song: bool: Whether or not the adapter supports scrobble_song.

property can_search: bool: Whether or not the adapter supports search.

property can_set_song_rating: bool: Whether or not the adapter supports set_song_rating.

property can_update_playlist: bool: Whether or not the adapter supports update_playlist.

create_playlist(name, songs=None)[source]

Creates a playlist of the given name with the given songs.

Parameters

name (str) – The human-readable name of the playlist.
songs (Optional[Sequence[sublime_music.adapters.api_objects.Song]]) – A list of songs that should be included in the playlist.

Returns

A sublime_music.adapter.api_objects.Playlist object for the created playlist. If getting this information will incurr network overhead, then just return None.

Return type

Optional[sublime_music.adapters.api_objects.Playlist]

delete_playlist(playlist_id)[source]

Deletes the given playlist.

Parameters: playlist_id (str) – The human-readable name of the playlist.

get_album(album_id)[source]

Get the details for the given album ID.

Parameters: album_id (str) – The ID of the album to get the details for.
Returns: The :classs`sublime_music.adapters.api_objects.Album`
Return type: sublime_music.adapters.api_objects.Album

get_albums(query, sort_direction='ascending')[source]

Get a list of all of the albums known to the adapter for the given query.

Note

This request is not paged. You should do any page management to get all of the albums matching the query internally.

Parameters

query (sublime_music.adapters.adapter_base.AlbumSearchQuery) – An AlbumSearchQuery object representing the types of albums to return.
sort_direction (str) –

Returns

A list of all of the sublime_music.adapter.api_objects.Album objects known to the adapter that match the query.

Return type

Sequence[sublime_music.adapters.api_objects.Album]

get_artist(artist_id)[source]

Get the details for the given artist ID.

Parameters: artist_id (str) – The ID of the artist to get the details for.
Returns: The :classs`sublime_music.adapters.api_objects.Artist`
Return type: sublime_music.adapters.api_objects.Artist

get_artists()[source]

Get a list of all of the artists known to the adapter.

Returns: A list of all of the sublime_music.adapter.api_objects.Artist objects known to the adapter.
Return type: Sequence[sublime_music.adapters.api_objects.Artist]

abstract static get_configuration_form(config_store)[source]

This function should return a Gtk.Box that gets any inputs required from the user and uses the given config_store to store the configuration values.

The Gtk.Box must expose a signal with the name "config-valid-changed" which returns a single boolean value indicating whether or not the configuration is valid.

If you don’t want to implement all of the GTK logic yourself, and just want a simple form, then you can use the ConfigureServerForm class to generate a form in a declarative manner.

Parameters: config_store (sublime_music.adapters.adapter_base.ConfigurationStore) –
Return type: gi.overrides.Gtk.Box

get_cover_art_uri(cover_art_id, scheme, size)[source]

Get a URI for a given cover_art_id.

Parameters

cover_art_id (str) – The song, album, or artist ID.
scheme (str) – The URI scheme that should be returned. It is guaranteed that scheme will be one of the schemes returned by supported_schemes.
size (int) – The size of image to return. Denotes the max width or max height (whichever is larger).

Returns

The URI as a string.

Return type

str

get_directory(directory_id)[source]

Return a Directory object representing the song files and directories in the given directory. This may not make sense for your adapter (for example, if there’s no actual underlying filesystem). In that case, make sure to set can_get_directory to False.

Parameters: directory_id (str) – The directory to retrieve. If the special value "root" is given, the adapter should list all of the directories at the root of the filesystem tree.
Returns: A list of the sublime_music.adapter.api_objects.Directory and sublime_music.adapter.api_objects.Song objects in the given directory.
Return type: sublime_music.adapters.api_objects.Directory

get_genres()[source]

Get a list of the genres known to the adapter.

Returns: A list of all of the :classs`sublime_music.adapter.api_objects.Genre` objects known to the adapter.
Return type: Sequence[sublime_music.adapters.api_objects.Genre]

get_ignored_articles()[source]

Get the list of articles to ignore when sorting artists by name.

Returns: A set of articles (i.e. The, A, El, La, Los) to ignore when sorting artists.
Return type: Set[str]

get_play_queue()[source]

Returns the state of the play queue for this user. This could be used to restore the play queue from the cloud.

Returns: The cloud-saved play queue as a sublime_music.adapter.api_objects.PlayQueue object.
Return type: Optional[sublime_music.adapters.api_objects.PlayQueue]

get_playlist_details(playlist_id)[source]

Get the details for the given playlist_id. If the playlist_id does not exist, then this function should throw an exception.

Parameters: playlist_id (str) – The ID of the playlist to retrieve.
Returns: A sublime_music.adapter.api_objects.Play object for the given playlist.
Return type: sublime_music.adapters.api_objects.Playlist

get_playlists()[source]

Get a list of all of the playlists known by the adapter.

Returns: A list of all of the sublime_music.adapter.api_objects.Playlist objects known to the adapter.
Return type: Sequence[sublime_music.adapters.api_objects.Playlist]

get_song_details(song_id)[source]

Get the details for a given song ID.

Parameters: song_id (str) – The ID of the song to get the details for.
Returns: The sublime_music.adapters.api_objects.Song.
Return type: sublime_music.adapters.api_objects.Song

get_song_file_uri(song_id, schemes)[source]

Get a URI for a given song. This URI must give the full file.

Parameters

song_id (str) – The ID of the song to get a URI for.
schemes (Iterable[str]) – A set of URI schemes that can be returned. It is guaranteed that all of the items in schemes will be one of the schemes returned by supported_schemes.

Returns

The URI for the given song.

Return type

str

get_song_stream_uri(song_id)[source]

Get a URI for streaming the given song.

Parameters: song_id (str) – The ID of the song to get the stream URI for.
Returns: the stream URI for the given song.
Return type: str

abstract static get_ui_info()[source]

Returns: A UIInfo object.
Return type: sublime_music.adapters.adapter_base.UIInfo

abstract initial_sync()[source]: Perform any operations that are required to get the adapter functioning properly. For example, this function can be used to wait for an initial ping to come back from the server.

property is_networked: bool: Whether or not this adapter operates over the network. This will be used to determine whether or not some of the offline/online management features should be enabled.

abstract static migrate_configuration(config_store)[source]

This function allows the adapter to migrate its configuration.

Parameters: config_store (sublime_music.adapters.adapter_base.ConfigurationStore) –

abstract on_offline_mode_change(offline_mode)[source]

This function should be used to handle any operations that need to be performed when Sublime Music goes from online to offline mode or vice versa.

Parameters: offline_mode (bool) –

abstract property ping_status: bool

If the adapter is_networked, then this function should return whether or not the server can be pinged. This function must provide an answer instantly (it can’t actually ping the server). This function is called very often, and even a few milliseconds delay stacks up quickly and can block the UI thread.

One option is to ping the server every few seconds and cache the result of the ping and use that as the result of this function.

save_play_queue(song_ids, current_song_index=None, position=None)[source]

Save the current play queue to the cloud.

Parameters

song_ids (Sequence[str]) – A list of the song IDs in the queue.
current_song_index (Optional[int]) – The index of the song that is currently being played.
position (Optional[datetime.timedelta]) – The current position in the song.

scrobble_song(song)[source]

Scrobble the given song.

Params song: The sublime_music.adapters.api_objects.Song to scrobble.
Parameters: song (sublime_music.adapters.api_objects.Song) –

search(query)[source]

Return search results fro the given query.

Parameters: query (str) – The query string.
Returns: A sublime_music.adapters.api_objects.SearchResult object representing the results of the search.
Return type: sublime_music.adapters.api_objects.SearchResult

set_song_rating(song_id, rating)[source]

Rate the given song

Parameters

song_id (str) – A string which uniquely identifies the file (song)
rating (int | None) – The rating between 1 and 5 (inclusive), or None to remove the rating

abstract shutdown()[source]: This function is called when the app is being closed or the server is changing. This should be used to clean up anything that is necessary such as writing a cache to disk, disconnecting from a server, etc.

property supported_artist_query_types: Set[sublime_music.adapters.adapter_base.AlbumSearchQuery.Type]

A set of the query types that this adapter can service.

Returns: A set of AlbumSearchQuery.Type objects.

property supported_schemes: Iterable[str]

Specifies a collection of scheme names that can be provided by the adapter for a given resource (song or cover art) right now.

Examples of values that could be provided include http, https, file, or ftp.

update_playlist(playlist_id, name=None, comment=None, public=None, song_ids=None)[source]

Updates a given playlist. If a parameter is None, then it will be ignored and no updates will occur to that field.

Parameters

playlist_id (str) – The human-readable name of the playlist.
name (Optional[str]) – The human-readable name of the playlist.
comment (Optional[str]) – The playlist comment.
public (Optional[bool]) – This is very dependent on the adapter, but if the adapter has a shared/public vs. not shared/private playlists concept, setting this to True will make the playlist shared/public.
song_ids (Optional[Sequence[str]]) – A list of song IDs that should be included in the playlist.

Returns

A sublime_music.adapter.api_objects.Playlist object for the updated playlist.

Return type

sublime_music.adapters.api_objects.Playlist

class sublime_music.adapters.adapter_base.AlbumSearchQuery(type, year_range=(2020, 2030), genre=<sublime_music.adapters.adapter_base.AlbumSearchQuery._Genre object>, _strhash=None)[source]

Bases: object

Represents a query for getting albums from an adapter. The UI will request the albums in pages.

Fields:

AlbumSearchQuery.type – the query AlbumSearchQuery.Type
AlbumSearchQuery.year_range – (guaranteed to only exist if type is AlbumSearchQuery.Type.YEAR_RANGE) a tuple with the lower and upper bound (inclusive) of the album years to return
AlbumSearchQuery.genre – (guaranteed to only exist if the type is AlbumSearchQuery.Type.GENRE) return albums of the given genre

Parameters

type (sublime_music.adapters.adapter_base.AlbumSearchQuery.Type) –
year_range (Tuple[int, int]) –
genre (sublime_music.adapters.api_objects.Genre) –
_strhash (Optional[str]) –

Return type

None

class Type(value)[source]

Bases: enum.Enum

Represents a type of query. Use Adapter.supported_artist_query_types to specify what search types your adapter supports.

AlbumSearchQuery.Type.RANDOM – return a random set of albums
AlbumSearchQuery.Type.NEWEST – return the most recently added albums
AlbumSearchQuery.Type.RECENT – return the most recently played albums
AlbumSearchQuery.Type.STARRED – return only starred albums
AlbumSearchQuery.Type.ALPHABETICAL_BY_NAME – return the albums sorted alphabetically by album name
AlbumSearchQuery.Type.ALPHABETICAL_BY_ARTIST – return the albums sorted alphabetically by artist name
AlbumSearchQuery.Type.YEAR_RANGE – return albums in the given year range
AlbumSearchQuery.Type.GENRE – return songs of the given genre

ALPHABETICAL_BY_ARTIST = 6

ALPHABETICAL_BY_NAME = 5

FREQUENT = 2

GENRE = 8

NEWEST = 1

RANDOM = 0

RECENT = 3

STARRED = 4

YEAR_RANGE = 7

__init__(type, year_range=(2020, 2030), genre=<sublime_music.adapters.adapter_base.AlbumSearchQuery._Genre object>, _strhash=None)

Parameters

type (sublime_music.adapters.adapter_base.AlbumSearchQuery.Type) –
year_range (Tuple[int, int]) –
genre (sublime_music.adapters.api_objects.Genre) –
_strhash (Optional[str]) –

Return type

None

genre: sublime_music.adapters.api_objects.Genre = <sublime_music.adapters.adapter_base.AlbumSearchQuery._Genre object>

strhash()[source]

Returns a deterministic hash of the query as a string.

>>> AlbumSearchQuery(
...     AlbumSearchQuery.Type.YEAR_RANGE, year_range=(2018, 2019)
... ).strhash()
'275c58cac77c5ea9ccd34ab870f59627ab98e73c'
>>> AlbumSearchQuery(
...     AlbumSearchQuery.Type.YEAR_RANGE, year_range=(2018, 2020)
... ).strhash()
'e5dc424e8fc3b7d9ff7878b38cbf2c9fbdc19ec2'
>>> AlbumSearchQuery(AlbumSearchQuery.Type.STARRED).strhash()
'861b6ff011c97d53945ca89576463d0aeb78e3d2'

Return type: str

type: sublime_music.adapters.adapter_base.AlbumSearchQuery.Type

year_range: Tuple[int, int] = (2020, 2030)

exception sublime_music.adapters.adapter_base.CacheMissError(*args, partial_data=None)[source]

Bases: Exception

This exception should be thrown by caching adapters when the request data is not available or is invalid. If some of the data is available, but not all of it, the partial_data parameter should be set with the partial data. If the ground truth adapter can’t service the request, or errors for some reason, the UI will try to populate itself with the partial data returned in this exception (with the necessary error text to inform the user that retrieval from the ground truth adapter failed).

Parameters: partial_data (Any) –

__init__(*args, partial_data=None)[source]

Create a CacheMissError exception.

Parameters

args – arguments to pass to the BaseException base class.
partial_data (Optional[Any]) – the actual partial data for the UI to use in case of ground truth adapter failure.

class sublime_music.adapters.adapter_base.CachingAdapter(config, data_directory, is_cache=False)[source]

Bases: sublime_music.adapters.adapter_base.Adapter

Defines an adapter that can be used as a cache for another adapter.

A caching adapter sits “in front” of a non-caching adapter and the UI will attempt to retrieve the data from the caching adapter before retrieving it from the non-caching adapter. (The exception is when the UI requests that the data come directly from the ground truth adapter, in which case the cache will be bypassed.)

Caching adapters must be able to service requests instantly, or nearly instantly (in most cases, this means that the data must come directly from the local filesystem).

Parameters

config (dict) –
data_directory (pathlib.Path) –
is_cache (bool) –

class CachedDataKey(value)[source]

Bases: enum.Enum

An enumeration.

ALBUM = 'album'

ALBUMS = 'albums'

ALL_SONGS = 'all_songs'

ARTIST = 'artist'

ARTISTS = 'artists'

COVER_ART_FILE = 'cover_art_file'

DIRECTORY = 'directory'

EVERYTHING = 'everything'

GENRE = 'genre'

GENRES = 'genres'

IGNORED_ARTICLES = 'ignored_articles'

PLAYLISTS = 'get_playlists'

PLAYLIST_DETAILS = 'get_playlist_details'

SEARCH_RESULTS = 'search_results'

SONG = 'song'

SONG_FILE = 'song_file'

SONG_FILE_PERMANENT = 'song_file_permanent'

SONG_RATING = 'song_rating'

abstract __init__(config, data_directory, is_cache=False)[source]

This function should be overridden by inheritors of CachingAdapter and should be used to do whatever setup is required for the adapter.

Parameters

config (dict) – The adapter configuration. The keys of are the configuration parameter names as defined by the return value of the get_config_parameters function. The values are the actual value of the configuration parameter.
data_directory (pathlib.Path) – the directory where the adapter can store data. This directory is guaranteed to exist.
is_cache (bool) – whether or not the adapter is being used as a cache.

abstract delete_data(data_key, param)[source]

This function will be called if the adapter should delete some of its data. This should destroy the data. If the deleted data is requested, a CacheMissError should be thrown with no data in the partial_data field.

Parameters

data_key (sublime_music.adapters.adapter_base.CachingAdapter.CachedDataKey) – the type of data to be deleted.
params –
the parameters that uniquely identify the data to be invalidated. For example, with playlist details, this will be the playlist ID.

For the playlist list, this will be none since there are no parameters to that request.
param (Optional[str]) –

abstract get_cached_statuses(song_ids)[source]

Returns the cache statuses for the given list of songs. See the SongCacheStatus documentation for more details about what each status means.

Params songs: The songs to get the cache status for.
Returns: A dictionary of song ID to SongCacheStatus objects for each of the songs.
Parameters: song_ids (Sequence[str]) –
Return type: Dict[str, sublime_music.adapters.adapter_base.SongCacheStatus]

abstract ingest_new_data(data_key, param, data)[source]

This function will be called after the fallback, ground-truth adapter returns new data. This normally will happen if this adapter has a cache miss or if the UI forces retrieval from the ground-truth adapter.

Parameters

data_key (sublime_music.adapters.adapter_base.CachingAdapter.CachedDataKey) – the type of data to be ingested.
param (Optional[str]) –
a string that uniquely identify the data to be ingested. For example, with playlist details, this will be the playlist ID. If that playlist ID is requested again, the adapter should service that request, but it should not service a request for a different playlist ID.

For the playlist list, this will be none since there are no parameters to that request.
data (Any) – the data that was returned by the ground truth adapter.

abstract invalidate_data(data_key, param)[source]

This function will be called if the adapter should invalidate some of its data. This should not destroy the invalidated data. If invalid data is requested, a CacheMissError should be thrown, but the old data should be included in the partial_data field of the error.

Parameters

data_key (sublime_music.adapters.adapter_base.CachingAdapter.CachedDataKey) – the type of data to be invalidated.
params –
the parameters that uniquely identify the data to be invalidated. For example, with playlist details, this will be the playlist ID.

For the playlist list, this will be none since there are no parameters to that request.
param (Optional[str]) –

ping_status = True

class sublime_music.adapters.adapter_base.ConfigurationStore(**kwargs)[source]

Bases: dict

This defines an abstract store for all configuration parameters for a given Adapter.

MOCK = False

__init__(**kwargs)[source]

clone()[source]

Return type: sublime_music.adapters.adapter_base.ConfigurationStore

get_secret(key)[source]

Get the secret value in the store with the given key. This will retrieve the secret from whatever is configured as the underlying secret storage mechanism so you don’t have to deal with secret storage yourself.

Parameters: key (str) –
Return type: Optional[str]

persist_secrets()[source]

set_secret(key, value=None)[source]

Set the secret value of the given key in the store. This should be used for things such as passwords or API tokens. When persist_secrets is called, the secrets will be stored in whatever is configured as the underlying secret storage mechanism so you don’t have to deal with secret storage yourself.

Parameters

key (str) –
value (Optional[str]) –

class sublime_music.adapters.adapter_base.SongCacheStatus(value)[source]

Bases: enum.Enum

Represents the cache state of a given song.

SongCacheStatus.NOT_CACHED – indicates that the song is not cached on disk.
SongCacheStatus.CACHED – indicates that the song is cached on disk.
SongCacheStatus.PERMANENTLY_CACHED – indicates that the song is cached on disk and will not be deleted when the cache gets too big.
SongCacheStatus.DOWNLOADING – indicates that the song is being downloaded.
SongCacheStatus.CACHED_STALE – indicates that the song is cached on disk, but has been invalidated.

CACHED = 1

CACHED_STALE = 4

DOWNLOADING = 3

NOT_CACHED = 0

PERMANENTLY_CACHED = 2

class sublime_music.adapters.adapter_base.UIInfo(name: str, description: str, icon_basename: str, icon_dir: Optional[pathlib.Path] = None)[source]

Bases: object

Parameters

name (str) –
description (str) –
icon_basename (str) –
icon_dir (Optional[pathlib.Path]) –

Return type

None

__init__(name, description, icon_basename, icon_dir=None)

Parameters

name (str) –
description (str) –
icon_basename (str) –
icon_dir (Optional[pathlib.Path]) –

Return type

None

description: str

icon_basename: str

icon_dir: Optional[pathlib.Path] = None

icon_name()[source]

Return type: str

name: str

status_icon_name(status)[source]

Parameters: status (str) –
Return type: str