:py:mod:`calliope.lastfm.history`
=================================

.. py:module:: calliope.lastfm.history

.. autoapi-nested-parse::

   Query listening history of a `Last.fm <https://last.fm>`_ user.

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

   Data is synced locally using the Last.fm `user.getRecentTracks <https://www.last.fm/api/show/user.getRecentTracks>`_
   API call. Due to API rate limiting, this is a slow operation for large datasets.

   At the time of writing, `Libre.fm <https://libre.fm>`_ also implements this
   function and can be queried by setting ``server='libre.fm'``, while
   `Listenbrainz <https://listenbrainz.org>`_ does not implement this API.



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

Classes
~~~~~~~

.. autoapisummary::

   calliope.lastfm.history.Store
   calliope.lastfm.history.PageToSync
   calliope.lastfm.history.LastfmSyncOperation
   calliope.lastfm.history.ListenHistory



Functions
~~~~~~~~~

.. autoapisummary::

   calliope.lastfm.history.escape_for_sql_identifier
   calliope.lastfm.history.escape_for_lastfm_uri
   calliope.lastfm.history.load



Attributes
~~~~~~~~~~

.. autoapisummary::

   calliope.lastfm.history.HistogramEntry


.. py:function:: escape_for_sql_identifier(name)


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


   .. py:method:: apply_schema()


   .. py:method:: begin_transaction()


   .. py:method:: commit_transaction()


   .. py:method:: cursor()



.. py:function:: escape_for_lastfm_uri(name)


.. py:class:: PageToSync(of_number, nf_number)


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

   .. py:method:: set_tracks(tracks)



.. py:class:: LastfmSyncOperation(lastfm_history, total_pages, total_tracks, newest_tracks, sync_page_callback)


   Bases: :py:obj:`calliope.sync_operation.SyncOperation`

   Represents a last.fm history sync operation.

   .. py:method:: prepare(page_size)


   .. py:method:: pages()


   .. py:method:: process_page(page)



.. py:data:: HistogramEntry

   

.. py:class:: ListenHistory(username=None, server='last.fm', retry_on_error=True, cachedir=None)


   Bases: :py:obj:`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 :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 = 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 :class:`calliope.interface.ListenHistoryProvider` interface.

   .. py:method:: prepare_sync()

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


   .. py:method:: annotate(item)


   .. py:method:: scrobbles()


   .. py:method:: listens()

      Return individual scrobbles 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 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



   .. 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 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


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

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



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

   Load the listen history database for `user`.