calliope.listenbrainz.listens

Query listening history of a Listenbrainz user.

The load() function is the main entry point.

Data is synced locally using the Listenbrainz listens API call.

Module Contents

Classes

Store

PageToSync

Represents one page of Listenbrainz history to be synced.

SyncOperation

Represents a Listenbrainz history sync operation."

History

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

Functions

maybe_set(item, key, value)

load(username[, cachedir])

Load the listen history database for user.

Attributes

HistogramEntry

class calliope.listenbrainz.listens.Store(file_path, retry_timeout=30)
apply_schema()
commit()
cursor()
class calliope.listenbrainz.listens.PageToSync

Represents one page of Listenbrainz history to be synced.

Pages are delimited by the ‘max_ts’ timestamp. The page will contain listens with timestamp < max_ts.

size: int
number: int
max_ts: int
min_ts: int
listens: [calliope.subprojects.pylistenbrainz.Listen]
set_listens(listens)
set_max_timestamp(max_ts)
set_min_timestamp(min_ts)
class calliope.listenbrainz.listens.SyncOperation(history, client)

Bases: calliope.sync_operation.SyncOperation

Represents a Listenbrainz history sync operation.”

We process remote listens from newest to oldest, using the max_ts parameter to control paging. As of January 2022 this is the only method that the Listenbrainz API makes possible.

We assume that remote listens are never deleted or modified. This is untrue but makes the sync more efficent. If existing remote listens have changed, delete the local cache completely to cause a full resync.

The initial sync may be interrupted so we handle two possibilities each time we sync:

  • there are remote listens newer than everything in our cache.

  • there are remote listens older than everything in our cache.

Parameters:

client (calliope.subprojects.pylistenbrainz.ListenBrainz) –

prepare(page_size)

Check stored data against remote.

Return type:

[PageToSync]

process_page(page)
pages()
calliope.listenbrainz.listens.maybe_set(item, key, value)
calliope.listenbrainz.listens.HistogramEntry
class calliope.listenbrainz.listens.History(username=None, 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 = listen_history.prepare_sync()
for i, page in enumerate(op.pages_to_sync):
    print(f"Syncing page {i}")
    listen_history.sync_page(page)

This class implements the calliope.interface.ListenHistoryProvider interface.

prepare_sync(page_size=None)

Query ListenBrainz for updates and returns a SyncOperation object.

intern_listen(listen)
annotate(item)
listens()

Return individual listens 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 Listenbrainz 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 listenbrainz 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.listenbrainz.listens.load(username, cachedir=None)

Load the listen history database for user.

Parameters:
  • username (str) –

  • cachedir (pathlib.Path) –

Return type:

History