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

.. py:module:: calliope.lastfm

.. autoapi-nested-parse::

   Access data from `Last.fm <https://www.last.fm>`_.

   This module uses `lastfmclient <https://github.com/jakubroztocil/lastfmclient>`_
   to access the `Last.fm API <https://www.last.fm/api>`_, and requires a Last.fm
   API key (see below). Note that the :mod:`.history` submodule does not require an
   API key.

   Authentication
   --------------

   API keys are available `on request <https://www.last.fm/api/account/create>`_
   and existing keys can be viewed `here <https://www.last.fm/api/accounts>`_.

   Credentials should be provided to the :class:`.LastfmContext` by
   with args ``lastfm.client-id`` and ``lastfm.client-secret``.

   Additionally ``lastfm.redirect-uri`` should be passed. Any URL should work.
   The first time :func:`.LastfmContext.authenticate` is called,
   it will open a browser window to authorize with Last.fm, and will return the
   access token by asking to paste the redirected URI::

       $ cpe lastfm --user ssam top-artists

           User authentication requires interaction with your
           web browser. Once you enter your credentials and
           give authorization, you will be redirected to
           a url.  Paste that url you were directed to to
           complete the authorization.

       Opened http://www.last.fm/api/auth/?api_key=275fdd45ac3cd224b3501be6444ff679&cb=http://afuera.me.uk/ in your browser

       Enter the URL you were redirected to:

   The authorization code will be saved in the cache so future API access will
   work without a prompt, until the cached code expires.

   The credentials can be provided in ``calliope.conf`` as follows:

       [lastfm]
       client_id = <API Key>
       client_secret = <Shared Secret>
       redirect_uri = http://...

   Caching
   -------

   The :mod:`calliope.cache` module is used to cache requests.



Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   history/index.rst
   lastexport/index.rst


Package Contents
----------------

Classes
~~~~~~~

.. autoapisummary::

   calliope.lastfm.LastfmContext



Functions
~~~~~~~~~

.. autoapisummary::

   calliope.lastfm.prompt_for_user_token
   calliope.lastfm.annotate_tags
   calliope.lastfm.similar_artists
   calliope.lastfm.similar_tracks
   calliope.lastfm.top_artists



.. py:class:: LastfmContext(user=None, client_id=None, client_secret=None, redirect_uri=None)


   
   Context for accessing Last.fm API.

   The :meth:`authenticate` function must be called to obtain a
   :class:`lastfmclient.LastfmClient` object.

   :param user: Username to use in requests
   :param client_id: API client
   :param client_secret: API key
   :param redirect_uri: Authentication return URI

   .. py:method:: authenticate()



.. py:function:: prompt_for_user_token(username, client_id=None, client_secret=None, redirect_uri=None)

   Prompt user to obtain authorization token.


.. py:function:: annotate_tags(context, playlist)


.. py:function:: similar_artists(context, count, artist_name)

   Given an artist, return similar artists.


.. py:function:: similar_tracks(context, count, artist_name, track_name)

   Given a track artist and title, return similar tracks.


.. py:function:: top_artists(context, count, time_range, include)

   Return top artists for the given user.