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¶
Represents one page of Listenbrainz history to be synced. |
|
Represents a Listenbrainz history sync operation." |
|
Interface for modules that provide a person's listening history. |
Functions¶
|
|
|
Load the listen history database for user. |
Attributes¶
- 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:
- 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.