:py:mod:`calliope.listenbrainz.listens`
=======================================

.. py:module:: calliope.listenbrainz.listens

.. autoapi-nested-parse::

   Query listening history of a `Listenbrainz <listenbrainz.org/>`_ user.

   The :func:`load` function is the main entry point.

   Data is synced locally using the Listenbrainz
   `listens <https://listenbrainz.readthedocs.io/en/production/dev/api/#get--1-user-(user_name)-listens>`_
   API call.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   calliope.listenbrainz.listens.Store
   calliope.listenbrainz.listens.PageToSync
   calliope.listenbrainz.listens.SyncOperation
   calliope.listenbrainz.listens.History



Functions
~~~~~~~~~

.. autoapisummary::

   calliope.listenbrainz.listens.maybe_set
   calliope.listenbrainz.listens.load



Attributes
~~~~~~~~~~

.. autoapisummary::

   calliope.listenbrainz.listens.HistogramEntry


.. py:class:: Store(file_path, retry_timeout=30)

   .. py:method:: apply_schema()


   .. py:method:: commit()


   .. py:method:: cursor()



.. py:class:: 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.

   .. py:attribute:: size
      :annotation: :int

      

   .. py:attribute:: number
      :annotation: :int

      

   .. py:attribute:: max_ts
      :annotation: :int

      

   .. py:attribute:: min_ts
      :annotation: :int

      

   .. py:attribute:: listens
      :annotation: :[calliope.subprojects.pylistenbrainz.Listen]

      

   .. py:method:: set_listens(listens)


   .. py:method:: set_max_timestamp(max_ts)


   .. py:method:: set_min_timestamp(min_ts)



.. py:class:: SyncOperation(history, client)

   Bases: :py:obj:`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.


   .. py:method:: prepare(page_size)

      Check stored data against remote.


   .. py:method:: process_page(page)


   .. py:method:: pages()



.. py:function:: maybe_set(item, key, value)


.. py:data:: HistogramEntry
   

   

.. py:class:: History(store, username)

   
   Database of listening history for a given user.

   This should be created using the :func:`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)

   .. py:method:: prepare_sync(page_size=None)

      Query ListenBrainz for updates and returns a SyncOperation object.


   .. py:method:: intern_listen(listen)


   .. py:method:: annotate(item)


   .. py:method:: listens()

      Return individual listens as a Calliope playlist.


   .. py:method:: 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



   .. py:method:: 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


   .. py:method:: histogram(bucket='year')

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



.. py:function:: load(username, cachedir = None)

   Load the listen history database for `user`.