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
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

staticmethod(function) -> method

Convert a function to be a static method.

A static method does not receive an implicit first argument. To declare a static method, use this idiom:

class C:

@staticmethod def f(arg1, arg2, …):

It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). Both the class and the instance are ignored, and neither is passed implicitly as the first argument to the method.

Static methods in Python are similar to those found in Java or C++. For a more advanced concept, see the classmethod builtin.

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_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.

Whether or not the adapter supports search.

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
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
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) –

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

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:

Parameters
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.

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
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
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'
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.

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: Union[pathlib.Path, NoneType] = None)[source]

Bases: object

Parameters
Return type

None

__init__(name, description, icon_basename, icon_dir=None)
Parameters
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