calliope.lastfm.history

Query listening history of a Last.fm user.

The load() function is the main entry point.

Data is synced locally using the Last.fm user.getRecentTracks API call. Due to API rate limiting, this is a slow operation for large datasets.

At the time of writing, Libre.fm also implements this function and can be queried by setting server='libre.fm', while Listenbrainz does not implement this API.

Module Contents

Classes

Store

PageToSync

Represents one page of last.fm history to be synced.

LastfmSyncOperation

Represents a last.fm history sync operation.

ListenHistory

Database of listening history for a given user.

Functions

escape_for_sql_identifier(name)

escape_for_lastfm_uri(name)

load(username, server = 'last.fm', retry_on_error = True, cachedir = None)

Load the listen history database for user.

Attributes

HistogramEntry

calliope.lastfm.history.escape_for_sql_identifier(name)
class calliope.lastfm.history.Store(file_path)
apply_schema(self)
commit(self)
cursor(self)
calliope.lastfm.history.escape_for_lastfm_uri(name)
class calliope.lastfm.history.PageToSync(of_number, nf_number)

Represents one page of last.fm history to be synced.

set_tracks(self, tracks)
class calliope.lastfm.history.LastfmSyncOperation(lastfm_history, total_pages, total_tracks, newest_tracks, sync_page_callback)

Bases: calliope.sync_operation.SyncOperation

Represents a last.fm history sync operation.

prepare(self, page_size)
pages(self)
process_page(self, page)
calliope.lastfm.history.HistogramEntry
class calliope.lastfm.history.ListenHistory(store, username, server, retry_on_error)

Database of listening history for a given user.

This should be created using the load() function.

You will probably first want to sync the data. As this is a slow operation, it is implemented as a generator so you can give feedback on the sync operation’s progress. Here’s a simple example:

op = lastfm_history.prepare_sync()
for i, page in enumerate(op.pages_to_sync):
    print(f"Syncing page {i}")
    lastfm_history.sync_page(page)
prepare_sync(self)

Queries last.fm for updates and returns a SyncOperation object.

annotate(self, item)
scrobbles(self)
listens(self)

Return individual scrobbles as a Calliope playlist.

artists(self, first_play_before=None, first_play_since=None, last_play_before=None, last_play_since=None, min_listens=1, show_listens_since=None)

Return artists from the lastfm history.

The following keyword arguments can be used to filter the returned results.

  • first_play_before: only artists who were played before the given date

  • first_play_since: only artists who were never played before the given date

  • last_play_before: only artists who were never played after the given date

  • last_play_since: only artists who were last played after the given date

  • min_listens: only artists who have N or more listens.

The following keyword arguments query extra information:

  • show_listens_since: number of listens since a given date

tracks(self, first_play_before=None, first_play_since=None, last_play_before=None, last_play_since=None, min_listens=1, show_listens_since=None)

Return tracks from the lastfm history.

The following keyword arguments can be used to filter the returned results.

  • first_play_before: only tracks which were played before the given date

  • first_play_since: only tracks which were never played before the given date

  • last_play_before: only tracks which were never played after the given date

  • last_play_since: only tracks which were last played after the given date

  • min_listens: only tracks which have N or more listens.

The following keyword arguments query extra information:

  • show_listens_since: number of listens since a given date

histogram(self, bucket='year')

Listen counts grouped per day/week/month/year.

calliope.lastfm.history.load(username, server='last.fm', retry_on_error=True, cachedir=None)

Load the listen history database for user.

Parameters
  • username (str) –

  • server (str) –

  • retry_on_error (bool) –

  • cachedir (pathlib.Path) –

Return type

ListenHistory