sublime_music.adapters.filesystem package

Module contents

class sublime_music.adapters.filesystem.FilesystemAdapter(config, data_directory, is_cache=False)[source]

Bases: sublime_music.adapters.adapter_base.CachingAdapter

Defines an adapter which retrieves its data from the local filesystem.

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

can_be_cached = False
can_be_ground_truth = False
can_get_album = True
can_get_albums = True
can_get_artist = True
property can_get_artists: bool

Whether or not the adapter supports get_aritsts.

can_get_cover_art_uri = True
can_get_directory = True
property can_get_genres: bool

Whether or not the adapter supports get_genres.

can_get_ignored_articles = True
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.

can_get_song_details = True
can_get_song_file_uri = True
can_get_song_rating = True
property can_set_song_rating: bool

Whether or not the adapter supports set_song_rating.

delete_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 – 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.

  • key (sublime_music.adapters.adapter_base.CachingAdapter.CachedDataKey) –

  • param (Optional[str]) –

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_all_albums()[source]
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(ignore_cache_miss=False)[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.

Parameters

ignore_cache_miss (bool) –

Return type

Sequence[sublime_music.adapters.api_objects.Artist]

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]

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_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(ignore_cache_miss=False)[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.

Parameters

ignore_cache_miss (bool) –

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

static get_ui_info()[source]
Returns

A UIInfo object.

Return type

sublime_music.adapters.adapter_base.UIInfo

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.

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.

invalidate_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 – 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.

  • key (sublime_music.adapters.adapter_base.CachingAdapter.CachedDataKey) –

  • param (Optional[str]) –

is_networked = False
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(_)[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

_ (bool) –

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

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.

supported_artist_query_types = {<Type.FREQUENT: 2>, <Type.RECENT: 3>, <Type.RANDOM: 0>, <Type.NEWEST: 1>, <Type.ALPHABETICAL_BY_NAME: 5>, <Type.GENRE: 8>, <Type.STARRED: 4>, <Type.ALPHABETICAL_BY_ARTIST: 6>, <Type.YEAR_RANGE: 7>}
supported_schemes = ('file',)