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

Interface for modules that provide a person's listening history.

Functions

escape_for_sql_identifier(name)

escape_for_lastfm_uri(name)

load(username[, server, retry_on_error, cachedir])

Load the listen history database for user.

Attributes

HistogramEntry

calliope.lastfm.history.escape_for_sql_identifier(name)
class calliope.lastfm.history.Store(file_path, retry_timeout=30)
apply_schema()
begin_transaction()
commit_transaction()
cursor()
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(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(page_size)
pages()
process_page(page)
calliope.lastfm.history.HistogramEntry
class calliope.lastfm.history.ListenHistory(username=None, server='last.fm', retry_on_error=True, cachedir=None)

Bases: calliope.interface.ListenHistoryProvider

Interface for modules that provide a person’s listening history.

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)

This class implements the calliope.interface.ListenHistoryProvider interface.

prepare_sync()

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

annotate(item)
scrobbles()
listens()

Return individual scrobbles as a Calliope playlist.

artists(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(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(bucket='year')

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

calliope.lastfm.history.load(username, server=None, 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